RegisterXXXHandlerFromEndpoint未调用会导致HTTP接口全部404，因其非中间件需显式注册；endpoint须指向运行中的gRPC服务，ctx不可取消，proto注解生效需完整工具链与正确生成步骤。
RegisterXXXHandlerFromEndpoint 没调用，HTTP 接口就完全不工作
这是最常见、也最容易被忽略的致命问题：gRPC-Gateway 不是中间件，它不会自动挂载到 HTTP 路由上。你生成了 service.pb.gw.go，但如果不显式注册 handler，http.ListenAndServe 启动的服务器对所有 REST 路径都返回 404。
- 必须在
main()中调用RegisterXXXHandlerFromEndpoint（XXX 是你的服务名，比如RegisterGreeterHandlerFromEndpoint） - 传入的
ctx不能是已 cancel 的上下文（例如用context.WithTimeout(ctx, 1s)后直接传入——超时后注册就失败） -
endpoint必须指向一个**正在运行中**的 gRPC server 地址，如"localhost:9090"；写成"127.0.0.1:9090"也可能因 DNS 解析或 TLS 配置失败 - 别把
runtime.NewServeMux()塞进 Gin/Echo 的路由里，比如r.POST("/v1/hello", mux.ServeHTTP)—— 这会绕过 gateway 内部的 method/path 匹配逻辑，导致 query 参数丢失、body 解析失败
proto 文件里写了 http 注解，但 curl 仍 404？检查三个硬性条件
注解只是声明，不是魔法。它生效的前提是工具链完整、路径正确、生成动作到位。
-
import "google/api/annotations.proto"和import "google/api/http.proto"必须存在，且路径可被protoc -I找到（通常要加-I $GOPATH/pkg/mod/github.com/grpc-ecosystem/grpc-gateway/v2@latest/third_party/googleapis） -
protoc命令必须显式包含--grpc-gateway_out参数，例如：protoc --grpc-gateway_out=logtostderr=true:. service.proto；漏掉这步，service.pb.gw.go根本不会生成 - 路径变量（如
get: "/v1/hello/{name}"）能自动绑定字段，但 query 参数（如?limit=10）必须在 proto 中显式声明为字段，并设body: "*"或绑定到具体字段，否则 gateway 不解析也不透传
能不能让 gRPC 和 HTTP 共享一个端口？能，但不是“监听同一个端口”那么简单
直接起两个 http.ListenAndServe 或两个 grpc.NewServer().Serve 会争抢 socket，出现随机 503 或连接拒绝。真正可行的是用 http.Server.Handler 做协议分发。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 核心是使用
golang.org/x/net/http2+ 自定义http.Handler：HTTP/1.1 流量交给 gateway 的runtime.ServeMux，HTTP/2 流量交给 gRPC server - 推荐用
h2c.NewHandler包裹 gRPC server，并 fallback 到 gateway mux，而不是自己手写协议嗅探逻辑 - 如果启用 HTTPS，gRPC 仍走 HTTP/2 over TLS，gateway 走 HTTP/1.1 over TLS —— 大多数现代客户端没问题，但某些嵌入式设备或老版 iOS WebKit 可能拒绝 JSON 响应中的空数组/空对象（因 gateway 默认用
protojson编码，与原生 gRPC 的二进制行为不一致）
JSON 编码结果和前端对不上？别怪 gateway，先看 protojson 配置
gateway 默认用 google.golang.org/protobuf/encoding/protojson，它的字段名策略、null 处理、时间格式都严格遵循 proto 定义，和前端习惯常有偏差。
立即学习“go语言免费学习笔记（深入）”；
- 默认字段名是 snake_case（如
user_id），若要 camelCase，需在runtime.NewServeMux初始化时传入runtime.WithMarshalerOption并配置protojson.MarshalOptions{UseProtoNames: false} - 空值默认省略（omitzero），若需保留
null，得设EmitUnpopulated: true - time 类型默认序列化为 RFC 3339 字符串（带时区），但有些前端库只认 Unix timestamp，这时得在 message 中改用
int64字段，或自定义MarshalJSON
这些细节不改，前端拿到 {"user_id": null} 却期望 {"userId": ""}，排查时容易误判为路由或业务逻辑问题。
