消息队列 / 系统课时

消息模式与兼容演进

消息模式与兼容演进

消息契约真正困难的不是第一次定义字段,而是生产者和消费者不能同时升级。本篇用一套兼容演进规则处理新增字段、废弃字段、默认值和版本路由,让新旧应用可以在同一段迁移窗口内稳定共存。

学习目标

  • 判断字段变更是兼容升级还是破坏性升级
  • 用默认值和渐进废弃降低新旧消费者的升级耦合
  • 在同 Topic 演进与新版本路由之间做出选择

先用消费者视角判断兼容性

判断一次变更是否安全,关键问题是:旧消费者能否读取新消息,新消费者能否读取旧消息。只要迁移期间两种情况都可能发生,就不能假设所有实例已经同步升级。

新增字段时,应让旧消费者能够忽略它,同时让新消费者在字段缺失时有合理默认值。删除字段时不要立刻停止发送,而是先让所有消费者不再依赖,再经过观察窗口后移除。字段类型和语义一旦改变,风险通常高于单纯增删字段。

消息模式兼容演进与版本路由

新增字段要给旧消息留退路

假设订单事件最初只有 orderId 和 amount,现在要增加 currency。兼容做法是把它作为可选信息发布,并约定消费者在字段缺失时按业务规则使用默认值,例如历史数据统一按 CNY 解释。

下面向同一个 Topic 发送 v1 与 v2 两种消息,再读取它们,模拟滚动升级期间新旧消息并存。

bash
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic dev.order.order-created.v1 --partitions 1 --replication-factor 1
printf '%s\n' '{"schemaVersion":1,"orderId":"o-1001","amount":12800}' '{"schemaVersion":2,"orderId":"o-1002","amount":9900,"currency":"CNY"}' | kafka-console-producer.sh --bootstrap-server localhost:9092 --topic dev.order.order-created.v1
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic dev.order.order-created.v1 --from-beginning --max-messages 2

预期输出

text
Created topic dev.order.order-created.v1.
{"schemaVersion":1,"orderId":"o-1001","amount":12800}
{"schemaVersion":2,"orderId":"o-1002","amount":9900,"currency":"CNY"}

新消费者读取第一条消息时,应把缺失的 currency 映射为约定默认值,而不是直接报错。旧消费者读取第二条消息时,应忽略自己不认识的 currency 字段。

废弃字段采用“停止依赖再停止发送”

假设已有字段 customerName 准备废弃,正确顺序是先发布消费者新版本,让它不再依赖该字段;观察所有消费者组完成升级后,生产者再停止填充;最后经过保留与回滚窗口后,才从模式定义中删除。

字段可以先保留但标记废弃。Protobuf 删除字段后应保留对应编号与名称,避免未来复用;Avro 或 JSON Schema 则要继续遵守字段名、类型和默认值的兼容规则,不能把旧字段改成完全不同的含义。

默认值必须代表真实业务语义

默认值不是为了让解析器不报错,而是要保证旧消息在新逻辑中仍有确定含义。像 currency=CNY 只有在历史订单确实全部为人民币时才安全;如果历史数据币种未知,就应使用 UNKNOWN 或显式空值,并让后续逻辑处理“不确定”状态。

同理,布尔值默认 false、数值默认 0 看似方便,却可能把“旧消息没有这个概念”误解成真实业务值。默认值应由领域语义决定,而不是由字段类型决定。

只有破坏性变化才升级路由版本

兼容新增字段通常继续使用原 Topic,不要每次变化都创建 v2、v3,否则消费者、ACL、监控和回放链路都会被版本数量拖累。

当字段类型改变、关键标识语义改变、事件从“订单已创建”变成另一种业务事实,或新消费者无法正确解释旧消息时,才创建新的主版本 Topic。迁移时让新消费者先具备同时读取旧版与新版的能力,再切换生产流量,最后退役旧路由。

兼容演进的目标不是让模式永远不变,而是让每次变化都能在滚动升级、消息重放和版本回退时保持可解释。只要字段语义、默认值和版本边界都明确,生产者与消费者就不必被迫同时上线。

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

目录与阅读设置

阅读设置

17

记录一个想法

消息模式与兼容演进

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

登录哪都通