API 版本升级与破坏性变更审查

目标与适用范围

对比 API 版本、规划迁移并在发布前验收兼容性。工具不替代真实发布和运行监控。
本指南将当前任务范围转化为可复核的交付结果。请保留源文件、中间产物和关键判断，让后续协作者能够理解检查了什么以及为什么这样处理。

准备证据并作出选择

• 准备带版本的旧版和新版 API 规范及代表性样例。

• 明确兼容性规则、受影响调用方、验收门槛和授权测试环境。

• 决策点: 根据输入选择哪个对比工具？. 两份 OpenAPI 3.x schema 且需要迁移策略时选择 api-breaking-changes-detector-migration-planner。需要对 OpenAPI 或 GraphQL 做影响导向 diff 时选择 openapi-diff-breach-detector。

按步骤完成工作流

1. 对比版本

校验并对比新旧 API 规范，分类被删除或收紧的契约元素。 使用 openapi-validator, api-breaking-changes-detector-migration-planner, openapi-diff-breach-detector.

2. 检查兼容性

校验已捕获响应、对比载荷并生成边界或变异用例；只有在授权测试后端上发送请求。 使用 api-response-contract-validator, api-response-diff-semantic-analyzer, api-contract-stress-tester, api-contract-mutation-tester.

3. 验收迁移计划

记录调用方动作、SemVer 与 changelog 证据、未解决阻断或豁免，并单独记录真实发布和运行监控负责人。 使用 semver-validator, changelog-extractor, package-json-dependency-auditor.

交付前验收结果

• 每个破坏性发现都有位置、调用方影响、迁移或兼容动作和负责人。
• 代表性响应、边界和变异检查通过，或明确记录阻断或豁免；真实发布和监控负责人单独记录。

常见问题

• 这些工具会发布或监控生产环境吗？ 不会。它们分析规范、保存的载荷、生成的用例和可选的授权测试请求。真实发布和运行监控必须另行执行。
• 什么是破坏性变更？ 删除操作、响应字段或状态码，收紧输入，改变字段类型，或把可选输入改为必填，都可能破坏已有调用方。
• 迁移计划必须包含什么？ 每个发现都需要记录受影响调用方、动作、负责人、截止时间、测试证据和回滚假设。