grpc-gateway是需手动组装的反向代理而非自动转换中间件；必须显式调用registerxxxhandlerfromendpoint注册路由、启动独立runtime.servemux，且endpoint须指向已运行的grpc服务，否则接口全404或503。
grpc-gateway 不是“自动把 REST 转成 gRPC”的魔法中间件，它是一个需要你手动组装、显式注册、严格对齐参数的反向代理。不写对 RegisterXXXHandlerFromEndpoint，不启动独立 runtime.ServeMux，所有接口都会 404；endpoint 指向一个没起来的 gRPC server，请求直接 503。
proto 文件里 google.api.http 注解为什么没生效
注解只是生成时的声明，运行时不参与任何逻辑。它只在 protoc 执行阶段被 protoc-gen-grpc-gateway 插件读取，用来生成 service.pb.gw.go 中的路由绑定代码。
- proto 文件必须显式 import：
import "google/api/annotations.proto";和import "google/api/http.proto";，缺一不可 -
protoc命令必须带--grpc-gateway_out参数，例如：protoc --grpc-gateway_out=paths=source_relative:. helloworld.proto - 生成的
service.pb.gw.go必须被 Go 项目 import（哪怕只是 blank import：_ "your/project/proto"），否则编译时根本不会包含 handler 逻辑 -
body: "*"表示整个 JSON body 映射到 message 根字段；body: "user.name"则只提取 JSON 中user.name路径，字段不存在时静默丢弃，不报错
GET /v1/users/{id} 总是 404 的真实原因
grpc-gateway 不做路径模糊匹配或字段名推导。它靠字段名与 URL 路径段严格一一对应，大小写、下划线、嵌套层级全算数。
- URL 中的
{id}必须在 request message 中定义同名字段：string id = 1;，不能是user_id或ID - query 参数（如
?page=1&limit=20）也必须在 request message 中定义对应字段：int32 page = 2;、int32 limit = 3; - 如果字段缺失或类型不匹配（比如 path 传了字符串，message 字段却是
int32），gateway 直接跳过解析，不填充、不报错、不 fallback - 生成的
service.pb.gw.go里没有自动注册逻辑——你得自己调用RegisterGreeterHandlerFromEndpoint，且传入的是真实可连通的 endpoint 地址（如"localhost:9090"）
如何让 8080 端口同时支持 REST 和 gRPC
不能起两个 http.ListenAndServe，也不能让 gRPC server 直接 Serve(lis) —— 否则会抢 socket、随机断连、返回 503。
- 主 handler 必须是
runtime.ServeMux实例，用于处理 REST 请求 - gRPC server 需包装为
h2c.NewHandler(grpcServer, &http2.Server{})，作为 fallback handler - 最终用
http.Server{Handler: mux}启动，其中mux是 gateway 的 ServeMux，未匹配路径才交给 fallback - 别把
mux.ServeHTTP塞进 Gin/Echo 的路由树（如r.GET("/xxx", mux.ServeHTTP)），这会让 gateway 丢失 method/path 匹配能力，query 和 body 解析全部失效
启动后报 failed to marshal response 或 503
这类错误往往不是代码写错了，而是 runtime 层级的配置或状态没对齐。
-
RegisterXXXHandlerFromEndpoint的ctx不能是已 cancel 的上下文（比如context.WithTimeout(ctx, 1*time.Second)后没重置就传入），注册失败无提示，但 handler 不生效 - endpoint 必须指向**正在运行中**的 gRPC server，地址要能 DNS 解析、端口监听、防火墙放行；
"127.0.0.1:9090"和"localhost:9090"在某些 TLS 或 hostfile 配置下行为不同 - gRPC server 必须启用 reflection（
reflection.Register(server)），否则 gateway 无法获取 service descriptor，部分响应序列化失败 - 默认的 JSON marshaler 对
google.protobuf.Timestamp等类型输出格式不符合预期，需显式配置runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{OrigName: false, EmitUnpopulated: true})
最常被忽略的点：gateway 的 runtime.ServeMux 是独立 HTTP handler，不是中间件；它和 gRPC server 之间是网络调用关系，不是内存共享。任何参数错位、字段名不一致、context 提前 cancel、endpoint 不可达，都会导致静默失败而非明确报错。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
