grpc-gateway：gRPC 转 REST 代理生成器

项目简介

gRPC-Gateway 是 Google protocol buffers 编译器 protoc 的插件。它读取 protobuf 服务定义，生成一个反向代理服务器，把 RESTful HTTP API 翻译成 gRPC 调用。代理服务器依据服务定义中的 google.api.http 注解生成。

借助它，同一套 API 可以同时以 gRPC 和 RESTful JSON 两种风格对外提供。适合需要兼容旧客户端、支持对 gRPC 支持不佳的语言或客户端、以及希望保留 RESTful JSON 工具链的场景。

文档地址：https://grpc-ecosystem.github.io/grpc-gateway/

主要功能

• 从 protobuf 服务定义生成 RESTful HTTP → gRPC 的反向代理服务器
• 支持三种 HTTP 映射方式：
  • 使用默认映射（开启 generate_unbound_methods），无需修改 .proto，但无法自定义 HTTP 路径与请求参数
  • 在 .proto 中通过 google.api.http 注解自定义映射
  • 不改 .proto，用外部配置文件设置自定义映射（适合源 proto 不在自己掌控中时）
• 附带 protoc-gen-openapiv2，可生成 Swagger 2.0 / OpenAPI 文档
• 新增 protoc-gen-openapiv3 可输出 OpenAPI 3.1（Alpha 状态，输出尚未稳定，protoc-gen-openapiv2 为生产稳定选项）

安装与使用

从源码编译安装

使用 Go Modules 跟踪工具依赖后，执行：

go install \
    github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway \
    github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2 \
    google.golang.org/protobuf/cmd/protoc-gen-go \
    google.golang.org/grpc/cmd/protoc-gen-go-grpc

这会在 $GOBIN 下放置四个二进制：protoc-gen-grpc-gateway、protoc-gen-openapiv2、protoc-gen-go、protoc-gen-go-grpc，请确认 $GOBIN 在 $PATH 中。

如需输出 OpenAPI 3.1，再安装：

go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3

Go 1.24 起也可在 go.mod 中使用 tool 指令声明工具依赖：

module tools

go 1.24

tool (
	github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway
	github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2
	google.golang.org/grpc/cmd/protoc-gen-go-grpc
	google.golang.org/protobuf/cmd/protoc-gen-go
)

或用 go get -tool 添加，随后在项目根目录执行 go install tool。

也可以直接从 GitHub Releases 页面 下载二进制，发布过程会生成 SLSA3 签名，可用 slsa-verifier 校验。

使用流程

1. 用 protocol buffers 定义 gRPC 服务（your_service.proto）。
2. 生成 gRPC stub，例如使用 buf 的 buf.gen.yaml：

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

或用 protoc：

protoc -I . \
    --go_out ./gen/go/ --go_opt paths=source_relative \
    --go-grpc_out ./gen/go/ --go-grpc_opt paths=source_relative \
    your/service/v1/your_service.proto

3. 按常规方式实现 gRPC 服务。
4. 用 protoc-gen-grpc-gateway 生成反向代理。若使用默认映射，需要开启 generate_unbound_methods：

protoc -I . --grpc-gateway_out ./gen/go \
    --grpc-gateway_opt paths=source_relative \
    --grpc-gateway_opt generate_unbound_methods=true \
    your/service/v1/your_service.proto

若使用自定义注解，在 .proto 中引入 google/api/annotations.proto 并添加 google.api.http 注解，例如 post: "/v1/example/echo"、body: "*"。

注意事项

v2.33.0 包含一项安全修复，改变了网关的请求头解析行为：默认不再把带 Grpc-Metadata- 前缀的客户端请求头自动加入 gRPC metadata。如需恢复旧行为，可使用新的 mux 选项 WithLegacyHeaderMatching，详见官方文档的安全注意事项页面。

---

本作品整理自 GitHub 开源项目 grpc-ecosystem/grpc-gateway，原作者 @grpc-ecosystem，许可证 BSD-3-Clause。中文介绍由 AI 根据项目 README 整理，以原仓库为准。