架构与系统设计 / 系统课时

设计事件 Schema 兼容策略

设计事件 Schema 兼容策略

事件一旦被多个消费者订阅,字段就不再只是生产者的内部实现。本节给出一套可执行的 Schema 演进规则:先判断变更是否兼容,再安排生产者与消费者升级顺序,并用契约校验阻断静默破坏。

学习目标

  • 区分可兼容的字段新增与破坏性的删除、改名、改类型
  • 为生产者和多个消费者设计安全的升级顺序
  • 用版本、契约检查和废弃窗口治理事件演进

先把事件当成跨团队契约

事件 Schema 至少约束字段名、类型、是否必填、枚举范围以及字段语义。真正危险的变更往往不是“解析失败”,而是消息仍能解析,却被消费者按旧语义解释。

因此不要只问“序列化能不能通过”,还要同时检查结构兼容与语义兼容。比如把 amount 从“分”改成“元”,即使类型仍是整数,也属于破坏性变更,应新增字段或发布新事件版本,而不是原地改解释。

可以把常见变更分成三类:新增可选字段通常可兼容;删除仍被读取的字段、把可空改为必填、缩小枚举集合通常不兼容;字段改名本质上是“删除旧字段 + 新增新字段”,也应按破坏性变更处理。

为变更定义明确规则

推荐为每个事件固定几条团队级约束:新增字段必须有默认值或允许缺失;已发布字段不得直接改名或改变业务含义;删除字段前必须经过废弃期;消费者必须忽略自己不认识的新增字段;关键枚举要为未知值保留兜底分支。

下面用一个订单事件说明安全新增字段。这里是数据结构示例,不绑定具体消息中间件。

json
{
  "eventType": "OrderCreated",
  "schemaVersion": 2,
  "eventId": "evt-1001",
  "orderId": "ord-9001",
  "amountCent": 12900,
  "currency": "CNY"
}

currency 是新增字段。旧消费者继续只读取 orderId 与 amountCent;新消费者在字段缺失时使用约定默认值,例如 CNY。若要把 amountCent 改成小数金额,不应直接改类型,而应新增 amountDecimal,让两种表示在迁移期并存。

安排生产者与消费者升级顺序

新增字段和删除字段的安全顺序不同。新增字段通常先升级消费者,使其能处理“字段不存在”和“字段已出现”两种情况,再升级生产者开始发送。删除字段则先让所有消费者停止依赖旧字段,确认观测窗口内没有读取,再由生产者停止发送。

事件 Schema 安全升级顺序

对于语义变化,最稳妥的做法不是安排一个“巧妙的升级顺序”,而是显式引入新字段或新事件类型。只有当新旧消费者可以同时正确解释同一条消息时,滚动升级才有意义。

用契约检查阻断静默失效

把 Schema 校验放进 CI,而不是依赖上线后报警。每次变更都应拿“候选 Schema”与当前生产版本比较,至少检查字段删除、必填性变化、类型收窄、枚举收窄和字段语义说明是否改变。

同时记录事件版本与消费者覆盖情况。只有当所有关键消费者都声明支持新版本,生产者才允许启用新字段;只有当旧字段在一个完整业务观察窗口内无人读取,才允许删除。

最终要追求的不是“永远不改 Schema”,而是让每次变更都有兼容规则、升级顺序和可验证的退出条件。这样消息契约即使跨多个团队长期演进,也不会靠口头约定维持。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计事件 Schema 兼容策略

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通