Files

duanshuwen e082bd2d98 feat(api): 实现三端统一的JSON API响应契约

- 新增`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文档，调整文档分类顺序将响应契约置于首位

2026-08-19 22:02:20 +08:00

4.3 KiB

Raw Blame History

三端统一 API 响应契约

本文档是 WonderQ-Admin、WonderQ-Admin-UI、WonderQ-MiniAPP 的统一 JSON 响应规范。适用于 /health、/api/public/** 和 /api/admin/**，新接口必须直接遵守本契约。

基本结构

所有 JSON 响应都必须包含 code、msg 和 data：

{
  "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 同级。

成功响应

查询、更新、排序

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": []
  }
}

创建

创建接口返回 HTTP 201，响应中的 code 也必须为 201：

{
  "code": 201,
  "msg": "success",
  "data": {
    "id": "example-id"
  }
}

删除

删除接口仍保留原有业务结果，只放入 data：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "example-id"
  }
}

失败响应

失败响应的 HTTP 状态码和 code 必须相同，data 必须为 null：

{
  "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 流程。
未包裹的旧响应不再兼容，客户端必须将其识别为协议错误。

联调检查

每次新增或修改接口时，至少检查：

成功查询返回 200，创建返回 201。
code 为数字且等于 HTTP 状态码。
成功 msg 为 success，失败 data 为 null。
列表、详情、删除和排序的原业务字段只出现在 data 内。
400、401、404、409、422、500（适用时）都保持相同包裹结构。

相关领域字段和路径以 public-api.md、admin-api-requirements.md、home-api.md、wanfa-api.md、detail-api.md、concierge-api.md、team-building-api.md 和 wild-archives-api.md 为准。

4.3 KiB Raw Blame History Unescape Escape