SuperAPI AI 工具集

cc-api-contract-safety

编程与开发

查看项目

更新于 10-15 21:11

技能介绍

用途:这是一套前后端接口契约安全规范,适用于新增或调整 HTTP/JSON 接口、前后端联调,以及列表页、分页、筛选项、状态枚举或详情页出现异常时排查;也用于治理前端已开始兼容多种 response shape 的情况。

核心原则:先看真实接口输入输出再下结论,不根据前端类型或旧记忆推测;能修后端契约根因时优先统一后端,前端兼容只作短期过渡;列表、详情、选项或枚举接口应遵守同一套成功响应格式;分页结构必须明确约定,不长期混用数组和分页对象;临时兼容可保留,但必须写清退出条件和移除时机。

检查清单覆盖六方面:成功响应包装(列表、详情、状态选项与枚举、筛选项是否走统一 helper,错误响应是否一致);列表与分页结构(前端期望与后端真实返回是否一致,page、pageSize、total、items 等字段是否完整且命名一致,页码基准是否统一);筛选项与枚举来源(是否来自真实日志或状态字段,枚举值是否与列表真实值一致,前端回退生成选项是否标注为短期兜底);字段映射与调用链(字段名是否来自真实返回,列表、详情、筛选是否同一业务语义,中间转换层前后语义是否一致);临时兼容治理(兼容分支解决什么问题、退出条件、后端统一后是否删除双格式兼容、输出是否区分根因修复与短期兜底);验证(直接查看真实接口响应或服务端日志,验证列表、详情、筛选项三个入口及空态、非空态、异常态,确认兼容分支不掩盖新契约错误)。

常见反模式:页面能打开就接受前端长期兼容数组和分页对象两种格式;只修列表接口不修详情和状态选项接口;筛选项为空就从当前页数据回填而不追查后端契约;无证据时按类型定义猜测字段名或返回结构。

输出要求:明确区分症状、当前契约、期望契约、根因修复、临时兼容和退出条件;证据来自日志、抓包或直接接口返回时写明依据;保留兼容逻辑时说明为何本次不立即删除。