---
name: k12-api-response-standard
description: 当任务涉及前后端接口联调、请求封装、异常处理时使用，统一 code/message/data/traceId 响应体契约
---
# K12 统一响应体技能
## 何时使用
- 新增或改造后端 API
- 改动前端/小程序请求层
- 修复“后端已报错但前端当成功处理”的联调问题
## 统一契约
- 响应体结构固定为：`code/message/data/traceId`
- 成功条件：`code === 0`
- 业务失败：`code !== 0`，前端应抛错并使用 `message` 透出
## 执行步骤
1. 后端控制器与异常处理统一返回 `ApiResponse`。
2. 前端与小程序请求封装统一校验 `code` 字段，不仅依赖 HTTP 状态码。
3. 新接口落地时同步检查类型声明与调用方数据解包方式，避免重复定义结构。
4. 同步更新 `docs/architecture/api-design.md` 中响应体约定，保持文档与代码一致。
## 约束
- 不引入破坏性字段重命名（如把 `message` 改为 `msg`）。
- 保留 `traceId` 以支持链路追踪。