protobuf

Protocol Buffers

何时需要此技能

• 创建或编辑 .proto 文件
• 设置 buf.yaml 或 buf.gen.yaml
• 设计 gRPC 或 Connect 服务
• 添加 protovalidate 约束
• 排查 buf lint 或破坏性变更错误

核心工作流

1. 匹配项目风格

编写 proto 代码前，先检查项目中现有的 .proto 文件。 遵循现有的命名、字段顺序、结构模式、验证和文档风格约定。 如果项目中没有现有文件，请询问用户应采用哪种风格，或模仿哪个现有库。

2. 编写 Proto 代码

• 应用 best_practices.md 中的通用最佳实践
• 为每个字段添加 protovalidate 约束——对于生产 API，这不是可选项
• 服务模板请参阅 assets/

3. 验证变更

进行变更后务必运行：

buf format -w && buf lint

先检查是否有 Makefile——许多项目使用 make lint 或 make format。

修复所有错误后，才能认为变更已完成。

快速参考

任务	参考
字段类型、枚举、oneof、映射	quick_reference.md
Schema 演进、破坏性变更	best_practices.md
验证约束	protovalidate.md
完整服务示例	examples.md、assets/
buf CLI、buf.yaml、buf.gen.yaml	buf_toolchain.md
从 protoc 迁移	migration.md
Lint 错误、常见问题	troubleshooting.md
Proto API 审核清单	review_checklist.md

项目设置

新建项目

1. 创建目录结构：

   proto/
   ├── buf.yaml
   ├── buf.gen.yaml
   └── company/
       └── domain/
           └── v1/
               └── service.proto
   

2. 以 assets/buf.yaml 为起点

3. 在 buf.yaml 中添加 buf.build/bufbuild/protovalidate 作为依赖，并运行 buf dep update

4. 使用 assets/buf.gen.*.yaml 配置代码生成

代码生成模板

模板	用途
buf.gen.go.yaml	Go 和 gRPC
buf.gen.go-connect.yaml	Go 和 Connect
buf.gen.ts.yaml	TypeScript 和 Connect
buf.gen.python.yaml	Python 和 gRPC
buf.gen.java.yaml	Java 和 gRPC

Proto 文件模板

位于 assets/proto/example/v1/：

模板	说明
book.proto	实体消息、BookRef oneof、枚举
book_service.proto	完整的 CRUD，包含批量操作、分页和排序

常见任务

添加新字段

1. 使用下一个连续字段编号
2. 添加 protovalidate 约束：每个字段都应根据其类型添加适当的验证（格式验证器、长度界限、数值范围、枚举约束等）
3. 为字段编写文档
4. 运行 buf format -w && buf lint

删除字段

1. 保留字段编号和名称：

   reserved 4;
   reserved "old_field_name";
   

2. 运行 buf breaking --against '.git#branch=main' 进行验证

添加 protovalidate 约束

生产 API 中的每个字段都应有适当的验证。 完整参考请参阅 protovalidate.md。

常见约束：

• 字符串格式：.string.uuid、.string.email、.string.uri、.string.pattern
• 字符串界限：.string.min_len、.string.max_len
• 数值界限：.int32.gte、.uint32.lte
• 枚举验证：.enum.defined_only、.enum.not_in = 0
• 重复字段界限：.repeated.min_items、.repeated.max_items
• 必填字段：(buf.validate.field).required = true
• 必填 oneof：(buf.validate.oneof).required = true

验证清单

完成变更后：

• 每个字段都有适当的 protovalidate 约束
• buf format -w（应用格式化）
• buf lint（检查风格规则）
• buf breaking --against '.git#branch=main'（修改现有 schema 时）