OpenAPI变更拉取门控

问题背景

当团队快速迭代 OpenAPI 规范时，破坏性变更（如字段删除、类型变更）可能悄悄进入主分支，导致服务调用方出现故障。传统代码评审难以快速识别这类结构性变化，尤其当规范文件由多个服务或团队共同维护时，人工对比新旧版本的成本极高。

工作原理

该技能通过调用 oasdiff 工具，将新旧 OpenAPI 规范进行结构化对比，自动识别破坏性变更点。具体流程包括：

• 加载基线版本与目标版本的规范文件；
• 运行 oasdiff 生成差异报告，标注高风险变更（如必填字段新增、接口删除）；
• 将报告输出为可读的 Markdown 或 JSON 格式，支持直接集成到 CI 流水线或代码评审工具中。

例如，当开发团队提交修改了用户信息接口的拉取请求时，技能会对比新旧规范，发现新增了一个必填字段，并在报告中明确标注，触发 CI 拦截或提醒评审人员重点关注。

适用边界

该技能适用于使用 OpenAPI 3.0 及以上版本规范的项目，尤其适合需要严格管控 API 变更的中大型团队。但需注意：

• 需确保 oasdiff 工具在环境中可用，且版本与规范兼容；
• 对于非标准规范（如自定义扩展、混合版本文件），可能需要额外配置或人工校准；
• 技能本身不处理业务逻辑层面的兼容性问题，仅聚焦于规范结构的破坏性变更。