grpc-gateway：一份接口定义，同时生成 gRPC 与 REST 两种接口

grpc-gateway 是一个开源代码生成工具，属于 Google protobuf 编译器（protoc）的插件，由 grpc-ecosystem 组织用 Go 语言开发维护。它的核心价值是：一份接口定义文件，同时生成 gRPC 和 REST 两种接口，后端不用写两套服务代码。项目在 GitHub 上已有 2 万（20.0k）star、2.4k fork、441 位贡献者，最新版本 v2.30.0 于 2026 年 8 月 5 日发布，采用 BSD-3-Clause 开源许可。

项目定位：解决「一个服务、两种接口」的兼容问题

先解释两个名词。gRPC 是 Google 开源的远程调用框架，程序与程序之间通过它通信，速度快、省带宽、自带强类型约束，适合后端服务之间的内部调用；REST 是更传统、更普及的 HTTP 接口风格，用 URL 加 JSON 数据交互，浏览器、前端、第三方系统都能直接调用。许多团队内部通信想用 gRPC 的性能，对外却必须提供 REST——因为合作方、旧系统、前端工具链只认 HTTP+JSON。

grpc-gateway 就是为这个矛盾而生：你在接口定义文件（proto 文件，一种专门描述数据结构与服务接口的格式）里写清楚服务有哪些方法，它自动生成一个反向代理服务器——一个接收外部请求、再转给后端服务的中转层，把 REST 请求翻译成 gRPC 调用。后端只需维护一个 gRPC 服务，REST 形态的接口由生成的代码自动提供。

适合谁用

用 gRPC 构建后端、又必须对外提供 REST 接口的团队；想保留 gRPC 生态（自动生成多语言客户端、流式传输、强类型定义）又不愿放弃 REST 兼容性的项目。前端开发者、第三方集成方也因此受益：他们拿到的始终是熟悉的 HTTP+JSON 接口。

四种接入方式

默认映射：不动接口定义文件，开启 generate_unbound_methods 选项，插件自动按规则给每个方法生成 HTTP 映射，最省事。
自定义注解：在接口定义文件里给方法加 google.api.http 注解（例如 post: "/v1/example/echo"），精确控制 URL 路径、请求方法、请求参数的位置。
外部配置：接口定义文件不在你手里、无法修改时，用独立的 gRPC Service Configuration 文件配置映射，不碰源文件。
生成 OpenAPI 文档：protoc-gen-openapiv2 插件可顺带输出 Swagger/OpenAPI v2 文档，接口文档站、前端代码生成直接可用。

质量与案例

仓库累计 5963 次提交，持续活跃。Ad Hoc 公司的 William Mill 在官方 README 中记录：他们自 2018 年起用 grpc-gateway 每天服务数百万 API 请求，从未出过问题。项目还支持流式 API 映射为换行分隔的 JSON 流、PATCH 请求自动转为 Field Mask（只更新客户端指定的字段，避免整条数据被覆盖）、Protobuf Editions 2023 等新特性。

新进展与边界

v2.30.0 是当前最新稳定版。新插件 protoc-gen-openapiv3 可输出 OpenAPI 3.1 文档，但官方标注为 Alpha，输出结构尚不稳定，生产环境仍建议使用 protoc-gen-openapiv2。官方明确不计划支持的能力也要知道：HTTP 头中的方法参数、trailer 元数据、XML 编解码、真正的双向流。