buf.gen.yaml

在微服务里用 Go 写后端，gRPC 几乎是默认选项：proto 即契约，代码生成省事，性能也好。但前端和第三方接入方往往只认 REST，于是 grpc-gateway 就成了那个"既要又要"的方案——一份 proto，同时吐出 gRPC 接口和 HTTP/JSON 接口。

听起来很美好，真正落地时坑一个接一个。下面是我在一个中型项目里踩过的几处，记录一下，希望能帮后来人少熬两个晚上。

坑一：代码生成的三方打架

最开始我按官方文档分别装了 `protoc-gen-go`、`protoc-gen-go-grpc`、`protoc-gen-grpc-gateway`，然后手写一长串 `protoc` 命令。问题很快就来了：`paths=source_relative` 只加在了部分插件上，生成的 `.pb.go` 和 `.pb.gw.go` 落在不同目录，编译时报"找不到类型定义"。

更隐蔽的是 `google/api/annotations.proto` 的引入。HTTP 注解依赖 `googleapis` 的公共 proto，如果项目里用的版本和插件内置的不一致，会报重复定义或者 descriptor 冲突。

经验是：直接上 `buf`，别手写 protoc 命令。

version: v2
plugins:
  - local: protoc-gen-go
    out: gen
    opt: paths=source_relative
  - local: protoc-gen-go-grpc
    out: gen
    opt: paths=source_relative
  - local: protoc-gen-grpc-gateway
    out: gen
    opt: paths=source_relative

`buf.lock` 把依赖版本钉死，团队里谁生成的结果都一样，这一步值得提前做。

坑二：HandlerServer 与 HandlerFromEndpoint，选错丢拦截器

网关的注册有两个函数：`RegisterXxxHandlerServer` 和 `RegisterXxxHandlerFromEndpoint`。

前者是进程内直调，不走网络，性能好，调试方便，很多人第一反应就选它。但它的调用链是：HTTP 请求 → ServeMux → 直接调用你的 service 实现。gRPC 的拦截器链完全被绕过了。如果你的鉴权、日志、限流都写在 unary interceptor 里，网关这条路径上等于裸奔。

我当时就是先用了 HandlerServer，测试环境一切正常，上线后才发现网关进来的请求没有 trace id、没有权限校验。后来改成 `RegisterXxxHandlerFromEndpoint`，把地址指向本机监听的 gRPC 端口，虽然多了一次本地回环，但拦截器、metadata、超时控制全都统一了。

如果确实想用 HandlerServer（比如为了省掉序列化开销），那就得把中间件逻辑抽出来，HTTP 侧和 gRPC 侧各接一遍——这就是下一坑。

坑三：Header、Metadata 和鉴权的两套逻辑

网关会把 HTTP Header 转成 gRPC metadata，但不是所有 Header 都转。默认的 `DefaultHeaderMatcher` 只放行一批"永久头"和带 `Grpc-Metadata-` 前缀的自定义头，而且 `Authorization` 这类头会被加上前缀，导致拦截器里 `md.Get("authorization")` 拿到空字符串。

排查这个问题的正确姿势是在拦截器里把整个 `md` 打出来看一眼：

md, _ := metadata.FromIncomingContext(ctx)
log.Printf("%+v", md)

要透传自定义头（比如 `X-Request-Id`、`X-Tenant-Id`），得显式配置：

runtime.WithIncomingHeaderMatcher(func(key string) (string, bool) {
    switch strings.ToLower(key) {
    case "x-request-id", "x-tenant-id":
        return strings.ToLower(key), true
    }
    return runtime.DefaultHeaderMatcher(key)
})

另外 CORS、访问日志、panic 恢复这些，属于 HTTP 层的中间件，得挂在 mux 外面，和 gRPC 拦截器是两套东西。我后来干脆写了一个薄薄的 `middleware` 包，两边复用同一批纯函数，避免逻辑漂移。

坑四：错误码映射和前端约定不一致

gRPC 的 `status.Code` 会被网关映射成 HTTP 状态码，比如 `InvalidArgument → 400`、`NotFound → 404`、`Unknown → 500`。默认的 JSON body 长这样：

{"code": 3, "message": "invalid phone", "details": []}

前端同学看到 `code: 3` 直接懵了。而且默认映射里，凡是没用 `status.Error` 包装的错误，一律变成 500 和一段英文内部信息，线上暴露细节也不太合适。

统一错误体是必须的：

```go
runtime.WithErrorHandler(func(ctx context.Context, mux *runtime.ServeMux,
m runtime.Marshaler, w http.ResponseWriter, r *http.Request, err error) {
st := status.Convert(err)
w.Header