gRPC-Gateway需三步：先用protoc生成gRPC stub（--go_out和--go-grpc_out），再单独运行gateway命令（显式指定third_party/googleapis路径），最后在ListenAndServe前调用RegisterXXXHandlerFromEndpoint注册handler。
gRPC-Gateway 不是“一键”工具，但只要三步走对、两处不漏，HTTP 接口就能跑起来——关键在 protoc 命令顺序、注解写法和 handler 注册时机。
protoc 命令必须分两次执行，不能合并
很多人想用一条 protoc 命令同时生成 gRPC stub 和 gateway 代码，结果报错找不到 google/api/annotations.proto 或生成的 .pb.gw.go 文件为空。这是因为：grpc-gateway 插件只负责生成 HTTP 路由逻辑，不参与 protobuf 结构定义；而 go 和 go-grpc 插件才真正生成 message 和 service 接口。
- 先运行 gRPC 相关生成命令（含
--go_out和--go-grpc_out），确保.pb.go和_grpc.pb.go存在 - 再单独运行 gateway 命令：
protoc -I . -I $GOPATH/pkg/mod/github.com/grpc-ecosystem/grpc-gateway@v2.15.2/third_party/googleapis/ --grpc-gateway_out=. --grpc-gateway_opt logtostderr=true your_service.proto - 路径中的
third_party/googleapis必须显式指定，否则google.api.http注解无法解析 - 如果用
buf，需在buf.gen.yaml中分开配置plugin: grpc和plugin: grpc-gateway，不能混在一个插件块里
google.api.http 注解写错一个字符，HTTP 就 404
注解不是装饰，是 gateway 的路由源。它直接决定 HTTP 方法、路径、参数绑定方式，且大小写、引号、字段名都必须严格匹配 Protobuf message 定义。
-
post:"/v1/users"表示整个请求体映射到入参 message，此时body: "*"是必需的；漏写会返回400 Bad Request，不是 404 -
get:"/v1/users/{id}"要求 message 中存在字段string id = 1;；若字段名是user_id却写成{id}，gateway 解析失败，直接 404 - 路径中带 query 参数（如
get:"/v1/users?status={status}"）时，status字段必须是 message 的一级字段，嵌套结构不支持自动展开 - 不要用
option (google.api.http) = { post: "/v1/foo" };这种换行缩进写法——某些旧版 protoc 会静默忽略整条注解
RegisterXXXHandlerFromEndpoint 必须在 ListenAndServe 前调用
生成的 .pb.gw.go 文件里只有一堆未注册的 handler 函数，不显式挂载，http.ServeMux 根本看不到任何路由。这不是配置问题，是根本没加载。
- 必须在
http.ListenAndServe或http.Serve之前调用RegisterYourServiceHandlerFromEndpoint -
ctx不能是短生命周期上下文（例如context.WithTimeout(ctx, 100ms)），注册过程可能耗时几十毫秒，超时会导致静默失败 -
endpoint必须指向已启动的 gRPC 服务地址，如"localhost:9090"；写成"127.0.0.1:9090"在启用了 mTLS 或自定义 DNS 的环境里可能连不上 - 别把 gateway 的
runtime.NewServeMux()塞进 Gin/Echo 的某个子路由（比如r.POST("/api", mux.ServeHTTP)），这会破坏 gateway 内部的 path 解析和 query/body 提取逻辑
HTTP 接口返回空 JSON 或 panic，大概率是响应结构没导出
gateway 将 gRPC response message 序列化为 JSON 时，依赖 Go 的 json 包反射机制。如果 message 字段未导出（小写开头）、或类型不支持 JSON 编码（如 func、chan、未实现 json.Marshaler 的自定义类型），就会返回空对象或 panic。
- Protobuf 生成的 struct 字段名默认首字母大写，但如果你手动改了
go_tag注释（如json:"user_id"），要确认对应字段确实可被 json 包访问 - 避免在 response message 中嵌入非基本类型：比如
map[string]interface{}可能导致序列化失败，改用明确字段的 struct 更稳妥 - 如果用了
google.protobuf.Timestamp，需确保已 import"google.golang.org/protobuf/types/known/timestamppb"，且 gateway 版本 ≥ v2.10.0（旧版对 timestamp 处理有 bug） - 开启 gateway 日志（
--grpc-gateway_opt logtostderr=true）后，panic 会打印在 stderr，但 HTTP 响应仍是 500 空体——这是常见盲区
最常被跳过的其实是 endpoint 连通性验证和 handler 注册顺序。哪怕 proto 写得再标准、protoc 命令跑得再顺，这两点任一缺失，HTTP 接口就只是个摆设。
