使用 buf 生成 gRPC 网关 Stubgrpc-gateway 项目的代码生成实践指南【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway本文以 grpc-gateway 项目官方教程《Generating stubs using buf》为主线完整讲解如何用 buf 替代 protoc 递归发现.proto文件、通过buf.yaml与buf.gen.yaml配置 Go 类型与 gRPC 服务 Stub 的生成并对照仓库根目录的真实配置与 Makefile 中的调用方式帮助读者一次性掌握从安装、配置到产出*.pb.go/*_grpc.pb.go的完整链路为后续接入 grpc-gateway 网关代码生成打下基础。为什么选择 buf 而非 protoc在 grpc-gateway 教程体系中生成 Stub 有两条路线protoc路线与buf路线两者的定位在生成 Stub 总览中有清晰说明protoc是业界使用最广泛的经典生成工具但学习曲线较陡而buf是更年轻、以用户体验和速度为导向的工具并且额外提供 lint代码风格检查与 breaking change detection破坏性变更检测——这两项能力是protoc本身不具备的。buf 提供的 Protobuf 工具链能力包括lint对.proto文件的命名规范、字段风格等进行静态检查breaking change detection对比新旧版本检测可能破坏二进制兼容性的改动generation基于插件机制批量生成类型、服务与网关代码。安装 bufgrpc-gateway 仓库自身通过 Go 工具链安装 buf在 Makefile 中固定了版本go install github.com/bufbuild/buf/cmd/bufv1.45.0该命令将 buf 安装到$GOBIN默认$GOPATH/bin确保后续buf generate等子命令可用。除此之外buf 官方也提供多种系统安装方式具体可查阅其官方安装文档当前仓库教程即指向该文档。用 buf.yaml 声明 Protobuf 模块buf 与protoc最直观的差异在于输入文件的管理方式protoc需要把每个.proto文件显式罗列在命令行上参见 使用 protoc 生成 Stub 中的示例而 buf 会在配置指定的文件层级下递归发现所有.proto文件并统一构建无需逐个列举。这个递归发现行为由buf.yaml控制。buf.yaml应检入check in到 Protobuf 文件层级file hierarchy的根目录buf 会在运行时自动读取它只要该文件存在。此外配置也可以通过命令行参数--config提供它接受指向.json或.yaml文件的路径或直接内联的 JSON / YAML 配置数据。原教程给出的最小合法配置如下将其放在 Protobuf 文件层级的根目录例如仓库根目录下的proto/buf.yamlversion: v1 name: buf.build/myuser/myrepoversion配置文件版本目前为v1name模块的规范名称Buf Schema Registry 风格用于标识你的 Protobuf 模块。仓库真实的 buf.yaml不止两行grpc-gateway 仓库根目录的 buf.yaml 是这一配置在实际大型项目中的完整形态它展示了version/name之外的更多能力version: v1 name: buf.build/grpc-ecosystem/grpc-gateway deps: - buf.build/googleapis/googleapis breaking: use: - FILE lint: use: - DEFAULT ignore_only: DIRECTORY_SAME_PACKAGE: - examples/internal/proto/examplepb/a_bit_of_everything.proto # ... 其他按规则分组的忽略清单 allow_comment_ignores: true build: excludes: - bazel-grpc-gateway对照教程要点可逐项理解deps声明外部依赖模块。这里的buf.build/googleapis/googleapis会被解析并写入 buf.lock该文件为自动生成、勿手改其中记录了远程模块的 owner、repository 与 commit 哈希用于锁定版本breaking.use: [FILE]以文件为单位检测破坏性变更lint.use: [DEFAULT]启用默认 lint 规则集并通过ignore_only对ENUM_VALUE_PREFIX、FIELD_LOWER_SNAKE_CASE、PACKAGE_DIRECTORY_MATCH等具体规则逐文件豁免——这正体现了教程所说的 lint 能力也解释了为何仓库中允许存在部分不完全符合默认风格的历史 protoallow_comment_ignores: true允许在.proto源码中用注释屏蔽 lint 规则build.excludes构建时排除bazel-grpc-gateway目录避免误把 Bazel 生成的目录纳入模块。用 buf.gen.yaml 定义生成模板配置好模块后还需要一个生成模板文件buf.gen.yaml来告诉 buf调用哪些插件、输出到哪里、传什么参数。原教程为 Go 类型与 gRPC Stub 给出的模板如下version: v1 plugins: - plugin: go out: proto opt: pathssource_relative - plugin: go-grpc out: proto opt: pathssource_relativeplugin: go/plugin: go-grpc分别调用 Go 类型生成插件与 gRPC 服务定义生成插件产出*.pb.go与*_grpc.pb.goout: proto生成文件相对于proto目录输出opt: pathssource_relative生成的 Go 文件与源.proto文件位于同一目录避免按 Go import path 重建目录树。仓库中的 v2 模板语法与 grpc-gateway 插件grpc-gateway 根目录的 buf.gen.yaml 是教程示例的升级形态使用了version: v2语法并加入了 grpc-gateway 自己的两个生成插件version: v2 plugins: - remote: buf.build/protocolbuffers/go:v1.35.1 out: . opt: - pathssource_relative - remote: buf.build/grpc/go:v1.5.1 out: . opt: - pathssource_relative - require_unimplemented_serversfalse - local: protoc-gen-grpc-gateway out: . opt: - pathssource_relative - allow_repeated_fields_in_bodytrue - local: protoc-gen-openapiv2 out: . opt: - allow_repeated_fields_in_bodytrue与教程的 v1 示例相比v2 语法的差异要点插件来源字段v1 用plugin: go表示本地插件v2 区分为remote:从 Buf Schema Registry 拉取远程插件如buf.build/protocolbuffers/go:v1.35.1与local:调用本地已安装的可执行文件如仓库自带的protoc-gen-grpc-gateway、protoc-gen-openapiv2opt 列表化v1 的opt是单个字符串v2 中为字符串列表可一次传多个参数如pathssource_relative与require_unimplemented_serversfalse并列网关插件protoc-gen-grpc-gateway生成*.pb.gw.go反向代理桩代码protoc-gen-openapiv2生成 OpenAPI v2 描述文档——这正是 grpc-gateway 项目把“类型 Stub → gRPC Stub → HTTP 网关桩 → OpenAPI 文档”一次性串联起来的关键。仓库内还有一批面向特定场景的模板文件进一步展示了opt参数的定制能力enum_with_single_value.buf.gen.yaml为protoc-gen-openapiv2传入omit_enum_default_valuetrue控制单值枚举在 OpenAPI 输出中的呈现protoc-gen-openapiv2/options/buf.gen.yaml为 Go 插件传入default_api_levelAPI_HYBRID等选项protoc-gen-openapiv3/buf.gen.yaml使用本地protoc-gen-openapiv3插件产出 OpenAPI v3 描述。运行 buf generate 并检查产物配置完成后在 Protobuf 文件层级根目录执行$ buf generatebuf 会读取根目录的buf.gen.yaml也可用--template显式指定其他模板文件递归构建模块内所有.proto文件并为每个 protobuf package 生成*.pb.goGo 类型定义*_grpc.pb.gogRPC 服务接口与客户端/服务端桩。在 grpc-gateway 仓库中可以直观看到产物与源文件同目录落盘例如 helloworld.proto 旁边就躺着 helloworld.pb.go、helloworld_grpc.pb.go 以及网关桩 helloworld.pb.gw.go 和 helloworld.swagger.json——这正是pathssource_relative的落地效果。多模板并存的真实用法--template一个实际项目往往需要多套生成配置。grpc-gateway 的 Makefile 展示了这一实践默认执行buf generate随后用--template反复调用不同模板生成额外产物例如buf generate --template ./examples/internal/proto/examplepb/openapi_merge.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/standalone_echo_service.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/unannotated_echo_service.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/generate_unbound_methods.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/use_go_template.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/ignore_comment.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/remove_internal_comment.buf.gen.yaml # 以及多组 visibility 规则模板、enum_with_single_value、proto3_field_semantics、 # opaque、protoc-gen-openapiv2/options、protoc-gen-openapiv3/options 等由此可以看出--template参数让“同一份 proto 源码、多份定制输出”成为可能——这正是教程中--config之外、buf 命令行灵活性的延伸也是把 lint、breaking、多插件输出统一进 CI 流水线的基础。依赖锁定与版本管理buf.lock当buf.yaml声明了deps后首次运行相关命令会生成 buf.lock。该文件由 buf 自动维护并应检入版本库其内容锁定远程模块的确切提交保证团队成员生成结果一致# Generated by buf. DO NOT EDIT. version: v1 deps: - remote: buf.build owner: googleapis repository: googleapis commit: 62f35d8aed1149c291d606d958a7ce32在 grpc-gateway 中googleapis 依赖为*.proto中的google.api.http等注解提供了类型来源——这是 grpc-gateway 路由映射HTTP annotation得以编译的基础。结合 go.mod 中的 Go 模块依赖buf 生态的模块锁定buf.lock与 Go 生态的模块锁定go.sum共同构成了完整的可复现构建链路。从 Stub 到网关完整的接入路径生成 Stub 只是 grpc-gateway 开发流程的第一步。教程的下一步指向 creating_main.go即编写入口代码把 gRPC 服务与 HTTP 网关装配起来。若要从零走通全流程建议按以下顺序阅读本教程系列教程导览与简单 Hello World 示例建立整体认知在.proto中加入 google.api.http 注解声明 HTTP 路由映射按本文方式用 buf或 protoc生成类型与 gRPC Stub再叠加 grpc-gateway 与 openapiv2 插件生成网关桩与 API 文档参考 creating_main.go 组装服务端与网关最终落地运行。小结buf 通过buf.yaml模块声明、lint 与 breaking 规则、依赖buf.gen.yaml插件、输出路径、插件参数取代了 protoc 繁琐的命令行文件罗列并借助递归发现、远程插件与--template多模板机制让 Stub 生成变得可声明、可复用、可锁定。grpc-gateway 仓库本身既是这套工具链的深度用户也是最佳参考样例——从根目录的 buf.yaml、buf.gen.yaml、buf.lock 到 Makefile 中的全套生成指令都可以直接对照本文的每一步进行验证与扩展。【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 buf 生成 gRPC 网关 Stub：grpc-gateway 项目的代码生成实践指南
使用 buf 生成 gRPC 网关 Stubgrpc-gateway 项目的代码生成实践指南【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway本文以 grpc-gateway 项目官方教程《Generating stubs using buf》为主线完整讲解如何用 buf 替代 protoc 递归发现.proto文件、通过buf.yaml与buf.gen.yaml配置 Go 类型与 gRPC 服务 Stub 的生成并对照仓库根目录的真实配置与 Makefile 中的调用方式帮助读者一次性掌握从安装、配置到产出*.pb.go/*_grpc.pb.go的完整链路为后续接入 grpc-gateway 网关代码生成打下基础。为什么选择 buf 而非 protoc在 grpc-gateway 教程体系中生成 Stub 有两条路线protoc路线与buf路线两者的定位在生成 Stub 总览中有清晰说明protoc是业界使用最广泛的经典生成工具但学习曲线较陡而buf是更年轻、以用户体验和速度为导向的工具并且额外提供 lint代码风格检查与 breaking change detection破坏性变更检测——这两项能力是protoc本身不具备的。buf 提供的 Protobuf 工具链能力包括lint对.proto文件的命名规范、字段风格等进行静态检查breaking change detection对比新旧版本检测可能破坏二进制兼容性的改动generation基于插件机制批量生成类型、服务与网关代码。安装 bufgrpc-gateway 仓库自身通过 Go 工具链安装 buf在 Makefile 中固定了版本go install github.com/bufbuild/buf/cmd/bufv1.45.0该命令将 buf 安装到$GOBIN默认$GOPATH/bin确保后续buf generate等子命令可用。除此之外buf 官方也提供多种系统安装方式具体可查阅其官方安装文档当前仓库教程即指向该文档。用 buf.yaml 声明 Protobuf 模块buf 与protoc最直观的差异在于输入文件的管理方式protoc需要把每个.proto文件显式罗列在命令行上参见 使用 protoc 生成 Stub 中的示例而 buf 会在配置指定的文件层级下递归发现所有.proto文件并统一构建无需逐个列举。这个递归发现行为由buf.yaml控制。buf.yaml应检入check in到 Protobuf 文件层级file hierarchy的根目录buf 会在运行时自动读取它只要该文件存在。此外配置也可以通过命令行参数--config提供它接受指向.json或.yaml文件的路径或直接内联的 JSON / YAML 配置数据。原教程给出的最小合法配置如下将其放在 Protobuf 文件层级的根目录例如仓库根目录下的proto/buf.yamlversion: v1 name: buf.build/myuser/myrepoversion配置文件版本目前为v1name模块的规范名称Buf Schema Registry 风格用于标识你的 Protobuf 模块。仓库真实的 buf.yaml不止两行grpc-gateway 仓库根目录的 buf.yaml 是这一配置在实际大型项目中的完整形态它展示了version/name之外的更多能力version: v1 name: buf.build/grpc-ecosystem/grpc-gateway deps: - buf.build/googleapis/googleapis breaking: use: - FILE lint: use: - DEFAULT ignore_only: DIRECTORY_SAME_PACKAGE: - examples/internal/proto/examplepb/a_bit_of_everything.proto # ... 其他按规则分组的忽略清单 allow_comment_ignores: true build: excludes: - bazel-grpc-gateway对照教程要点可逐项理解deps声明外部依赖模块。这里的buf.build/googleapis/googleapis会被解析并写入 buf.lock该文件为自动生成、勿手改其中记录了远程模块的 owner、repository 与 commit 哈希用于锁定版本breaking.use: [FILE]以文件为单位检测破坏性变更lint.use: [DEFAULT]启用默认 lint 规则集并通过ignore_only对ENUM_VALUE_PREFIX、FIELD_LOWER_SNAKE_CASE、PACKAGE_DIRECTORY_MATCH等具体规则逐文件豁免——这正体现了教程所说的 lint 能力也解释了为何仓库中允许存在部分不完全符合默认风格的历史 protoallow_comment_ignores: true允许在.proto源码中用注释屏蔽 lint 规则build.excludes构建时排除bazel-grpc-gateway目录避免误把 Bazel 生成的目录纳入模块。用 buf.gen.yaml 定义生成模板配置好模块后还需要一个生成模板文件buf.gen.yaml来告诉 buf调用哪些插件、输出到哪里、传什么参数。原教程为 Go 类型与 gRPC Stub 给出的模板如下version: v1 plugins: - plugin: go out: proto opt: pathssource_relative - plugin: go-grpc out: proto opt: pathssource_relativeplugin: go/plugin: go-grpc分别调用 Go 类型生成插件与 gRPC 服务定义生成插件产出*.pb.go与*_grpc.pb.goout: proto生成文件相对于proto目录输出opt: pathssource_relative生成的 Go 文件与源.proto文件位于同一目录避免按 Go import path 重建目录树。仓库中的 v2 模板语法与 grpc-gateway 插件grpc-gateway 根目录的 buf.gen.yaml 是教程示例的升级形态使用了version: v2语法并加入了 grpc-gateway 自己的两个生成插件version: v2 plugins: - remote: buf.build/protocolbuffers/go:v1.35.1 out: . opt: - pathssource_relative - remote: buf.build/grpc/go:v1.5.1 out: . opt: - pathssource_relative - require_unimplemented_serversfalse - local: protoc-gen-grpc-gateway out: . opt: - pathssource_relative - allow_repeated_fields_in_bodytrue - local: protoc-gen-openapiv2 out: . opt: - allow_repeated_fields_in_bodytrue与教程的 v1 示例相比v2 语法的差异要点插件来源字段v1 用plugin: go表示本地插件v2 区分为remote:从 Buf Schema Registry 拉取远程插件如buf.build/protocolbuffers/go:v1.35.1与local:调用本地已安装的可执行文件如仓库自带的protoc-gen-grpc-gateway、protoc-gen-openapiv2opt 列表化v1 的opt是单个字符串v2 中为字符串列表可一次传多个参数如pathssource_relative与require_unimplemented_serversfalse并列网关插件protoc-gen-grpc-gateway生成*.pb.gw.go反向代理桩代码protoc-gen-openapiv2生成 OpenAPI v2 描述文档——这正是 grpc-gateway 项目把“类型 Stub → gRPC Stub → HTTP 网关桩 → OpenAPI 文档”一次性串联起来的关键。仓库内还有一批面向特定场景的模板文件进一步展示了opt参数的定制能力enum_with_single_value.buf.gen.yaml为protoc-gen-openapiv2传入omit_enum_default_valuetrue控制单值枚举在 OpenAPI 输出中的呈现protoc-gen-openapiv2/options/buf.gen.yaml为 Go 插件传入default_api_levelAPI_HYBRID等选项protoc-gen-openapiv3/buf.gen.yaml使用本地protoc-gen-openapiv3插件产出 OpenAPI v3 描述。运行 buf generate 并检查产物配置完成后在 Protobuf 文件层级根目录执行$ buf generatebuf 会读取根目录的buf.gen.yaml也可用--template显式指定其他模板文件递归构建模块内所有.proto文件并为每个 protobuf package 生成*.pb.goGo 类型定义*_grpc.pb.gogRPC 服务接口与客户端/服务端桩。在 grpc-gateway 仓库中可以直观看到产物与源文件同目录落盘例如 helloworld.proto 旁边就躺着 helloworld.pb.go、helloworld_grpc.pb.go 以及网关桩 helloworld.pb.gw.go 和 helloworld.swagger.json——这正是pathssource_relative的落地效果。多模板并存的真实用法--template一个实际项目往往需要多套生成配置。grpc-gateway 的 Makefile 展示了这一实践默认执行buf generate随后用--template反复调用不同模板生成额外产物例如buf generate --template ./examples/internal/proto/examplepb/openapi_merge.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/standalone_echo_service.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/unannotated_echo_service.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/generate_unbound_methods.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/use_go_template.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/ignore_comment.buf.gen.yaml buf generate --template ./examples/internal/proto/examplepb/remove_internal_comment.buf.gen.yaml # 以及多组 visibility 规则模板、enum_with_single_value、proto3_field_semantics、 # opaque、protoc-gen-openapiv2/options、protoc-gen-openapiv3/options 等由此可以看出--template参数让“同一份 proto 源码、多份定制输出”成为可能——这正是教程中--config之外、buf 命令行灵活性的延伸也是把 lint、breaking、多插件输出统一进 CI 流水线的基础。依赖锁定与版本管理buf.lock当buf.yaml声明了deps后首次运行相关命令会生成 buf.lock。该文件由 buf 自动维护并应检入版本库其内容锁定远程模块的确切提交保证团队成员生成结果一致# Generated by buf. DO NOT EDIT. version: v1 deps: - remote: buf.build owner: googleapis repository: googleapis commit: 62f35d8aed1149c291d606d958a7ce32在 grpc-gateway 中googleapis 依赖为*.proto中的google.api.http等注解提供了类型来源——这是 grpc-gateway 路由映射HTTP annotation得以编译的基础。结合 go.mod 中的 Go 模块依赖buf 生态的模块锁定buf.lock与 Go 生态的模块锁定go.sum共同构成了完整的可复现构建链路。从 Stub 到网关完整的接入路径生成 Stub 只是 grpc-gateway 开发流程的第一步。教程的下一步指向 creating_main.go即编写入口代码把 gRPC 服务与 HTTP 网关装配起来。若要从零走通全流程建议按以下顺序阅读本教程系列教程导览与简单 Hello World 示例建立整体认知在.proto中加入 google.api.http 注解声明 HTTP 路由映射按本文方式用 buf或 protoc生成类型与 gRPC Stub再叠加 grpc-gateway 与 openapiv2 插件生成网关桩与 API 文档参考 creating_main.go 组装服务端与网关最终落地运行。小结buf 通过buf.yaml模块声明、lint 与 breaking 规则、依赖buf.gen.yaml插件、输出路径、插件参数取代了 protoc 繁琐的命令行文件罗列并借助递归发现、远程插件与--template多模板机制让 Stub 生成变得可声明、可复用、可锁定。grpc-gateway 仓库本身既是这套工具链的深度用户也是最佳参考样例——从根目录的 buf.yaml、buf.gen.yaml、buf.lock 到 Makefile 中的全套生成指令都可以直接对照本文的每一步进行验证与扩展。【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考