proto3必须显式声明syntax = "proto3";，否则按proto2解析导致字段语义、零值判断和Go结构体类型不一致；go_package需完整指定路径和包名；字段编号1–15优先高频字段；负数用sint32/sint64。
proto3语法必须显式声明，否则默认用proto2
不写 syntax = "proto3"; 的第一行，protoc 会按 proto2 解析，而 proto2 和 proto3 在字段默认值、optional/required 语义、nil 检查行为上完全不同——Go 生成的 struct 字段可能全为零值却无法区分“未设置”和“设为零”，导致反序列化后逻辑出错。
常见错误现象：proto.Unmarshal 成功但字段全是零值，user.Age 明明传了 0 却被当成未赋值；或者 user.GetAge() panic，因为 proto2 生成的 getter 方法在未设置时返回指针，而 proto3 默认生成值类型。
- proto3 中
int32 age = 2;生成的是Age int32字段，0 就是合法值 - proto2 中同名字段生成的是
Age *int32，0 需通过GetAge() != nil判断是否设置 - 务必把
syntax = "proto3";放在 .proto 文件**第一个非空非注释行**，且前后不能有空白行干扰
go_package 选项必须完整，否则 import 路径和包名不一致
option go_package = "path;name"; 里 path 是生成文件的相对或绝对路径（影响 go build 查找），name 是该文件的 package 名（影响代码中 import 别名和类型引用）。两者不一致会导致编译失败或运行时 panic。
常见错误现象：import "service" 编译报错 “cannot find module providing package service”，或明明生成了 user.pb.go 却提示 undefined: service.User。
立即学习“go语言免费学习笔记（深入）”；
- 若想生成到
./pb/user.pb.go且包名为pb，写option go_package = "./pb;pb"; - 若想生成到
$GOPATH/src/github.com/your/repo/pb，写option go_package = "github.com/your/repo/pb;pb"; - 不要省略分号，也不要写成
option go_package = "pb";（旧写法，已弃用）
字段编号 1–15 优先分配给高频字段
Protobuf 二进制编码中，字段编号 1–15 仅占 1 字节 tag，16–2047 占 2 字节，编号越大编码越冗余。对高频传输或小体积敏感场景（如 IoT 设备上报），编号分配直接影响 wire size 和解析速度。
性能影响：单条消息多 1 字节 tag，百万级请求就多出近 1MB 网络流量；更关键的是，CPU 在解码时需多一次字节读取和位运算。
- 把
string id = 1;、int32 status = 2;这类必填字段放前面 - 把
repeated string tags = 18;、bytes payload = 23;这类可选/大字段放后面 - 跳过 19000–19999 区间（protobuf 内部保留），避免未来升级冲突
int32/int64 不适合可能为负的字段
Protobuf 的 int32 和 int64 使用变长 zigzag 编码，负数会被编码成超长字节（例如 -1 编码为 0xFE），比正数膨胀数倍。实际中若字段可能为负（如温度、位移、差值），应改用 sint32 或 sint64。
容易踩的坑：用 int32 delta = 1; 表示变化量，结果 -5 的编码长度是 +5 的 5 倍，wire size 突增且解码变慢。
- 正负皆可 → 用
sint32/sint64 - 非负整数 → 用
uint32/uint64（更明确语义，且编码效率略优） - 固定范围小整数（如状态码 0–100）→
int32可接受，但编号仍建议 ≤15
