Go 代码生成实践：从 Protobuf 到 OpenAPI 的工程化之路

为什么代码生成又成了热门话题

如果你写过几年 Go，大概率经历过这样的事：项目初期用 protobuf 定义了一套 gRPC 接口，各端调用都很顺畅；后来业务需要对外暴露 REST API，于是又写了一套 OpenAPI 规范，再手写一遍结构体、路由和校验逻辑。两套体系并行维护，接口文档和实现逐渐脱节，改一个字段要动三四个地方，烦不胜烦。

真正麻烦的地方不在于“写代码”，而在于“反复写同一种代码”。尤其是当你的团队同时维护着 gRPC 和 REST 两套接入方式时，服务端逻辑、客户端 SDK、甚至接口文档都应该是同一份契约的产物，而不是靠人肉对齐。

这就是为什么这几年 Go 代码生成技术又重新被频繁提起——不是因为工具新，而是因为工程复杂度倒逼我们必须把“从契约到代码”这件事做彻底。从 protobuf 到 OpenAPI 的代码生成实践，本质上是在解决一个问题：如何用一份 IDL（接口定义语言）喂饱整个开发生命周期。

先厘清两条主线的生成逻辑

很多人会把 protobuf 的代码生成和 OpenAPI 的代码生成混为一谈，但它们的侧重点其实很不一样。

Protobuf 是“服务契约型”生成

在 Go 里用 protobuf，通常是为了 gRPC。你写一个 .proto 文件，定义 service、rpc、message，然后通过 protoc 配合 protoc-gen-go 和 protoc-gen-go-grpc 插件，直接生成出 struct、客户端 stub 以及服务端接口骨架。这个流程的产出是强类型的、二进制友好的，而且方法签名被严格约束，几乎是“编译器帮你保证接口正确性”。

举个例子：

syntax = "proto3";

service OrderService {
  rpc CreateOrder(CreateOrderReq) returns (CreateOrderResp);
}

message CreateOrderReq {
  string user_id = 1;
  repeated string product_ids = 2;
  double amount = 3;
}

生成出来的 Go 代码里，你会得到一个 OrderServiceServer 接口，里面只有一个方法 CreateOrder(context.Context, *CreateOrderReq) (*CreateOrderResp, error)。这就是契约：实现方必须满足这个签名，调用方也只能按这个签名来调用。对于内部服务间通信，这样的约束已经足够强了。

OpenAPI 是“资源描述型”生成

OpenAPI 规范（原 Swagger）描述的是 HTTP 层面的资源、路径、请求体和响应体，它不关心你是用 Go 还是用 Java 实现，也不强制 RPC 语义。常用工具 oapi-codegen 会根据 OpenAPI 文件生成 Go 的 server 或 client 代码，但生成的代码往往更“薄”：它给你的是路由、参数解析、类型定义，以及某种形式的接口声明，但具体业务逻辑还是需要你自己填充。

openapi: 3.0.0
paths:
  /orders:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderReq'
      responses:
        '201':
          description: Created
components:
  schemas:
    CreateOrderReq:
      type: object
      properties:
        user_id:
          type: string
        product_ids:
          type: array
          items:
            type: string
        amount:
          type: number
          format: double

这是典型的契约描述，但缺少了“服务行为”的语义——它不知道 CreateOrder 这个动作代表什么，只能帮你生成一个处理函数。对于 REST 风格的外部 API，这种描述方式又是必需的，因为它天然与 HTTP 方法论对齐。

于是问题就来了：同一个业务，两套契约，两份生成代码，如何统一？

最常踩的坑：把代码生成当成“一次性”的事

很多团队在使用代码生成时，会陷入几个典型的误区：

• 认为生成代码不能改：于是要求工具必须生成出完美的生产级代码，结果发现工具生成的错误处理、校验逻辑、日志格式都不符合团队规范，于是放弃生成，回归手写。
• 生成代码和手写代码混在一起：把生成出来的 struct 和手写的业务逻辑写在同一个包里，某次重新生成后覆盖了手动修改的代码，导致调试困难。
• 只生成服务端，不生成客户端：觉得客户端 SDK 由调用方自己写就行，结果每个调用方都自己实现一遍类似的请求封装，接口变更时到处报错。

这些问题的根源在于：没有把代码生成当作一条持续集成的流水线。正确的做法是，生成代码应该是一次性的、可重复执行的，所有手动添加的逻辑必须在生成代码之外，通过组合、包装或依赖注入的方式接入。

从 Protobuf 到 OpenAPI 的打通方案对比

在实际项目中，我们通常需要从同一份 protobuf 定义同时得到 gRPC 服务和 REST API，甚至生成 OpenAPI 文档和客户端 SDK。目前主流的思路有三种：

如果你的团队已经重度使用 gRPC，那么 grpc-gateway 是最顺手的方案。它通过在 proto 文件的 rpc 上添加 google.api.http 注解，直接生成一个反向代理服务，将 HTTP/JSON 请求翻译成 gRPC 调用。同时，protoc-gen-openapi 插件还可以从带有这些注解的 proto 文件生成 OpenAPI 文档，从而间接打通了到 OpenAPI 的链路。

但这条路并不总是平坦的。grpc-gateway 生成的 HTTP 路由往往比较“粗暴”，比如字段命名、枚举转换、错误码映射等都需要额外处理。而且，一旦你需要更复杂的 URL 模式、参数校验或自定义响应格式，就会发现 proto 注解的能力有限，这时候你可能需要混合使用 oapi-codegen 来获得更精细的控制。

一个典型场景：从纯 gRPC 到对外提供 RESTful API

假设你负责一个订单服务，最初只对内提供 gRPC 接口。随着业务发展，需要开放给前端或第三方合作伙伴，必须提供 REST API。这时你有两个选择：

1. 把 gRPC 服务拆成单独的 gRPC 和 REST 两个服务，REST 服务内部再调用 gRPC。
2. 使用 grpc-gateway 在不改变现有 gRPC 服务的情况下，直接暴露 HTTP 接入。

多数团队会倾向于第二种，因为它改动最小。但接下来你会发现，REST 接口的响应格式、错误码、分页方式可能和 gRPC 内部约定不一致，你需要额外的映射层。而且，如果你希望生成客户端 SDK 给合作伙伴，grpc-gateway 生成的 OpenAPI 文件可能缺少足够的描述信息（比如参数校验规则、示例值），导致自动生成的 SDK 不够友好。

这时候，一个务实的做法是：

• 依然用 proto 作为唯一的事实来源，并添加丰富的 google.api.http 注解和 openapi 扩展注释。
• 通过 protoc-gen-openapi 生成 OpenAPI 规范文件，然后人工补充缺失的描述、示例、安全定义等。
• 最后用 openapi-generator 或 oapi-codegen 生成客户端 SDK，并和生成的 grpc-gateway 代码一起交付。

这个过程虽然比直接用 grpc-gateway 多了一步，但长期来看，一份精心维护的 OpenAPI 文档的价值远超额外的工作量——它不仅是生成代码的输入，更是团队间的协作契约。

代码生成不是万能药

最后想强调一点：代码生成解决的是“冗余的、机械的、重复的”代码，而不是“复杂的、有判断的、业务相关的”代码。如果你发现生成的代码还需要大量修改才能用，要么是工具选错了，要么是契约定义得不够严谨。

在 Go 生态里，从 protobuf 到 OpenAPI 的代码生成实践，本质上是一场关于“契约优先”的工程化落地。如果你能坚持用一份 IDL 驱动整个服务生命周期，那么无论是内部的 gRPC 调用，还是外部的 REST 接口，甚至是客户端 SDK 和接口文档，都将成为同一棵树上长出的不同分支，而不是需要人工对齐的孤岛。