架构与系统设计 / 系统课时
事件版本变化怎么保持兼容
事件版本变化怎么保持兼容
订单事件只是新增一个渠道字段,旧消费者却开始报错;金额字段类型没变,消费者又可能算错一百倍。本篇区分结构兼容与业务语义兼容,用新旧读取器交叉测试,并给出多版本并存时的发布与退役路径。
学习目标
- 判断字段新增、删除、类型和语义变化的兼容风险。
- 用新旧消费者交叉读取样本,验证默认行为和业务结果。
- 设计兼容升级与破坏性升级的共存、回滚和退役条件。
先说明谁要读取谁的数据
“兼容”必须带方向,不能只说新版本能运行。以下方向采用 Schema Registry 文档中的定义;新旧指载荷契约,而不是应用部署时间。([Confluent 文档][2])
| 兼容方向 | 必须成立的读取关系 | 保护的场景 |
|---|---|---|
| 向后兼容 | 新消费者读取旧数据 | 历史回放、旧生产者仍在运行 |
| 向前兼容 | 旧消费者读取新数据 | 消费者尚未全部升级 |
| 双向兼容 | 上述两个方向都成立 | 新旧生产者与消费者并存 |
业务版本不要借用 CloudEvents 的 specversion。本篇约定兼容新增保持 type 的 .v1 后缀,破坏契约才改为 .v2;用 dataschema 的不同 URI 标识具体载荷模式。版本后缀是团队选择,不是 CloudEvents 强制格式。([GitHub][3])
按消费者受到的影响分类
下面是针对本篇订单事件的评审规则,不是所有序列化格式通用的兼容性判定表。判断重点是:旧消息会不会缺值,旧消费者会不会拒收,新旧双方是否仍得到相同业务含义。
| 变化 | 主要风险 | 本篇处理原则 |
|---|---|---|
| 新增可选字段 | 旧消费者拒绝未知字段 | 验证旧端接受新字段,新端定义缺失行为 |
| 新增必填字段 | 历史消息没有该字段 | 先允许缺失,或建立独立新版本 |
| 删除或重命名字段 | 旧消费者仍依赖原字段 | 先增加替代字段并迁移,最后删除 |
| 改类型、单位或语义 | 解码失败或结果悄悄错误 | 使用新字段或新主版本,不原地偷换 |
| 增加枚举值 | 旧分支无法处理新取值 | 先验证未知值策略,必要时升级旧端 |
例如,旧 JSON Schema 在相应对象层设置了 additionalProperties: false,新增可选字段也会被拒绝。是否兼容还取决于实际模式、序列化器及消费者逻辑,不能把“字段可选”直接等同于“双向兼容”。([JSON Schema][4])
用交叉读取测试验证默认行为
下面是完整的 Python 3.10 及以上版本可运行程序,无第三方依赖。保存为 compat_demo.py,执行 python compat_demo.py。样本只测试 data 中的核心字段:旧载荷没有 channel,新载荷新增它,金额始终以分计量。
def read_v1(data):
# 旧消费者忽略未知字段,但严格校验依赖的金额字段。
amount = data["totalAmountMinor"]
currency = data["currency"]
if type(amount) is not int or amount < 0:
raise ValueError("金额必须是非负整数分")
if currency != "CNY":
raise ValueError("本例仅接受 CNY")
return amount, currency
def read_v11(data):
amount, currency = read_v1(data)
# 缺失才使用默认值;null 和空字符串不是缺失。
channel = data.get("channel", "unknown")
if not isinstance(channel, str) or not channel:
raise ValueError("channel 必须是非空字符串")
return amount, currency, channel
def main():
old = {"totalAmountMinor": 12900, "currency": "CNY"}
new = {**old, "channel": "app"}
# 同时覆盖新旧读取器与新旧载荷的四种组合。
for reader in (read_v1, read_v11):
for label, payload in (("old", old), ("new", new)):
result = reader(payload)
assert result[:2] == (12900, "CNY")
print(f"{reader.__name__} <- {label}: {result}")
# 类型被改成字符串时,不能静默转换后继续处理。
bad = {**new, "totalAmountMinor": "12900"}
try:
read_v11(bad)
except ValueError:
print("bad-type: rejected")
else:
raise AssertionError("错误类型不应通过")
if __name__ == "__main__":
main()预期输出:
read_v1 <- old: (12900, 'CNY')
read_v1 <- new: (12900, 'CNY')
read_v11 <- old: (12900, 'CNY', 'unknown')
read_v11 <- new: (12900, 'CNY', 'app')
bad-type: rejected旧读取器只读取所需字段;新读取器把缺失渠道解释为 unknown,表示历史事件没有记录渠道,而非猜测真实渠道。错误金额类型则被拒绝,不能为了兼容就把所有异常值强行转换。
这四个组合通过,只证明当前样本成立,不等于证明全部数据双向兼容。还要补充缺失、null、未知枚举和金额边界;金额单位改变应通过已知订单总价的业务断言发现,不能只检查“仍然是整数”。
让新旧版本有明确的共存路径
如果只保证向后兼容,先升级所有相关消费者,再发布新格式;不能让仍按旧契约运行的消费者冒险读取新数据。双向兼容经过验证时,才允许新旧双方独立滚动升级。([Confluent 文档][2])
破坏性变化需要旧消费者继续运行时,本篇采用隔离版本通道的迁移方案。先保持旧契约不动,再迁移订阅关系,而不是把同一主题中的所有消息突然换成旧端不认识的结构。
- 冻结
v1,发布v2契约与不可变的模式标识,先验证新消费者。 - 若同一业务事实仍能准确表达为两版,从同一可靠发布记录派生两种表示,分别送入版本通道并跟踪投递进度;不能表达时,不强行下转换。
- 旧消费者继续读取
v1,迁移后的消费者读取v2,逐个切换并比较业务结果。 - 处理旧积压、死信和回放需求,确认没有旧订阅依赖后,再停止旧版发布。

两种表示使用不同事件 ID,并用同一次业务操作的稳定标识关联。某个逻辑消费者在切换边界可能接触两版,必须按业务操作防止重复副作用;不能期待两个不同的事件 ID 自动完成跨版本去重。
退役前验证历史回放和回滚
将各版本样本、模式校验和真实消费者测试纳入持续集成。需要读取全部保留历史时,兼容检查也应覆盖全部相关旧版本;以 Confluent Schema Registry 为例,BACKWARD_TRANSITIVE 比只比较上一版的 BACKWARD 覆盖更广。([Confluent 文档][2])
解码错误、金额差异或重复副作用出现时,应暂停切换并保留原始消息。回滚消费者之前,先确认旧程序能读已经写入的新消息;否则应恢复旧版本通道或采用经过验证的转换方案,不能只回退代码。
停止发布旧版,不等于可以删除旧版读取逻辑。只有旧订阅、积压、死信、历史保留期及回放方案都已有明确处置,旧契约才真正完成退役。