e082bd2d98
- 新增`api_response.py`统一响应封装工具类，提供标准成功/错误响应构造方法 - 重构WonderQ-Admin全局异常处理器，将所有异常转换为标准响应格式 - 修改所有公共和管理端接口的返回逻辑，统一使用`code`（与HTTP状态码一致）、`msg`和`data`的三层结构 - 新增`api-response-contract.md`文档，定义完整的三端统一JSON响应规范 - 更新所有领域API文档，明确业务数据需位于`data`字段内，补充响应格式说明 - 为WonderQ-MiniAPP和WonderQ-Admin-UI新增响应解析逻辑和类型定义，自动完成协议校验和错误处理 - 更新所有测试用例，适配新的响应结构确保接口符合契约要求 - 新增`module-config-api.md`模块配置API文档，补充站点模块配置的接口约定 - 更新项目README文档，调整文档分类顺序将响应契约置于首位
117 lines
4.3 KiB
Markdown
117 lines
4.3 KiB
Markdown
# 三端统一 API 响应契约
|
||
|
||
本文档是 `WonderQ-Admin`、`WonderQ-Admin-UI`、`WonderQ-MiniAPP` 的统一 JSON 响应规范。适用于 `/health`、`/api/public/**` 和 `/api/admin/**`，新接口必须直接遵守本契约。
|
||
|
||
## 基本结构
|
||
|
||
所有 JSON 响应都必须包含 `code`、`msg` 和 `data`：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `code` | `number` | 与 HTTP 状态码一致；成功通常为 `200`，创建成功为 `201`。 |
|
||
| `msg` | `string` | 成功固定为 `success`；失败为用户可读的错误信息。 |
|
||
| `data` | `object \| array \| string \| number \| boolean \| null` | 成功时承载原接口业务结果；失败时必须为 `null`。 |
|
||
| `errorCode` | `string`，可选 | 稳定的业务错误码，使用大写蛇形命名。 |
|
||
| `details` | `unknown`，可选 | 面向客户端的结构化错误详情，不得包含 SQL、堆栈、Token 或环境变量。 |
|
||
|
||
`data` 内的业务字段保持各领域文档原有结构不变。也就是说，列表的 `items`、首页的 `experiences`、玩法的 `categories` 等字段都位于响应的 `data` 内，而不是与 `code` 同级。
|
||
|
||
## 成功响应
|
||
|
||
### 查询、更新、排序
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"items": []
|
||
}
|
||
}
|
||
```
|
||
|
||
### 创建
|
||
|
||
创建接口返回 HTTP `201`，响应中的 `code` 也必须为 `201`：
|
||
|
||
```json
|
||
{
|
||
"code": 201,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": "example-id"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 删除
|
||
|
||
删除接口仍保留原有业务结果，只放入 `data`：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": "example-id"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 失败响应
|
||
|
||
失败响应的 HTTP 状态码和 `code` 必须相同，`data` 必须为 `null`：
|
||
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"msg": "未找到对应内容",
|
||
"data": null,
|
||
"errorCode": "RESOURCE_NOT_FOUND",
|
||
"details": {
|
||
"resource": "example"
|
||
}
|
||
}
|
||
```
|
||
|
||
`errorCode` 和 `details` 没有值时可以省略，但不能用空对象替代 `data: null`。常见错误码包括：
|
||
|
||
| HTTP/code | 场景 | 推荐 `errorCode` |
|
||
| --- | --- | --- |
|
||
| `400` | 请求参数、排序列表或字段格式错误 | `VALIDATION_ERROR` 或领域错误码 |
|
||
| `401` | 未登录或 Token 无效 | `AUTH_REQUIRED` 或 `AUTH_INVALID` |
|
||
| `404` | 资源不存在、停用或未配置 | 领域 `*_NOT_FOUND` |
|
||
| `409` | 重复键、删除冲突或并发冲突 | 领域 `*_CONFLICT` |
|
||
| `422` | 仍由业务层使用的不可处理实体 | 领域错误码 |
|
||
| `500` | 未知服务端异常 | `INTERNAL_SERVER_ERROR` |
|
||
|
||
参数校验错误由后端统一转换为 `400 + VALIDATION_ERROR`；如果某个既有业务场景仍返回 `422`，也必须按本契约包装，且 `code` 必须为数字 `422`。
|
||
|
||
## 客户端处理
|
||
|
||
- `WonderQ-Admin` 负责所有路由和全局异常处理，不能把内部异常、SQL、堆栈、Token 或环境配置写入 `msg`、`details` 或响应日志。
|
||
- `WonderQ-Admin-UI` 的公共 `request<T>` 校验包裹结构，成功只返回 `data`；失败使用 `msg` 提示，并保留 `errorCode`、`details`。
|
||
- `WonderQ-MiniAPP` 的公共请求层执行同样校验，页面、Store 和归一化函数继续只接收业务类型，不重复读取 `data`。
|
||
- HTTP 错误是服务端返回了合法错误包；网络错误是请求未获得 HTTP 响应；协议错误是响应缺少必填字段或字段类型不正确，三者应分别进入现有错误、重试和 fallback 流程。
|
||
- 未包裹的旧响应不再兼容，客户端必须将其识别为协议错误。
|
||
|
||
## 联调检查
|
||
|
||
每次新增或修改接口时，至少检查：
|
||
|
||
1. 成功查询返回 `200`，创建返回 `201`。
|
||
2. `code` 为数字且等于 HTTP 状态码。
|
||
3. 成功 `msg` 为 `success`，失败 `data` 为 `null`。
|
||
4. 列表、详情、删除和排序的原业务字段只出现在 `data` 内。
|
||
5. `400`、`401`、`404`、`409`、`422`、`500`（适用时）都保持相同包裹结构。
|
||
|
||
相关领域字段和路径以 [public-api.md](./public-api.md)、[admin-api-requirements.md](./admin-api-requirements.md)、[home-api.md](./home-api.md)、[wanfa-api.md](./wanfa-api.md)、[detail-api.md](./detail-api.md)、[concierge-api.md](./concierge-api.md)、[team-building-api.md](./team-building-api.md) 和 [wild-archives-api.md](./wild-archives-api.md) 为准。
|