GeoXMind

兼容演进需要把生产者与消费者分开升级

说明 API、事件和数据结构如何通过宽容读取、明确版本和弃用窗口在独立发布中演进。

兼容演进需要把生产者与消费者分开升级

分布式系统中的服务、客户端和数据不会在同一时刻升级。新生产者可能面对旧消费者，新客户端也可能访问旧服务。兼容演进的目标是在这段版本重叠期内保持可理解行为，并让弃用有可观测、可回滚的路径。

向后与向前兼容方向不同

向后兼容通常指新实现仍能处理旧输入或旧客户端；向前兼容指旧实现面对新数据时仍能安全工作。事件系统还要区分新消费者读旧事件与旧消费者读新事件。

“兼容”必须说明方向、版本组合和行为。只说 schema compatible 会掩盖字段语义、默认值和错误处理差异。

线格式能解析不等于业务兼容。字段从“可选备注”变成“审核结论”，类型不变但语义已经改变。

新增字段也可能破坏消费者

宽容读取的消费者忽略未知字段，新增可选字段通常较安全。但严格反序列化、签名计算、缓存键和 UI 枚举可能拒绝未知内容。

新增必填字段会让旧生产者无法创建有效对象。常见做法是先加可选字段和服务端默认，升级生产者填值，再在确认覆盖后收紧约束。

默认值必须具有业务意义。用零或空串让校验通过，可能把“未知”误成真实值。应区分缺失、未知和明确为空。

枚举新增值对旧客户端尤其危险。消费者应有 unknown 分支，而不是把未识别值映射到现有类别。

删除和重命名需要双轨期

直接删除字段会破坏仍在读取的消费者。安全流程通常先停止新代码依赖，标记弃用，监控使用，经过窗口后再移除。

重命名实质是新增新字段并迁移。生产者可以短期双写，消费者优先读新字段并回退旧字段。双写期间要定义冲突时以谁为准。

长期双写会形成永久复杂度，必须有结束条件。迁移看板要显示旧字段读取量和仍未升级的调用方。

数据库列迁移同样适用扩展—迁移—收缩。先添加结构，再回填和切换读写，最后删除旧结构；每步都应可独立发布。

HTTP 兼容还包含状态与缓存

HTTP API 的方法、状态码、头和缓存语义都是契约。把原来返回 404 改成空 200，客户端重试和监控行为可能改变。

分页默认大小、排序稳定性和时间格式变化也会造成回归。响应多一个字段通常比改字段含义安全，但负载大小和缓存 ETag 仍可能变化。

版本可放在路径、媒体类型或协议协商中。版本号不能替代迁移计划；维护多个永久版本会扩大测试与安全成本。

事件必须保留历史可读性

消息日志可能保留数月，消费者重放时会遇到多个 schema 版本。事件应携带版本或可识别结构，转换逻辑要覆盖历史。

事件表示已经发生的事实，不应原地修改历史语义。发现错误可发布更正事件，并让投影明确处理。

生产者与消费者契约测试可以提前发现格式破坏，但测试样例要包含真实旧版本和边界值。只测试最新版双方无法证明滚动升级安全。

语义变更需要新的概念

单位、计算方式、权限和时间含义变化时，沿用旧字段名最危险。即使能够转换，也应明确新概念、版本和生效时间。

例如金额从含税改为未税，增加文档说明不能保护旧消费者。应新增字段或新事件，让两种语义在迁移期并存。

错误修复也可能改变依赖旧错误的客户端。需要评估影响、提供开关或版本，而不是把所有修复都视为天然兼容。

弃用必须由观测证据驱动

服务端应记录旧版本、旧字段或旧端点的调用量，并能定位所有者。没有观测就无法知道何时可以安全删除。

弃用通知应包含替代方案、截止时间、测试环境和回退方式。内部调用方也需要同样纪律，不能依赖口头通知。

截止后先拒绝测试或低风险环境，再逐步扩大。删除前保留最后快照和回滚发布物。

矩阵测试覆盖混合版本

测试不仅是新对新，还包括新服务配旧客户端、旧服务配新客户端，以及滚动期间的数据交叉。数据库迁移要验证旧应用在新 schema 上仍能运行。

混沌和回滚演练应模拟新版本发布一半后撤回。若新写入了旧代码无法读取的数据，二进制回滚并不安全。

重试与幂等语义也属于兼容契约

客户端常在超时后重试，而超时不能证明服务端没有执行。若新版本改变幂等键范围、去重期限或错误码，旧客户端可能重复创建资源。接口演进应记录请求标识的生成规则、有效期和冲突响应，并在网关与服务之间保持一致。

批处理与消息消费者还要兼容重复、乱序和延迟到达。新增字段若改变去重键或聚合窗口，历史事件重放可能得到不同结果。迁移测试要包含失败后重试、跨版本重复消息和旧数据回放，不能只验证一次成功调用。

契约目录连接设计与运行证据

组织应维护端点、事件、所有者、版本、弃用时间和已知消费者的目录。目录不能只靠人工登记，发布流水线可生成结构差异并关联契约测试，运行观测再补充真实使用情况。结构兼容、行为兼容和业务语义兼容应分别判断，避免用 schema 检查通过代替完整评审。

兼容演进是一种时间维度上的架构约束。通过扩展—迁移—收缩、明确语义和使用观测，生产者与消费者才能独立升级，而不会把一次普通发布变成全系统同步停机。

资料依据