gRPC↔HTTP/JSON转换必须避免网关直连gRPC Server，否则会丢失metadata、截断streaming、错误码映射混乱；正确解法是gRPC服务自带grpc-gateway sidecar并显式配置google.api.http注解。
协议转换不是加个中间件就能跑通的事，核心在于“谁转、在哪转、怎么转不丢数据”。gRPC ↔ HTTP/JSON 的转换必须绕开网关直连 gRPC Server 的陷阱，否则 streaming 会断、metadata 会丢、错误码会变成 rpc error: code = Unknown desc = 。
为什么不能在网关里直接 dial gRPC Server
网关本质是 HTTP Server，没有 gRPC Client 的上下文管理能力。直接用 grpc.Dial 发起调用会踩三个坑：
- 无法透传
grpc.Header和grpc.Trailer，JWT token 或 traceID 只能靠手动塞X-Forwarded-For等 Header，下游服务拿不到原始 metadata - gRPC streaming（比如日志推送、实时通知）在 HTTP 层会被截断，
http.ResponseWriter不支持持续写入 - 错误码映射混乱：
codes.NotFound到 HTTP 是 404，但网关自己没做翻译逻辑时，一律返回 500 + 模糊的rpc error
正确解法是让每个 gRPC 服务自带 grpc-gateway sidecar，暴露标准 REST 接口；网关只跟这个 sidecar 通信。
grpc-gateway 的 proto 注解必须显式声明
光写 service UserService 不够，HTTP 路由和 body 映射要靠 google.api.http 扩展。漏掉这步，生成的 *.pb.gw.go 文件里就没有 HTTP handler。
立即学习“go语言免费学习笔记（深入）”；
- 必须
import "google/api/annotations.proto"，且确保本地有google/api/annotations.pb.go -
post/get路径要带前缀，比如post: "/v1/user/login"，否则 gateway 默认 fallback 到/ -
body: "*"表示整个 JSON body 映射到 request message；如果只想映射部分字段，得写成body: "user.name" - 若后端需要 raw binary（如文件上传），
grpc-gateway默认不支持，得改用runtime.WithMarshalerOption注册自定义 marshaler
go-zero 网关配置里 Endpoint 指的是 gRPC Server 地址，不是 sidecar
很多人被 goctl api go 生成的 etc/*.yaml 误导，以为 Grpc.Endpoint 是填 sidecar 的 HTTP 地址。其实它是给网关内部 client 用的——go-zero 网关自己会发起 gRPC 调用，所以这里必须填真实的 localhost:9000 这类 gRPC 监听地址。
- 它和
grpc-gateway的架构不同：go-zero 是“HTTP 入口 → 自动转成 gRPC 调用”，而 grpc-gateway 是“HTTP 入口 → sidecar 转成 gRPC 调用” - 这意味着 go-zero 网关必须能直连所有后端 gRPC Server，网络策略要放开，且需配置 TLS（
grpc.WithTransportCredentials）或禁用（grpc.WithInsecure()） - go-zero 的
Mappings中RpcMethod必须和 proto 里定义的完全一致，包括 package 名，比如user.UserService.Login，少一级就报method not found
跨语言调用时 proto 版本和字段编号必须严格对齐
Go 和 Java 用同一份 .proto 文件生成代码，看似没问题，但实际部署常因两个细节崩掉：
- Go 生成代码用
protoc-gen-gov1.28+，Java 用protobuf-maven-pluginv3.21+，版本差一丁点，oneof字段的零值处理逻辑就可能不一致 - 字段编号一旦发布就不能改，哪怕字段已
reserved，Java 客户端反序列化时仍会尝试读该位置——若 Go 服务新写了别的字段，Java 就 panic - map 类型在 Go 里是
map[string]string，Java 是Map<string string></string>，但 protobuf 编译后底层都是 repeated key-value pair，只要 proto 定义一致，序列化结果就一致
真正容易被忽略的是：所有服务启动时都要校验 proto schema hash 是否一致，而不是只靠 CI 生成阶段“看起来一样”。
