22 lines
1.0 KiB
Markdown
22 lines
1.0 KiB
Markdown
|
---
|
||
|
|
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` 以支持链路追踪。
|