架构与系统设计 / 系统课时
设计事件 Schema 兼容策略
设计事件 Schema 兼容策略
事件一旦被多个消费者订阅,字段就不再只是生产者的内部实现。本节给出一套可执行的 Schema 演进规则:先判断变更是否兼容,再安排生产者与消费者升级顺序,并用契约校验阻断静默破坏。
学习目标
- 区分可兼容的字段新增与破坏性的删除、改名、改类型
- 为生产者和多个消费者设计安全的升级顺序
- 用版本、契约检查和废弃窗口治理事件演进
先把事件当成跨团队契约
事件 Schema 至少约束字段名、类型、是否必填、枚举范围以及字段语义。真正危险的变更往往不是“解析失败”,而是消息仍能解析,却被消费者按旧语义解释。
因此不要只问“序列化能不能通过”,还要同时检查结构兼容与语义兼容。比如把 amount 从“分”改成“元”,即使类型仍是整数,也属于破坏性变更,应新增字段或发布新事件版本,而不是原地改解释。
可以把常见变更分成三类:新增可选字段通常可兼容;删除仍被读取的字段、把可空改为必填、缩小枚举集合通常不兼容;字段改名本质上是“删除旧字段 + 新增新字段”,也应按破坏性变更处理。
为变更定义明确规则
推荐为每个事件固定几条团队级约束:新增字段必须有默认值或允许缺失;已发布字段不得直接改名或改变业务含义;删除字段前必须经过废弃期;消费者必须忽略自己不认识的新增字段;关键枚举要为未知值保留兜底分支。
下面用一个订单事件说明安全新增字段。这里是数据结构示例,不绑定具体消息中间件。
{
"eventType": "OrderCreated",
"schemaVersion": 2,
"eventId": "evt-1001",
"orderId": "ord-9001",
"amountCent": 12900,
"currency": "CNY"
}currency 是新增字段。旧消费者继续只读取 orderId 与 amountCent;新消费者在字段缺失时使用约定默认值,例如 CNY。若要把 amountCent 改成小数金额,不应直接改类型,而应新增 amountDecimal,让两种表示在迁移期并存。
安排生产者与消费者升级顺序
新增字段和删除字段的安全顺序不同。新增字段通常先升级消费者,使其能处理“字段不存在”和“字段已出现”两种情况,再升级生产者开始发送。删除字段则先让所有消费者停止依赖旧字段,确认观测窗口内没有读取,再由生产者停止发送。

对于语义变化,最稳妥的做法不是安排一个“巧妙的升级顺序”,而是显式引入新字段或新事件类型。只有当新旧消费者可以同时正确解释同一条消息时,滚动升级才有意义。
用契约检查阻断静默失效
把 Schema 校验放进 CI,而不是依赖上线后报警。每次变更都应拿“候选 Schema”与当前生产版本比较,至少检查字段删除、必填性变化、类型收窄、枚举收窄和字段语义说明是否改变。
同时记录事件版本与消费者覆盖情况。只有当所有关键消费者都声明支持新版本,生产者才允许启用新字段;只有当旧字段在一个完整业务观察窗口内无人读取,才允许删除。
最终要追求的不是“永远不改 Schema”,而是让每次变更都有兼容规则、升级顺序和可验证的退出条件。这样消息契约即使跨多个团队长期演进,也不会靠口头约定维持。