给订单表加了一个 channel 字段，改了两行代码、加了一条 DDL，测试环境一路绿灯。上线后下游对账服务开始报解析错误——不是因为它不认识新字段，而是因为它的解析器用位置下标取值，多一个列就整体错位。
这次事故的复盘结论是"下游太脆弱"。但真正的问题是："加字段"这件事在结构层和格式层是两个完全不同的变更，而我们只用一套版本管理去描述它们。
1. 两个维度，四类变更
结构讲的是"有哪些字段、什么类型、什么约束"；格式讲的是"值怎么摆进字节流"。两者的变更自由度完全不同。
| 变更 | 结构层影响 | 格式层影响 | 下游是否可能崩 |
|---|---|---|---|
| 增加一个可空字段 | 加列 | 若按名字取值则无感；按位置取值则错位 | 是，取决于解析方式 |
| 删除一个字段 | 删列 | 字段消失，严格解析器报错 | 是，且不可逆 |
| 字段重命名 | 等价于删加 | 位置不变，名字变了 | 是，最隐蔽的一类 |
| 类型放宽 int → bigint | 类型定义变化 | JSON 里可能完全无感，二进制编码里改变宽度 | 视编码而定 |
空值表示从 null 改为缺省 |
约束不变 | 语义变了 | 是，消费端判空逻辑失效 |
| 时间格式从秒级改毫秒 | 类型不变 | 值域变了 | 是，且不会报错，只会算错 |
这张表最重要的一行是最后一行：格式层的破坏性变更可以完全不报错，只是让下游算出一个错误的数。这类问题不会在故障时间线上出现，只会在某个月的报表里出现。
两个维度还有一个不对称之处值得记住：结构层的变化可以从 DDL 差异里读出来，格式层的变化必须靠真实的序列化往返才能发现。所以团队里"谁负责看结构"通常很明确（有迁移脚本、有评审），"谁负责看格式"往往没有人——因为格式差异在代码 diff 里可能只是改了一个单位换算函数。
2. 向后兼容与向前兼容约束的是不同维度
这两个词经常被当成同义词，实际约束的层次不同。
| 兼容方向 | 定义 | 主要约束 |
|---|---|---|
| 向后兼容 | 新生产者 → 老消费者 | 格式层：老解析器不能报错 |
| 向前兼容 | 老生产者 → 新消费者 | 结构层：新消费者不能假设字段一定存在 |
| 双向兼容 | 两者都成立 | 两个维度都要留余地 |
加字段通常被判定为"向后兼容"，因为它没有删东西。但对按位置解析的老消费者来说，加字段恰恰是不兼容的。所以判断"这次改动兼容吗"，不能只看结构差异，必须先确认消费端的解析方式。
// 同一份数据的两种解析写法，决定了"加字段"是否安全
payload = {"id": 1024, "amount": 99, "channel": "web"}
// 安全：按名字取值，缺字段时给默认值
def parse_by_name(p):
return {"id": p.get("id"), "amount": p.get("amount")}
// 危险：按位置取值，字段数量变化即错位
def parse_by_position(p):
vals = list(p.values())
return {"id": vals[0], "amount": vals[1]}
// 加一个字段后，parse_by_position 的 amount 可能取到 channel
3. 三个独立演进的版本号
把版本号只标在一个地方，是这一整类问题的制度根源。
| 版本对象 | 变更频率 | 谁关心 | 标在哪 |
|---|---|---|---|
| 表结构版本 | 低 | DBA、数据平台 | 迁移脚本序列号（Flyway / Liquibase） |
| 消息格式版本 | 中 | 生产者、消费者 | 消息头字段、schema registry |
| API 契约版本 | 中高 | 前端、外部接入方 | URL 路径或请求头 |
三者的版本号必须各自独立。共用一个是常见错误：API 版本升到 v2，但表结构没动、消息格式也没动，于是下游看到 v2 就以为格式变了。
最麻烦的情况是三者都被同一个"发布版本"覆盖，比如 2026.11.09。这个号一变，下游无法判断该不该重新评估兼容性，只能全量回归一次；它不变，下游又不知道内部发生了什么。结果是每次变更都触发最贵的验证方式，久而久之验证就被跳过了。
反过来，如果消息格式升级了却沿用同一个 API 版本，消费方从版本号上看不出任何提示。
// 三个版本各归各处，互不替代
api:
version: "v2" // 契约层：路径 /v2/orders
message:
schema_id: 41 // 格式层：注册中心里的格式编号
structural_version: 7 // 结构层：字段集合的版本
db:
migration: "V20261109_03__add_channel.sql" // 结构层：DDL 序列
4. 加字段为什么看起来安全却经常出问题
四类具体机制，每类都在测试环境里难以复现。
| 机制 | 触发条件 | 表现 |
|---|---|---|
| 非空约束 + 无默认值 | 存量行写入 | 加列语句在有大表的库上失败或长时间锁表 |
| 旧消费者的严格解析 | 消费端用强校验解析器 | 多一个字段直接抛异常 |
| 按位置序列化 | 定长记录、CSV、数组形式 | 静默错位，不报错 |
| 下游的字段白名单 | 消费端只接受已知字段 | 整条记录被丢弃 |
第一类在数据量大的表上尤其危险：给一张千万行的表加一个非空且无默认值的列，在部分数据库版本上会重写整表。安全做法是先加可空列、回填、再加约束，三步分开。
// 安全的三步：加可空 → 回填 → 加约束，每步都可单独回滚
ALTER TABLE orders ADD COLUMN channel VARCHAR(32) NULL;
UPDATE orders SET channel = 'legacy' WHERE channel IS NULL LIMIT 10000; // 分批
ALTER TABLE orders MODIFY COLUMN channel VARCHAR(32) NOT NULL DEFAULT 'legacy';
// 每步之间至少留一个观察窗口，确认无慢查询与主从延迟
5. 迁移的顺序约束
顺序错了，再好的方案也会出事故。这三条约束是硬的，不能按项目节奏调整。
| 阶段 | 该做什么 | 不能做什么 |
|---|---|---|
| 扩展期 | 加结构、双写、老代码仍可运行 | 删字段、改语义 |
| 迁移期 | 新老并行读、比对差异 | 只切一半就宣布完成 |
| 收缩期 | 确认无消费后停写老字段、再删结构 | 在双写期间删中间态 |
最常被跳过的是"新老并行读、比对差异"这一步。它看起来多余（毕竟双写已经保证了），实际上是唯一能发现"两条路径语义不一致"的手段。跳过它的团队，问题会在切换后的第一个月以数据对不上的形式出现。
还有个常被忽略的约束：双写期间必须能比对。如果两条路径写入后互相覆盖、或者只有一条可读，那么这个阶段形同虚设。可行的做法是让新老路径写到不同的列或不同的表，比对完成后再合并。
// 双写期：两条路径写不同列，比对差异，不做覆盖
ALTER TABLE orders ADD COLUMN channel_new VARCHAR(32) NULL;
// 定时比对：找出两条路径结果不一致的行，这才是格式层问题的唯一证据
SELECT id,
channel AS old_val,
channel_new AS new_val
FROM orders
WHERE channel_new IS NOT NULL
AND (channel <=> channel_new) = 0 // <=> 处理 NULL 安全比较
LIMIT 200;
// 差异率持续为 0 才允许进入收缩期
契约兼容性测试应该测哪一层，也有明确答案：测格式层。因为结构层的差异可以从 DDL 直接看出来，格式层的差异只能靠真实的序列化往返来验证。
// 格式层兼容性验证：用旧版本解析新数据，必须不报错
schema_registry_check --subject orders-value \
--new-schema orders_v8.avsc \
--compat BACKWARD
// BACKWARD = 新格式能被旧消费者读；FULL = 双向都要成立
// 注意：这只验证格式层，字段语义变化（如秒改毫秒）它查不出来
6. 排错：五种"改了但说不清哪里坏了"
| 现象 | 成因 | 处理方向 |
|---|---|---|
| 下游解析报错但字段没删 | 加字段撞上按位置解析 | 改消费端为按名解析，或加显式版本号 |
| 数据对不上但无异常日志 | 格式层语义变更（单位、精度、时区） | 比对双写期间的两条路径输出 |
| 某消费端整条记录被丢弃 | 字段白名单/严格校验 | 放宽校验或同步白名单 |
| 加列卡住整张表 | 非空无默认值导致重写 | 拆成加可空、回填、加约束三步 |
| 版本号升了但下游没反应 | 三个版本号共用了一个 | 拆开标注，各自独立演进 |
第二条最难查，因为它不产生错误。定位方法只有一个：在双写期间把两条路径的结果存下来做差异比对，而不是等报表出来再回头找。
四条排错经验的共同点是：它们都不在错误日志里。结构层的问题会以 DDL 报错、锁等待、迁移脚本失败的形式出现，有明确的报错信息；格式层的问题只有三种可见形态——下游解析异常、数据对不上、记录被静默丢弃。前一种可以靠看日志，后两种只能靠比对。
所以建立一件事是值得的：把"格式层变更"单独列成一份清单，每次发布附上。清单内容只有三列——哪个字段、语义怎么变、谁验证过。它比任何自动化检查都便宜，而且能被评审看见。
7. 边界：什么情况不值得分层管理版本
| 场景 | 为什么可以简化 | 做法 |
|---|---|---|
| 单一消费者且同仓部署 | 结构变更可原子发布 | 一个版本号足够 |
| 数据不落盘（纯内存传递） | 没有跨版本共存 | 随发布一起切 |
| 生命周期短于一个发布周期 | 不会出现新老共存 | 不做兼容设计 |
| 内部临时接口 | 消费方可随时改 | 约定即可 |
判断口径一句话：是否存在"新老版本同时运行"的时间窗口。存在就必须分层管理版本；不存在，层数就是纯负担。
8. 自测
- 结构与格式的差别用一句话怎么表述？为什么格式层的破坏性变更可能完全不报错？
- 加字段为什么会被判为"向后兼容"，却在某些消费端造成破坏？
- 三个版本号分别对应什么对象？共用会带来什么具体后果？
- 给千万行表加非空列，安全的三步是什么？每步为什么不能合并？
- 迁移的三个阶段里，最常被跳过的是哪一步？跳过后的典型症状是什么？
- 契约兼容性测试为什么应该测格式层而不是结构层？