你加了一个字段,生产环境炸了:论 API 兼容性的真正战场
先说一个我亲眼见过的翻车现场。
某次迭代,团队给订单服务的 protobuf 消息加了个字段 user_tier。逻辑测试全绿,联调全绿,上线也全绿。第二天早上七点,客服工单爆了:App 端下单页面报「订单创建失败」。
原因简单得让人想笑:他们复用了旧字段的编号。老字段 amount 是 3 号,新人把 amount 删了,把 3 号给了 user_tier。服务端发的是 int64,客户端按 string 解析,直接炸在解码器里。
事故报告最后写的是:「缺乏严谨的变更管控」。
但我读完那份报告只想说:问题不在流程,在于大家把「兼容」这件事想得太表面了。
一、版本号是最没用的设计
教科书教我们做 API 版本管理:/v1/orders、/v2/orders,不兼容就升版本。听起来很稳,实操起来是个坟场。
问题在于:版本号只能表达「不兼容」,却无法表达「哪里不兼容」。你把 /v1 下线,需要所有客户端都迁移完——但移动端有用户三个月不升级,嵌入式设备可能五年不动。你一旦有了几十个 /v1/x、/v2/x,改一个字段要发六个版本,而且这六个版本从此并行存在,你再也删不掉任何一个。
更反直觉的是:绝大多数变更其实是兼容的。加个可选字段、改个描述文案、加个枚举值——按「是否不兼容」一刀切,这些全要升版本,等于每次迭代都在制造版本垃圾。
所以真正的工程实践是反过来:默认兼容,不兼容才做破坏性变更。这要求我们把注意力从「版本号」挪到「契约的字节表示」上。
二、真正的兼容战场:字段编号,而不是字段名字
Protobuf 的 wire format 有个反直觉的设计:字段名字在传输层根本不存在。传输的只有「字段编号 + wire type + 值」。
这意味着字段编号才是这个字段的身份证,名字只是给人看的注释。它让改名几乎免费,也让它成为最容易踩坑的地方,因为所有人都直觉上把「名字」当成身份。
message Order {
int64 order_id = 1;
string customer = 2;
int64 amount = 3; // 3 号:金额,单位分
string user_tier = 4; // 4 号:用户等级
}
如果你想知道线上那些坑具体长什么样,看这个 wire type 编码就清楚了:
// varint 编码的字段头:(field_number << 3) | wire_type
// wire_type: 0=varint 1=64bit 2=length-delimited 5=32bit
message Order {
int64 order_id = 1; // tag = (1<<3)|0 = 0x08
string customer = 2; // tag = (2<<3)|2 = 0x12
int64 amount = 3; // tag = (3<<3)|0 = 0x18
}
字段头只有一个字节或几个字节,它只带编号和类型,不带名字。这意味着:老客户端收到它不认识的新字段编号,会原样跳过(这是 protobuf 的向前兼容);而如果你把 3 号的语义从 amount 换成 user_tier,老客户端不会跳过,它会拿 3 号当 int64 解出来,然后看到一个「金额是用户等级」的鬼东西——要么报错,要么写进数据库污染业务。
所以 protobuf 社区第一条铁律是:永远不要复用、不要回收字段编号。字段废弃了,编号就进 reserved 墓碑:
message Order {
int64 order_id = 1;
string customer = 2;
// 已废弃:coupon_id 曾经是 3 号,2019 年下线。
// 保留编号,防止有人再把它分配给别的字段。
reserved 3;
reserved "coupon_id";
int64 amount = 4; // 挪到新编号,向后兼容
string user_tier = 5;
}
注意细节:把 amount 从 3 挪到 4 不是破坏性变更,前提是服务端同时发布、双跑。因为 wire format 里只有编号,客户端只要按编号解,3 号在新消息里消失了(客户端用默认值),4 号是新数据。老客户端不认识 4 号会丢弃,但这也意味着老客户端拿不到 amount 了——所以真正的做法是双写:保留旧编号发旧字段,同时发新编号。
这就是「墓碑 + 双写」这套组合拳的由来。
三、一张能直接贴在墙上的演进对照表
这张表我整理自多次线上事故复盘,涵盖 protobuf、gRPC、Thrift、Avro 以及 JSON 化场景下的通用规则:
- 新增字段:安全。前提是可选(有默认值),且新字段不要成为必填语义。
- 删除字段:语法上安全(老客户端忽略未知编号),但语义上要看你是否还在发这个编号给新客户端。正确姿势是
reserved标墓碑 + 停止填充。 - 修改字段名:wire 层安全,但 JSON/proto3 JSON 映射层会炸!proto3 的 JSON 编码默认用字段名,客户端按名字取。这是最隐蔽的雷。
- 修改字段类型:只在「wire type 兼容家族」内安全——int32/int64/uint32/uint64/bool/enum 互通;string/bytes 与 varint 类不互通。string 改 bytes 也是雷(UTF-8 校验)。
- 修改字段号:破坏性。除非配合双写与灰度,否则直接判定不兼容。
- 给 oneof 加分支:安全。但要注意 protobuf 允许「最后一个分支被读走」,加分支会让某些「同时设置多个分支」的旧代码行为变化。
- 给 enum 加值:客户端如果用 switch 且没 default,遇到未知值会抛异常或走错分支。生产环境的 enum 必须有未知值兜底。
- 把 optional 改成 required:在 proto3 里没这个概念,但在 proto2 / Avro / Thrift 里有,等于给所有老客户端判死刑。
我特别想强调第二条里 JSON 映射层的坑。我见过一个团队,proto 文件里把 coupon_id 改名成 discount_id,proto 服务全绿,但某个内部网关把 protobuf 转 JSON 再给前端,前端字段直接变 undefined。因为 JSON 化传输把「编号制」退化成「名字制」,protobuf 的兼容性优势瞬间蒸发一半。
结论:只要你的数据会经过 JSON 那一层,字段名就是 ABI,而不只是给人看的注释。
四、别靠人肉 review,工具会在你犯错前抓住你
手写 review 规则是不可靠的。人类 reviewer 看到「改了个字段名」,脑子里想的是「这是不是兼容的」,而答案往往是「看下游怎么用」。所以必须上工具。
# buf.yaml
version: v2
lint:
use: [STANDARD]
breaking:
use: [FILE]
ignore:
- pkg/legacy/v1pb # 冻结的老版本目录,明确豁免
# 检查当前分支相对主分支是否有破坏性变更
buf breaking --against '.git#branch=main'
# 输出示例:
# FIELD_NO_DELETE: pkg/orders.proto:12
# Field "Order.coupon_id" on message "Order" was deleted.
# Do not use 'reserved' ...
同类工具还有 Confluent Schema Registry 的兼容性模式:BACKWARD(新消费者读旧数据)、FORWARD(老消费者读新数据)、FULL(两个都要)。Kafka 这类流式场景至少要开 FULL,因为你控制不了所有消费者什么时候升级。
我的经验是:把 breaking check 挂进 CI,让它比单元测试更早失败。合并请求门禁里跑一次,比上线后回滚一次便宜三个数量级。
五、契约不止是 protobuf:数据库和事件同样会炸
很多人只盯着 RPC 契约,其实最容易出事的是共享数据库。
典型翻车链:新同事给订单表加了列 refund_status,类型 varchar(32),没加默认值也没回填。服务 A 用老代码没问题;服务 B 上线后 ORM 生成了带该字段的 INSERT,老库表里没这列,插入直接失败。更糟的是滚动重启:第 3/5 个实例带着新代码连上老版本数据库,直接 500。
规则很简单但很少有人遵守:
- 加列必须带默认值,且默认值要是「旧代码能理解」的语义(数字 0、空串,而不是
'unknown'这种需要解释的字符串)。 - 加列和加索引分开两个发布走。即使是 online DDL,大表上仍可能因为
ALTER持锁而抖动。 - 删列走两阶段:先停止读写该列 → 观察一个完整发布周期 → 再删。
- 代码里禁止
SELECT *。它让「加一列」从零成本变成「全链路炸裂」,在 SQL 注入面前还会把密码列带进日志。
消息事件也一样。如果直接把数据库实体序列化后扔进消息队列,你等于把 schema 变成了「数据库的物理结构」,任何一次 ALTER TABLE 都可能变成消费者侧的崩溃。消息契约必须自己拥有、独立演进,别当数据库的影子。
六、消费者驱动的契约测试:让「下游说了算」
光有兼容性检查还不够,因为你永远不知道「哪些字段真的有人在用」。更狠的一招是让下游消费者来声明需求:
// provider (订单服务) 侧的 pact 契约
given("存在一个已支付订单", () -> {
when("查询订单详情", () -> {
then("返回字段包含 order_id 与 amount", () -> {
assertThat(response.path("order_id")).isNotNull();
assertThat(response.path("amount")).isNotNull();
});
});
});
// 消费者 (风控服务) 侧断言
verifyPact({
consumer: "risk-service",
provider: "order-service",
providerStates: { "已支付订单": () -> seedOrder(...) }
});
它的价值在于:当你想删一个字段时,消费者会直接跳出来说「我在用」,而不是让你靠记忆和祈祷。字段是否废弃、什么时候能删,全部有了客观依据。
七、那版本号什么时候有用?
不是完全没用,但它的定位应该被纠正:
版本号是「不兼容变更的隔离墙」,不是「每次迭代的编号」。
只有在以下几种情况才值得开新版本:
- 语义发生了根本改变(比如
amount从「分」改成「元」,字段名没变但含义变了——这是最脏的破坏,等于给用户制造十倍的价格差); - 字段被彻底删除且无法通过双写过渡;
- 枚举的语义重构;
- 客户端群体无法同步升级(嵌入式、第三方开放 API)。
其余九成场景,你都应该老实地做到「零客户端改动、零版本号增长」。能做到这点,你的 API 才能活过三年,而不是活过三次发布。
八、一份能今天就落地的检查清单
- 所有 proto 文件启用
buf lint+buf breaking,挂 CI 门禁; - 删除的字段一律
reserved,编号和名字都保留; - 字段改名只在 wire 层做,JSON 暴露层用
json_name保留旧名字; - enum 客户端必须有未知值兜底分支;
- 数据库 DDL 与代码发布解耦,加列带默认值;
- 上线前跑一次真实客户端回归(用真机 App 或老版本二进制,别只跑单测);
- 关键契约用 Pact 锁住消费者依赖。
写代码时我们总习惯把注意力放在业务逻辑上。但真正让服务在半夜被叫醒的,往往不是逻辑写错了,而是两个本来互不影响的模块,因为一个字段编号、一个列名,被硬生生焊在了一起。
兼容性不是发布前的检查项,它是设计时就该想清楚的东西。把字段编号当成身份证、把数据库列当成别人的表、把消息体当成独立契约——很多半夜的告警就自然消失了。
而版本号,它只是最后那扇门。大多数时候,我们根本不需要推开它。