WonderQ-Project/docs/api-response-contract.md

三端统一 API 响应契约

本文档是 WonderQ-Admin、WonderQ-Admin-UI-Vue、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 同级。

ID 规范

• 所有持久化资源的 id 都是服务端生成的稳定不透明字符串，当前实现统一使用 UUID v4 格式。
• ID 只在记录创建时生成，后续列表、详情、排序、编辑和删除响应必须保持不变；禁止在序列化或每次请求时重新随机生成。
• 玩法路线详情的 DetailRecord.key 等于对应的 WanfaRoute.id，详情、列表、排序和跳转必须复用同一个路线 ID。
• 本地 fallback/mock 数据可以继续使用便于阅读的语义 ID，但这些 ID 不代表服务端正式 ID；接口成功后应以 API 返回的 UUID 为准。

成功响应

查询、更新、排序

{
  "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-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、admin-api-requirements.md、module-config-api.md、wanfa-api.md、detail-api.md 和 concierge-api.md 为准。