S48：做一次兼容协议变更

内容类型：预习教材（不代表已完成）
日期：2027-01-09
阶段：P2 · AI Systems Engineering 90
总路线：Day 138 / 360
周次：W7 · Protocols & Enterprise Integration
节奏：周六可选探索 / 补学
状态：教材已备；学习未完成
标签：compatibility、schema-evolution、expand-contract、migration、optional

一句话定义

兼容变更不是“schema 工具没有报错”，而是在生产者、消费者和积压消息并存时，通过 expand-and-contract 让语义有序迁移。

学习目标

1. 理解 producer/consumer 独立部署导致的版本组合。
2. 能用 expand→migrate→observe→contract 描述一次安全变化。
3. 区分语法兼容、行为兼容和业务语义兼容。
4. 可选完成一个小型 v1/v2 契约推演，无需真实部署。

核心知识

• 协议演进期间至少存在旧 producer→旧 consumer、旧→新、新→旧、新→新四种组合，还可能有 backlog 中更旧事件。
• Expand 先让消费者接受新旧表示；migrate 逐步升级生产者/数据；observe 检查未知字段、错误和采用；contract 最后移除旧表示。
• 双写可能产生不一致，双读要定义优先级；迁移期不是简单复制字段。
• 默认值若改变业务含义，即使字段可选也可能不兼容。例如缺失 currency 从“拒绝”变成默认 USD，会静默改变结果。
• Feature negotiation 或 capability discovery 可帮助选择版本，但不能替代服务端兼容窗口与明确弃用策略。
• Deprecation 需要 owner、时间线、使用证据和回退方案；只在文档标“deprecated”不会推动迁移。

机制与推导

示例：把 reason: string 演进为 reasonCodes: string[]。

1. 新 consumer 同时读 reasonCodes 与 reason
2. producer 双写一段时间，并记录不一致
3. 观察旧字段消费者是否仍有流量
4. 停写旧字段，但保持读兼容覆盖 backlog
5. 超过约定窗口后才移除旧读取

兼容矩阵要包括数据和行为：旧 consumer 遇到未知 code 是忽略、拒绝还是崩溃？新 consumer 同时收到两字段以谁为准？这些问题不能只靠 JSON Schema diff 回答。

最小练习或观察步骤

1. 从 S44 选择一个字段变化，列四种新旧组合。
2. 写 expand、migrate、observe、contract 四步和各自 owner。
3. 构造一条迁移前 backlog 消息，确认新 consumer 能否读取。
4. 定义两个观测信号：旧字段使用量、解析失败或语义不一致。
5. 写清回退会回退 producer、consumer 还是路由。
6. 周六完全可跳过；不需要建立自动 compatibility gate。

常见误区与边界

• producer 和 consumer 同时大爆炸升级，无法独立回滚。
• 只做双写，不观察字段是否一致和谁仍在读取。
• backlog 保留期长于兼容读取窗口。
• 新默认值静默改变金融金额、时区或权限语义。
• 版本号增加却没有迁移与弃用责任。
• 本日只推演一个变化，不要求掌握所有 schema registry 产品。

系统 / 金融 / Web3 场景连接

金融事件从单一原因演进为多原因时，旧风控 consumer 可能只读取首个值，影响决策解释。Web3 工具增加新链或交易类型时，旧客户端可能错误使用默认 chain；扩展契约必须让未知链显式失败，而非静默发送到错误网络。

自检问题

1. 为什么 schema diff 不能判断所有行为兼容？
2. expand-and-contract 每一步解决什么风险？
3. backlog 如何延长兼容窗口？
4. 双写期间必须观察什么？

专业课程对齐

• 阅读 OpenAPI Specification 的版本、Schema 与兼容表达，聚焦 optional/required、enum 和 deprecated 如何影响客户端。
• 阅读 AsyncAPI 官方文档 中 schema format、message evolution 相关内容，将生产者/消费者独立演进映射到四组合矩阵。
• 阅读 A2A Protocol 官方文档 的 capability discovery 与协议版本信息，思考能力协商能解决什么、不能解决什么。

深入学习提示

用“先升级哪一边”作为阅读主问题。对每个方案写回滚方向和 backlog 影响。若还想深入，比较 tolerant reader 与严格验证的取舍，但无需选绝对答案：边界接口、金额与权限字段可能更需要严格失败。

学后填写区

• 选择的字段变化：
• 四种版本组合：
• Expand-and-contract 路径：
• 观测与回退：
• 未验证部分：