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

事件版本变化怎么保持兼容

事件版本变化怎么保持兼容

订单事件只是新增一个渠道字段,旧消费者却开始报错;金额字段类型没变,消费者又可能算错一百倍。本篇区分结构兼容与业务语义兼容,用新旧读取器交叉测试,并给出多版本并存时的发布与退役路径。

学习目标

  • 判断字段新增、删除、类型和语义变化的兼容风险。
  • 用新旧消费者交叉读取样本,验证默认行为和业务结果。
  • 设计兼容升级与破坏性升级的共存、回滚和退役条件。

先说明谁要读取谁的数据

“兼容”必须带方向,不能只说新版本能运行。以下方向采用 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,新载荷新增它,金额始终以分计量。

python
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()

预期输出:

text
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])

破坏性变化需要旧消费者继续运行时,本篇采用隔离版本通道的迁移方案。先保持旧契约不动,再迁移订阅关系,而不是把同一主题中的所有消息突然换成旧端不认识的结构。

  1. 冻结 v1,发布 v2 契约与不可变的模式标识,先验证新消费者。
  2. 若同一业务事实仍能准确表达为两版,从同一可靠发布记录派生两种表示,分别送入版本通道并跟踪投递进度;不能表达时,不强行下转换。
  3. 旧消费者继续读取 v1,迁移后的消费者读取 v2,逐个切换并比较业务结果。
  4. 处理旧积压、死信和回放需求,确认没有旧订阅依赖后,再停止旧版发布。

事件破坏性升级的双版本共存与退役时序

两种表示使用不同事件 ID,并用同一次业务操作的稳定标识关联。某个逻辑消费者在切换边界可能接触两版,必须按业务操作防止重复副作用;不能期待两个不同的事件 ID 自动完成跨版本去重。

退役前验证历史回放和回滚

将各版本样本、模式校验和真实消费者测试纳入持续集成。需要读取全部保留历史时,兼容检查也应覆盖全部相关旧版本;以 Confluent Schema Registry 为例,BACKWARD_TRANSITIVE 比只比较上一版的 BACKWARD 覆盖更广。([Confluent 文档][2])

解码错误、金额差异或重复副作用出现时,应暂停切换并保留原始消息。回滚消费者之前,先确认旧程序能读已经写入的新消息;否则应恢复旧版本通道或采用经过验证的转换方案,不能只回退代码。

停止发布旧版,不等于可以删除旧版读取逻辑。只有旧订阅、积压、死信、历史保留期及回放方案都已有明确处置,旧契约才真正完成退役。

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

目录与阅读设置

阅读设置

17

记录一个想法

事件版本变化怎么保持兼容

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

登录哪都通