protobuf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Protocol Buffers

When You Need This Skill

适用场景

Creating or editing
```
.proto
```
files
Setting up
```
buf.yaml
```
or
```
buf.gen.yaml
```
Designing gRPC or Connect services
Adding protovalidate constraints
Troubleshooting buf lint or breaking change errors

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

Core Workflow

核心工作流程

1. Match Project Style

1. 匹配项目风格

Before writing proto code, review existing

.proto

files in the project. Match conventions for naming, field ordering, structural patterns, validation, and documentation style. If none exists, ask the user what style should be used or an existing library to emulate.

在编写proto代码前，先查看项目中已有的

.proto

文件。匹配命名、字段排序、结构模式、验证和文档风格的约定。如果没有现有文件，询问用户应采用何种风格或参考哪个现有库。

2. Write Proto Code

2. 编写Proto代码

Apply universal best practices from best_practices.md
Add protovalidate constraints to every field—this is not optional for production APIs
For service templates, see assets/

遵循best_practices.md中的通用最佳实践
为每个字段添加protovalidate约束——这是生产级API的必填项
服务模板请查看assets/

3. Verify Changes

3. 验证变更

Always run after making changes:

bash

buf format -w && buf lint

Check for a Makefile first—many projects use

make lint

make format

Fix all errors before considering the change complete.

每次修改后必须执行：

bash

buf format -w && buf lint

先检查是否存在Makefile——许多项目使用

make lint

或

make format

命令。在确认变更完成前，修复所有错误。

Quick Reference

快速参考

Task	Reference
Field types, enums, oneofs, maps	quick_reference.md
Schema evolution, breaking changes	best_practices.md
Validation constraints	protovalidate.md
Complete service examples	examples.md, assets/
buf CLI, buf.yaml, buf.gen.yaml	buf_toolchain.md
Migrating from protoc	migration.md
Lint errors, common issues	troubleshooting.md
Proto API review checklist	review_checklist.md

任务	参考文档
字段类型、枚举、oneofs、映射	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

Project Setup

项目配置

New Project

新项目

Create directory structure:

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

Use
```
assets/buf.yaml
```
as starting point

Add

buf.build/bufbuild/protovalidate

as a dependency in

buf.yaml

and run

buf dep update

Use
```
assets/buf.gen.*.yaml
```
for code generation config

创建目录结构：

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

以
```
assets/buf.yaml
```
为初始模板

在

buf.yaml

中添加

buf.build/bufbuild/protovalidate

作为依赖，然后运行

buf dep update

使用
```
assets/buf.gen.*.yaml
```
作为代码生成配置

Code Generation Templates

代码生成模板

Template	Use For
`buf.gen.go.yaml`	Go with gRPC
`buf.gen.go-connect.yaml`	Go with Connect
`buf.gen.ts.yaml`	TypeScript with Connect
`buf.gen.python.yaml`	Python with gRPC
`buf.gen.java.yaml`	Java with gRPC

模板	适用场景
`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 File Templates

Proto文件模板

Located in

assets/proto/example/v1/

Template	Description
`book.proto`	Entity message, BookRef oneof, enum
`book_service.proto`	Full CRUD with batch ops, pagination, ordering

位于

assets/proto/example/v1/

目录下：

模板	描述
`book.proto`	实体消息、BookRef oneof、枚举
`book_service.proto`	包含批量操作、分页、排序的完整CRUD服务

Common Tasks

常见任务

Add a new field

添加新字段

Use next sequential field number
Add protovalidate constraints: every field should have validation appropriate to its type (format validators, length bounds, numeric ranges, enum constraints, etc.)
Document the field
Run
```
buf format -w && buf lint
```

使用下一个连续的字段编号
添加protovalidate约束：每个字段都应添加与其类型匹配的验证（格式验证器、长度限制、数值范围、枚举约束等）
为字段添加文档注释
执行
```
buf format -w && buf lint
```

Remove a field

删除字段

Reserve the field number AND name:
protobuf
```
reserved 4;
reserved "old_field_name";
```

Run

buf breaking --against '.git#branch=main'

to verify

保留该字段编号和名称：
protobuf
```
reserved 4;
reserved "old_field_name";
```

执行

buf breaking --against '.git#branch=main'

进行验证

Add protovalidate constraints

添加protovalidate约束

Every field in a production API should have appropriate validation. See protovalidate.md for the full reference.

Common constraints:

String formats:

.string.uuid

.string.email

.string.uri

.string.pattern

String bounds:
```
.string.min_len
```
,
```
.string.max_len
```
Numeric bounds:
```
.int32.gte
```
,
```
.uint32.lte
```
Enum validation:
```
.enum.defined_only
```
,
```
.enum.not_in = 0
```
Repeated bounds:
```
.repeated.min_items
```
,
```
.repeated.max_items
```
Required fields:
```
(buf.validate.field).required = true
```
Oneof required:
```
(buf.validate.oneof).required = true
```

生产级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
```

Verification Checklist

验证清单

After making changes:

Every field has appropriate protovalidate constraints
```
buf format -w
```
(apply formatting)
```
buf lint
```
(check style rules)

buf breaking --against '.git#branch=main'

(if modifying existing schemas)

修改完成后检查：

每个字段都添加了适当的protovalidate约束
执行了
```
buf format -w
```
（应用格式化）
执行了
```
buf lint
```
（检查风格规则）
执行了
```
buf breaking --against '.git#branch=main'
```
（如果修改了现有Schema）