17370845950

proto文件是gRPC强约束ABI契约：必须首行syntax="proto3"；go_package决定Go路径而非package；字段编号不可复用且需预留扩展空间；service需按实际通信模式选unary/流式类型。

proto 文件是 gRPC 服务的契约起点，不是“写完就能跑”，而是定义即约束。写错一个字段编号、漏掉 option go_package、或误用 package，后续生成代码就会报错、包路径混乱、客户端调不通——这些不是运行时问题，而是编译期就卡死。

---

proto3 语法必须显式声明，且不能混用 proto2

gRPC 官方只支持 proto3，不兼容 proto2 的 required/optional 语义。一旦忘记写或写成 syntax = "proto2";，protoc 会静默降级或报错（取决于插件版本），但生成的 Go 代码可能缺少零值处理逻辑，导致解码 panic。

• 必须放在文件第一行，且独占一行：syntax = "proto3";
• 所有字段默认可选（no presence），string 字段为 "" 而非 nil；如需显式区分“未设置”和“设为空字符串”，得用 wrapper 类型（如 google.protobuf.StringValue）
• 避免在同一个项目中混用 proto2 和 proto3 文件，尤其是有 import 依赖时

---

option go_package 是生成 Go 包路径的唯一权威来源

很多人以为 package pb; 决定 Go 包名，其实它只影响 Protobuf 命名空间（比如跨语言引用）。真正控制 go install 后的导入路径、go mod 识别、以及 protoc-gen-go 输出目录的是 option go_package。

• 格式必须是 option go_package = "路径;包名";，例如：option go_package = "./user;userpb";
• 路径部分（分号前）是相对于 protoc 当前工作目录的输出子目录；包名（分号后）是生成文件顶部的 package userpb
• 如果省略或写错（如写成 option go_package = "userpb"; 缺少路径），生成的 .pb.go 会默认放到当前目录，且包名可能与预期不符，引发 import cycle 或 undefined: xxx

---

字段编号不能重复，删除字段后编号也不能复用

Protobuf 序列化靠字段编号（=1, =2）定位数据，不是靠字段名。一旦服务已上线、客户端已部署，改编号等于破坏 wire 协议兼容性——旧客户端发来的 uid=1 会被新服务当成 name=1 解析，结果错乱。

• 每个 message 内字段编号必须唯一，否则 protoc 直接报错：Field number 1 has already been used
• 废弃字段应保留编号并加注释，改用 reserved 防复用：reserved 3, 5; reserved "old_field";
• 新增字段一律用未使用过的编号，推荐从 100 起跳（留出扩展空间），避免和早期字段冲突

---

service 定义要匹配实际通信模式，别硬套 unary

gRPC 支持四种 RPC 类型，但很多人一上来全写 rpc Method(Request) returns (Response)（unary），等遇到流式场景才回头改——这时客户端/服务端都要大改，且历史接口无法平滑迁移。

• 服务器流（server streaming）：适合列表查询、日志推送，定义为 rpc ListUsers(ListReq) returns (stream User);
• 客户端流（client streaming）：适合大文件分块上传，定义为 rpc Upload(stream Chunk) returns (UploadResult);
• 双向流（bidi streaming）：适合实时协作、聊天，定义为 rpc Chat(stream Message) returns (stream Message);
• 生成代码后，对应方法签名完全不同（带 ServerStream/ClientStream 接口），不能靠类型断言补救

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (stream User);  // ← 这行生成的函数签名和上一行完全不兼容
}

最常被忽略的一点：

proto 不是文档草稿，它是强约束的 ABI 接口定义。字段删了、类型改了、服务重命名了，只要没做兼容性设计（比如用 oneof、预留字段、版本化 service 名），下游就可能炸。别把它当临时配置文件写。