---
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. 验证

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

## 常见反模式

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

## 输出要求

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