e8eb8614f0
删除home-api.md、team-building-api.md等废弃文档 统一替换所有文档中的`WonderQ-Admin-UI`为`WonderQ-Admin-UI-Vue` 更新README.md与联调文档的内容与路径 修正各API文档的过时描述，移除废弃的迁移说明与本地mock依赖 整理docs/README.md的文档索引，优化阅读路径
124 lines
4.8 KiB
Markdown
124 lines
4.8 KiB
Markdown
# 三端统一 API 响应契约
|
||
|
||
本文档是 `WonderQ-Admin`、`WonderQ-Admin-UI-Vue`、`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` 同级。
|
||
|
||
## ID 规范
|
||
|
||
- 所有持久化资源的 `id` 都是服务端生成的稳定不透明字符串，当前实现统一使用 UUID v4 格式。
|
||
- ID 只在记录创建时生成，后续列表、详情、排序、编辑和删除响应必须保持不变；禁止在序列化或每次请求时重新随机生成。
|
||
- 玩法路线详情的 `DetailRecord.key` 等于对应的 `WanfaRoute.id`，详情、列表、排序和跳转必须复用同一个路线 ID。
|
||
- 本地 fallback/mock 数据可以继续使用便于阅读的语义 ID，但这些 ID 不代表服务端正式 ID；接口成功后应以 API 返回的 UUID 为准。
|
||
|
||
## 成功响应
|
||
|
||
### 查询、更新、排序
|
||
|
||
```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-Vue` 的公共 `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)、[module-config-api.md](./module-config-api.md)、[wanfa-api.md](./wanfa-api.md)、[detail-api.md](./detail-api.md) 和 [concierge-api.md](./concierge-api.md) 为准。
|