从消费者而非版本号定义兼容性
变更是否破坏契约取决于现有消费者实际发送和读取的内容，而不仅是新 Schema 是否有效。首先记录受支持客户端、历史持久化记录和回滚窗口。
新增必填字段、类型收窄或删除枚举值常会影响旧生产者；即使新增可选字段，也可能破坏拒绝额外属性的消费者。
- 盘点生产者与消费者。
- 为兼容窗口写明日期。
- 不要把决定交给版本标签。
比较范围一致的文档
确认新旧 JSON Schema 描述同一个根对象。OpenAPI 应比较等价环境生成的文档，避免把线上契约与不完整本地文件混在一起。
ByteQuant 检查直接属性、必填项、类型、枚举、路径、方法、参数必填和删除的响应；外部 $ref 与条件 Schema 需另行完整解析。
用匿名样例复现每个候选项
为每项发现保存最小化且不含个人数据的旧请求、新请求、旧响应和新响应。除正常路径外，还要测试缺失字段、未知枚举、空数组和大 payload。
结构差异不能证明行为；默认值、错误码、排序、分页和授权必须由契约测试观察。
把破坏性变更转化为迁移计划
必须变更时，先发布允许新字段为可选项的过渡版本，迁移生产者并测量采用率，再启用强制要求。删除路径或响应时提供并行期、弃用日期和机器可读警告。
发布说明应写明操作、旧行为、新行为、迁移示例、截止日期和回滚路径，而不只是‘Schema 已更新’。
用证据关闭发布门禁
将本地预检、匿名样例、消费者测试和预发布环境观察合并在同一记录中，并明确批准者与接受的风险；自动工具不是决策者。
发布后监控错误率、4xx 分布和旧客户端使用情况；不得把敏感 payload 或访问凭据写入报告、CI 日志或共享 URL。
- 对应发布前后指标。
- 预先定义回滚标准。
- 报告只使用合成数据。
本指南配套工具
下列工具为同一决策提供不同证据。请结合真实环境、合同或权威来源分别核验每项输出；先用合成数据复现流程，再记录人工验收标准与停止条件。
- JSON Schema 向后兼容检查器
- OpenAPI 破坏性变更检查器
- 结构化 JSON 对比
- OpenAPI 端点清单
把指南转化为安全试用流程
使用真实资料前，请先在JSON Schema 向后兼容检查器中用合成数据试做《在不破坏消费者的前提下演进 JSON Schema 与 OpenAPI 契约》的步骤。勾选状态只保留在当前标签页。
把指南转化为可重复的检查流程
请使用这套包含 4 个工具的检查计划来落实《在不破坏消费者的前提下演进 JSON Schema 与 OpenAPI 契约》。目标：实用指南：在更安全的契约发布流程中审查必填字段、类型、枚举、API 路径、参数和响应。 请先用安全示例代替真实数据，并记录每一步的预期结果与验收决定。
JSON Schema 向后兼容检查器
- 准备
- 先粘贴旧 Schema，再粘贴新 Schema。
- 执行
- 运行结构比较。
- 验收检查
- 使用真实样例和消费者测试核验每项发现。
- 预期输出
- 解析后的结构、字段指标和明确的语法问题. 查找两个 JSON Schema 版本之间可能破坏消费者的结构变化。
OpenAPI 破坏性变更检查器
- 准备
- 添加旧版和新版 OpenAPI JSON。
- 执行
- 生成破坏性变更候选项。
- 验收检查
- 通过服务器行为、请求样例和 SDK 测试确认。
- 预期输出
- 规范化的 Web 配置、组件清单和可执行的复核提示. 报告两个 OpenAPI JSON 文档中被删除的路径、方法、参数和响应。
结构化 JSON 对比
- 准备
- 语法有效、并包含工具所述对象、数组或字段的 JSON处理敏感真实数据前，请先用合成示例确认格式。
- 执行
- 运行设备端处理。解析采用确定性规则，并保留字段与类型边界。
- 验收检查
- 验收检查：将字段名、值类型、转义以及空值或 null 与源数据逐项比较请在目标系统核验架构、编码和数据丢失假设。
- 预期输出
- 解析后的结构、字段指标和明确的语法问题. 识别新增、删除和变更的 JSON 路径。
OpenAPI 端点清单
- 准备
- 工具要求的 URL、HTTP 标头、cURL 命令、API 定义或 Web 配置处理敏感真实数据前，请先用合成示例确认格式。
- 执行
- 运行设备端处理。输入在不发起网络请求的情况下解析，并分别显示组成部分和高风险假设。
- 验收检查
- 验收检查：在获授权的测试环境中，与现行标准和真实服务器行为进行比较请在目标系统核验架构、编码和数据丢失假设。
- 预期输出
- 规范化的 Web 配置、组件清单和可执行的复核提示. 从 OpenAPI JSON 提取方法、路径、标签与安全摘要。
JSON Schema 向后兼容检查器适用以下边界：请在目标系统核验架构、编码和数据丢失假设。 如果未满足该条件，请勿把输出传递到工作流的下一步。
落实《在不破坏消费者的前提下演进 JSON Schema 与 OpenAPI 契约》时，请记录工具名称、所选设置、浏览器版本，以及“API 版本审查 — 查找两个 JSON Schema 版本之间可能破坏消费者的结构变化。”的接受或拒绝理由，而不是敏感内容。这样既能重复检查，也不会复制真实数据。