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 解析，结果错乱。
立即学习“go语言免费学习笔记（深入）”；
- 每个
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 名），下游就可能炸。别把它当临时配置文件写。
