当前位置：首页 >专题 >Go Protobuf 与 Buf 契约工程实战专题

Go Protobuf 与 Buf

Go Protobuf 与 Buf 契约工程实战专题

从 proto 定义、Go 代码生成到兼容性校验与 CI

这个专题面向已经写过 Go 服务、希望把跨服务数据结构和 API 生成流程做得稳定可维护的开发者。

官方入口与工具链

先建立当前 Protobuf、Go 插件和 Buf 的正确基线

外链

Protocol Buffers Go 入门教程

官方 Go 教程，覆盖 proto3 文件、生成代码与序列化基础。

外链

Protocol Buffers Go Reference

Go 生成代码、API、Opaque API 迁移和 FAQ 的官方参考。

外链

Go gRPC Quickstart

gRPC 官方 Go 快速开始，演示 protoc-gen-go 与 protoc-gen-go-grpc 的安装和生成。

外链

Buf Generate 官方文档

Buf 官方代码生成文档，介绍插件、远程插件、managed mode 和生成 SDK。

外链

Buf 代码生成 Quickstart

Buf 官方实践教程，演示 buf.gen.yaml、Go 插件和 managed mode。

外链

Buf Breaking Change Detection

Buf 官方兼容性检查文档，说明如何阻止破坏性 Protobuf 变更。

站内契约工程路线

从 proto 文件到生成、排错和 CI 落地

文章

GolanggRPC生成代码教程详解

从 proto 定义、安装 protoc 与 Go 插件，到生成 hello.pb.go 和 hello_grpc.pb.go。

文章

Golang集成gRPC与protobuf配置指南

覆盖 go_package、Buf 配置、插件参数、paths=source_relative 与 CI 生成校验。

文章

Golang实现gRPC：proto文件详解指南

讲解 proto3、message、service、流式 RPC 与 Go 代码生成命令。

文章

GoLand缺失google/api/annotations.proto？解决方法来了！

排查 protoc、Google API proto 依赖和 IDE 路径配置导致的生成错误。

文章

如何解决找不到或错误导入google/api/annotations.proto的问题？

围绕 grpc-gateway 生成流程说明第三方 proto 文件的查找路径与配置。

文章

Go语言中的数据格式（json、xml、msgpack、protobuf）使用总结

从数据交换背景、protobuf IDL 到 Go 中的序列化和反序列化示例。

Protobuf 与 Buf 工程 FAQ

把生成、兼容和发布前检查中的高频问题一次讲清

Buf 能完全替代 protoc 吗？

Buf 可以统一模块、依赖、插件和生成流程，但底层仍然围绕 Protobuf 编译与插件生态工作。团队应把 buf.yaml、buf.gen.yaml 和插件版本纳入版本控制，按项目需要选择本地或远程插件。

修改 proto 字段编号为什么危险？

字段编号属于 wire format 的兼容契约。已经发布或写入数据的字段编号不能随意复用；删除字段应保留 reserved，新增字段使用新的编号，并通过 Buf breaking 检查阻止高风险变更。

go_package 和 paths=source_relative 分别解决什么问题？

go_package 决定生成 Go 包的导入路径与包归属，paths=source_relative 决定生成文件相对输入 proto 的输出布局。两者配合可以减少跨模块生成后的 import 混乱，但仍需让目录结构与 Go module 规划一致。

生成代码应该提交到仓库还是在 CI 中生成？

两种方式都可以，关键是生成器、插件和输入 schema 必须可复现。提交生成代码便于下游直接构建；CI 重新生成并 diff 更容易发现漂移。无论采用哪种策略，都应固定工具版本并在合并前执行 buf lint、buf build、buf breaking 或等价检查。