cc-api-contract-safety

name	cc-api-contract-safety
description	前后端接口契约安全规范，适用于接口新增或调整、联调、列表分页异常与临时兼容治理；用于避免响应结构漂移被前端兼容长期掩盖。

接口契约安全规范

触发场景

• 新增或调整 HTTP/JSON 接口
• 前后端联调
• 列表页、分页、筛选项、状态枚举或详情页异常
• 前端开始兼容多种 response shape
• 后端某些接口没有走项目统一成功响应 helper

核心原则

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

检查清单

1. 成功响应包装

• 列表接口是否走项目统一成功响应 helper
• 详情接口是否也走同一成功响应格式
• 状态选项、枚举、筛选项接口是否仍在返回裸数组或其他特例结构
• 错误响应是否与项目现有模式一致

2. 列表与分页结构

• 前端当前期望的是数组、分页对象还是统一包裹后的 data
• 后端真实返回是否与该期望一致
• page、pageSize、total、items 或等价字段是否完整且命名一致
• 页码基准是否一致，例如从 0 开始还是从 1 开始

3. 筛选项与枚举来源

• 筛选项接口返回的数据是否来自真实日志或真实状态字段
• “筛选项为空”是否真的是无数据，而不是契约失配
• 枚举值是否与列表数据里的真实值一致
• 前端回退生成选项时，是否已标注为短期兜底而非长期正式来源

4. 字段映射与调用链

• 前端使用的字段名来自真实接口返回，而不是本地类型猜测
• 列表、详情、筛选接口引用的是同一业务字段语义
• 若存在中间转换层，转换前后字段语义是否保持一致

5. 临时兼容治理

• 当前兼容分支是为了解什么具体问题
• 兼容分支的退出条件是什么
• 后端统一后是否有计划删掉双格式兼容
• 输出里是否明确区分“根因修复”和“短期兜底”

6. 验证

• 直接查看真实接口响应或服务端日志，而不是只看前端表现
• 验证列表、详情、筛选项三个入口是否都一致
• 验证空态、非空态和异常态下的契约表现
• 若保留兼容分支，验证其不会掩盖新的契约错误

常见反模式

• 看到页面能打开，就接受前端长期兼容数组和分页对象两种格式
• 只修列表接口，不修详情接口和状态选项接口
• 看到筛选项为空，就先从当前页数据回填，但不追查后端契约
• 在没有证据的情况下根据类型定义猜测字段名或返回结构

输出要求

• 明确区分症状、当前契约、期望契约、根因修复、临时兼容和退出条件
• 若证据来自日志、抓包或直接接口返回，要明确写出依据
• 若仍保留兼容逻辑，要说明为什么这次不立即删除