grpc-gateway不是http框架替代品，必须配合独立grpc server使用；单独启动会报connection refused或503；proto需导入annotations.proto和http.proto，protoc命令须含--grpc-gateway_out，生成的.pb.gw.go须被import，handler须注册到独立runtime.servemux而非gin/echo。
grpc-gateway 不是 HTTP 框架替代品，它必须和独立运行的 gRPC server 配合使用；单独启动 gateway 会直接报 connection refused 或 503。
proto 文件里 google.api.http 注解不生效？检查 import 和生成命令
注解本身不触发任何运行时逻辑，只在 protoc 生成阶段被读取。漏掉任一依赖都会导致 service.pb.gw.go 为空或缺失路由绑定：
- proto 中必须显式写两行：
import "google/api/annotations.proto";和import "google/api/http.proto"; -
protoc命令必须包含--grpc-gateway_out参数，例如：protoc --grpc-gateway_out=paths=source_relative:. your_service.proto - 生成的
service.pb.gw.go文件必须被 Go 项目 import（哪怕只是 blank import：_ "your/project/gen"），否则 handler 根本不会编译进二进制
注册 handler 时不能塞进 Gin/Echo 路由树
runtime.ServeMux 是完整、自包含的 HTTP handler，不是中间件。把它当普通 handler 函数塞进第三方框架，会丢失 method/path 匹配能力，所有请求 fallback 到 404：
- 错误写法：
r.POST("/v1/echo", gwMux.ServeHTTP) - 正确写法：调用
RegisterXXXHandlerFromEndpoint(ctx, gwMux, "127.0.0.1:9090", opts)后，直接用http.ListenAndServe(":8080", gwMux) - 若需共用端口（如 8080 同时响应 REST 和 gRPC），必须用
h2c.NewHandler(grpcServer, &http.Server{Handler: gwMux})做 fallback，不能起两个ListenAndServe
路径参数和 body 映射失败的常见原因
gateway 对字段名、类型、嵌套层级做严格字面匹配，不自动转换也不报错，静默丢弃是常态：
-
get: "/v1/users/{id}"要求 request message 中必须有字段int32 id = 1;，字段名大小写、下划线必须完全一致 -
body: "*"表示整个 JSON body 映射到 message；若写成body: "user.name"，则只提取user.name路径下的值，且user字段必须是嵌套 message 类型 - query 参数（如
?page=1&size=10）也必须在 request message 中定义对应字段，否则不解析、不传入
最易被忽略的是 context 生命周期 —— RegisterXXXHandlerFromEndpoint 传入的 ctx 若已 cancel（比如来自 context.WithTimeout 且超时），注册会静默失败，gateway 启动后所有请求返回 503，日志无提示。务必确保该 ctx 至少存活到注册完成。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
