如何在生产部署前检测现有Public API的非新增类变更

以下方案均默认排除新增API的检测逻辑，仅校验已对外提供服务的存量公开API：

1. 基于API契约快照的比对校验 #

• 首次操作时，基于当前生产环境运行的代码生成稳定API契约快照，快照需包含所有存量公开API的路由地址、请求方法、入参名称/类型/必填属性、出参结构、常规响应状态码信息，不包含内部非公开接口
• 后续每次待发布版本的CI构建阶段，自动生成当前分支的API契约快照，调用契约比对工具完成两份快照的差异化校验：
  • 仅比对两张快照中同时存在的API项，新增API自动跳过检测
  • 检测触发条件：Action对应路由变更、请求方法调整、必填参数删除/改名/类型修改、响应必填字段删除/类型变更
  • 只要命中任意破坏性变更，直接阻断构建流程，返回具体变更明细通知开发人员调整
• 不同技术栈可直接使用现有工具生成OpenAPI格式的快照文件：.NET生态用Swashbuckle，Java生态用SpringDoc，Node.js生态用swagger-jsdoc，快照文件跟随主分支代码存储即可，仅在API正式官宣调整时允许更新

2. 基于反射的API签名单元测试卡点 #

• 编写API签名校验单元测试，通过反射读取所有对外公开Controller的Action方法名、参数列表、路由注解信息，和预设的存量API签名白名单做校验
• 仅当存量公开API的签名和白名单完全匹配时，单元测试才能通过，否则CI流程直接中断，开发人员在代码提交阶段就能发现问题，不需要等到部署环节
• 签名白名单的修改权限做管控，普通开发提交代码不允许修改，仅当API正式迭代调整时走审批流程后更新

3. CI/CD流程集成落地 #

• 把上述两种检测逻辑全部集成到CI流水线的代码合并前置校验阶段，只要检测到变更直接阻断代码合并
• 新增API首次上线时不会纳入检测范围，上线后自动更新到稳定契约快照/签名白名单中，后续迭代将纳入变更检测
• 如果确实需要对存量公开API做破坏性变更，走单独审批流程后手动跳过对应检测项，同步通知所有调用方提前适配后再部署

内容的提问来源于stack exchange，提问作者Salamat Turdukhodzhaev