Protobuf schema 演进时，哪些改动会踩坑
接口协议一旦上线就不能随便改，这是常识。但 Protobuf 因为本身支持向前向后兼容，很多人在 schema 更新时习惯比较随意——今天加个字段，明天改下类型，直到出线上问题才发现踩了坑。
我们项目里就有过这样的经历。一次迭代里把某个字段的类型从 string 改成 int32，旧客户端没有这个字段时不报错，但拿到的是默认值 0，业务逻辑判断出错；后来又遇到过加了 repeated 字段、删了已有字段、改了字段的 number，每一项都可能埋雷。
Protobuf 的兼容性不是靠开发者自觉，而是靠数字编号这个机制保证的。理解它的规则，才能在设计 schema 时做出正确取舍。
为什么会有兼容性问题
Protobuf 在解析时，消息里的每个字段都绑定了一个唯一的 field number。序列化后只存 number，不存名字。这带来两个好处：
- 字段改名不影响解析
- 可以跳过不认识的新字段
但也带来一个问题：只要 number 被复用，旧版本就会解析到新字段的内容，结果完全不可预测。
这就是所有兼容性问题的根源。
向后兼容：允许做什么
向后兼容的意思是：新版本发布的 schema，能被旧版本客户端正常解析。
Protobuf 官方支持以下改动，不影响旧客户端：
加字段
message Order {
int32 id = 1;
string name = 2;
// 新增字段，使用未使用的 number
string status = 3;
}
旧客户端收到这个消息时，status 字段会被忽略，完全正常。
删除字段
message Order {
int32 id = 1;
string name = 2;
// status 被删除
}
旧客户端里有 status 字段，服务端发来的消息不再包含它，解析时会使用默认值（空字符串或 0）。没有问题。
修改字段类型：仅限标量到标量，且语义相近
int32↔int64↔uint32↔uint64↔sint32↔sint64：这些在大部分情况下是兼容的，但要注意数值范围变化float↔double：可能损失精度，需要评估bool↔int32：不安全，0/1 在业务上可能代表不同含义
保留被删字段的 number
删除字段时，用 reserved 防止他人复用：
message Order {
int32 id = 1;
reserved 2; // 原 name 字段的 number，禁止再次使用
}
向前兼容：允许做什么
向前兼容的意思是：旧版本客户端能解析新版本服务端发的消息。
条件比较苛刻，只有这些改动安全：
加字段：和向后兼容一样，旧客户端会忽略新字段。
不要动已有字段的 number：任何 number 的修改都会导致解析错位。
不要删除字段：旧客户端仍然期望收到那个字段，如果服务端不再发送，客户端拿到的会是默认值。这个默认值可能是 0、空字符串、false，具体取决于字段类型。如果业务代码依赖这个字段有真实值，就会出问题。
会踩坑的改动
下面这些操作，大概率会让你在某个时间点看到奇怪的问题：
改 number
// 旧 schema
message Order {
int32 id = 1;
string name = 2;
}
// 新 schema
message Order {
int32 id = 1;
string nickname = 2; // 改了字段名但 number 还是 2
string status = 3;
}
如果旧客户端还在用 name 字段，它会把服务端发来的 nickname 的内容读进 name 变量。两个完全不同的语义混在一起，排查起来会很头疼。
从 oneof 里删除字段
message Payment {
oneof method {
string alipay = 1;
string wechat = 2;
string bank_card = 3;
}
}
如果你删掉 bank_card 而旧客户端还在用，旧客户端发来的消息里如果有 bank_card 的值，服务端解析时会出错或者被忽略，取决于你具体的处理方式。
把可选字段改成 required
Protobuf 3 已经去掉了 required，但如果你的项目还在用 Protobuf 2，这是一个明确的兼容破坏。
改 repeated 的顺序
Protobuf 不保证 repeated 字段的顺序语义，除非你的业务代码依赖顺序，否则不用太担心。但如果有语义上的排序要求，需要在协议层明确约定。
管理 schema 演进的实际做法
给字段编号做全局规划
不要在写 schema 的时候随手写 = 1 = 2，而是应该在项目初期就规划好一段可用的 number 范围，比如：
- 1–99：核心字段
- 100–999：业务扩展字段
- 1000+：预留或实验性字段
这样后续加字段时不容易撞号。
用 reserved 封堵废弃的 number
字段一旦删除或废弃，立即加上 reserved：
message Order {
int32 id = 1;
reserved 2, 5, 7; // 曾经用过，现在禁用
string status = 3;
}
这能防止其他开发者在不知情的情况下复用这些 number。
保持字段名字面意义稳定
number 可以不变，但字段名字最好也不要随便改。虽然 Protobuf 不关心名字，但代码生成后的类名、注释、文档都会跟着变，改名会增加迁移成本。
如果确实需要改名，可以暂时保留旧名字作为 deprecated：
message Order {
int32 id = 1;
string name = 2 [deprecated = true];
string nickname = 3; // 新名字
}
为字段变化做版本记录
schema 变更记录不需要很复杂，一个简单的 markdown 文件就够了：
## v1.3
- 新增 Order.status
- 废弃 Order.legacy_flag（保留 number 12 不再使用）
## v1.4
- Order.pay_amount 从 int32 改为 int64
兼容性出问题时怎么排查
线上出现解析异常时，先看这几个方向：
检查 number 是否被复用
这是最常见的原因。对比两个版本的 schema，看是否有 number 指向了不同语义的字段。
检查字段类型是否变更
尤其是 string 和 int32 之间的互改，或者 bool 和 int 的互改。这些改动可能在编译时不会报错，但运行时数据语义完全不同。
检查是否有字段被悄悄删除
旧客户端可能还在发送某个字段，但新 schema 里没有，导致解析异常或服务端字段丢失。
用 protoc 的 --include_imports 导出完整 schema 做 diff
protoc --include_imports --proto_path=. message.proto --descriptor_set_out=messages.bin
然后把两个 .bin 文件拿来做 diff，能直观看到字段变化。
最后说几句
Protobuf 的兼容性设计很合理，但它的"安全"建立在正确使用的基础上。加字段通常没问题，删字段和改 number 需要格外谨慎。
schema 不是代码，它是有生命周期的。每一次变更都应该经过 review，每一条 reserved 都应该认真填写。protocol buffer 不会因为一个错误的 number 报错，但它会在某个深夜让你面对一个很难复现的线上问题。
浙公网安备 33010602011771号