K12Study/.agents/skills/k12-api-response-standard/SKILL.md

name, description

name	description
k12-api-response-standard	当任务涉及前后端接口联调、请求封装、异常处理时使用，统一 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 以支持链路追踪。