用 oasdiff 在发布前拦截破坏性 API 变更

在 CI 里用 oasdiff 对比两版 OpenAPI 文档，删除字段或收窄类型即失败，并输出可读变更日志供评审。

目标

OpenAPI 文档是你对所有看不见的客户端的承诺。重构改掉响应字段名时，服务端自洽所以测试全绿，破坏只出现在别人的构建里。把已发布 spec 与新构建生成的 spec 做对比，让承诺变得可执行：删除与收窄类型直接让流水线失败，变更日志输出把不可见的 API 改动变成可评审的工件。

步骤要点

在 CI 中下载已发布的 openapi-v3.2.json 作为基线，并由当前构建生成候选 spec。
本地先跑 oasdiff breaking released.json openapi.json，确认能精确列出“response 200 字段 order.items 被删除”这类位置明确的差异。
使用 –fail-on ERR：错误级差异非零退出、警告通过，这是合并流水线合适的默认门禁强度。
在 CI 里用 redocly/oasdiff Docker 镜像执行同一命令，PR 因破坏性变更清单而失败，而不是静默上线。
同时产出 oasdiff changelog 的 api-changelog.md 构件，让评审者有意识地批准每一次 API 变更。

排错提示

字段重排产生噪声是因为 JSON 键序无语义，应保证两份 spec 由同版本工具链生成或先按键排序；确实要做的破坏性变更不要放宽门禁，而应开新主版本并建立新基线；本地与 CI 生成的 spec 有差异时，改为在 CI 受控任务内生成 spec，对比“代码对代码”而非手改文件。

适用边界

工具比较的是文档而不是行为，spec 完全一致的语义变化（如新增校验）仍可能破坏客户端；未写进文档的端点对 diff 不可见，门禁只保护 spec 描述到的部分。

代码示例

oasdiff breaking released.json openapi.json --fail-on ERR

# Also produce a reviewer-facing changelog
oasdiff changelog released.json openapi.json > api-changelog.md