grpc-gateway REST接口返回404的主因是RegisterXXXHandlerFromEndpoint未调用或runtime.NewServeMux()未正确挂载；需手动注册、确保ctx有效、endpoint可达，且mux须作为独立http.ServeMux使用，不可嵌入Gin/Echo路由树。
为什么 grpc-gateway 生成的 REST 接口返回 404？
核心原因通常是 RegisterXXXHandlerFromEndpoint 没调用，或 runtime.NewServeMux() 没挂到 HTTP 路由器上。它不是自动注册的中间件，得手动把 gRPC 服务“翻译”成 HTTP handler。
- 确保在
main()中调用了RegisterXXXHandlerFromEndpoint（XXX 是你的服务名），且传入的ctx未被 cancel，endpoint是正在运行的 gRPC server 地址（如"localhost:9090"） -
runtime.NewServeMux()必须作为独立的http.ServeMux使用，不能直接塞进 Gin/echo 的路由树；常见错误是写成r.POST("/xxx", mux.ServeHTTP)—— 这会丢掉 method 和 path 匹配逻辑 - 如果用
http.ListenAndServe，务必传入你自己的runtime.ServeMux实例，而不是nil（否则走默认 mux，没注册任何 handler）
如何让 google.api.http 注解真正生效？
注解只是声明，不自动触发映射 —— 必须用 protoc 配合 grpc-gateway 插件重新生成 Go 代码，且 proto 文件要 import 正确的 http rule 定义。
- proto 中必须有
import "google/api/annotations.proto";和import "google/api/http.proto"; -
protoc命令里要显式加--grpc-gateway_out参数，例如：protoc -I. --grpc-gateway_out=logtostderr=true:. api.proto - 路径变量（如
/{name}）会被转成 URL path segment，但 query 参数（?key=value）需在 proto 中显式定义为body: "*"或绑定到 message 字段，否则 gateway 不解析
grpc-gateway 和原生 gRPC server 能共用一个端口吗？
可以，但不是靠“复用 listener”，而是用 golang.org/x/net/http2 + http.Server 的 Handler 分发：HTTP/2 流量给 gRPC server，HTTP/1.1 给 gateway mux。
- 关键点是设置
http.Server.Handler为自定义的handler，内部用h2c.NewHandler包裹 gRPC server，并 fallback 到 gateway mux - 不要用
grpc.NewServer().Serve(lis)单独启一个端口；那样两个 server 会争抢 socket，导致连接拒绝或随机 503 - 注意 TLS：若启用 HTTPS，gRPC 流量仍走 HTTP/2，gateway 走 HTTP/1.1 over TLS —— 大多数情况没问题，但某些老客户端可能不兼容
JSON 编解码行为和原生 gRPC 不一致怎么办？
grpc-gateway 默认用 jsonpb（已弃用）或 google.golang.org/protobuf/encoding/protojson，字段名、空值处理、时间格式都和 proto 定义强相关，容易和前端预期对不上。
立即学习“go语言免费学习笔记（深入）”；
- 时间字段（
google.protobuf.Timestamp）默认序列化为 RFC3339 字符串（带时区），不是毫秒数；如需统一，得在 gateway mux 初始化时传runtime.WithMarshalerOption自定义protojson.MarshalOptions - 枚举值默认输出数字，加
enum_as_int: false可输出名称，但需在protojson.MarshalOptions中设UseEnumNumbers = false - 空字符串、零值字段默认被省略；若前端需要显式返回
null，得设Indent = ""+EmitUnpopulated = true
最常被忽略的是：gateway 的请求体校验完全依赖 proto message 的字段规则（validate 扩展），它不会执行 gRPC server 里的业务校验逻辑。HTTP 层的参数合法性 ≠ 业务合法性，这块边界得人工对齐。
