Files

duanshuwen d3a246a873 docs: 统一业务资源ID为服务端生成的稳定UUID

更新所有业务API文档，明确持久化资源的正式ID必须为服务端生成的稳定UUID，本地调试或接口失败时可使用语义ID作为fallback。新增数据库迁移脚本0022_opaque_ids，用于将历史语义ID转换为稳定UUID，并同步外键关联、详情记录的key字段以及审计日志的实体ID引用。新增该迁移的单元测试用例，验证ID替换与关联数据同步的逻辑正确性。调整MiniAPP前端代码，优化导航工具函数的格式，移除废弃函数并修改首页跳转逻辑，使用接口返回的UUID作为详情跳转参数。

2026-08-19 22:28:13 +08:00

5.0 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 同级。

ID 规范

所有持久化资源的 id 都是服务端生成的稳定不透明字符串，当前实现统一使用 UUID v4 格式。
ID 只在记录创建时生成，后续列表、详情、排序、编辑和删除响应必须保持不变；禁止在序列化或每次请求时重新随机生成。
玩法路线详情的 DetailRecord.key 等于对应的 WanfaRoute.id，因此路线 ID 迁移后详情 key 必须同步更新。
本地 fallback/mock 数据可以继续使用便于阅读的语义 ID，但这些 ID 不代表服务端正式 ID；接口成功后应以 API 返回的 UUID 为准。
0022_opaque_ids 迁移只转换历史非 UUID ID，并同步外键、详情 key 和审计实体引用；新建记录继续由 ORM 默认生成 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 的公共 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 为准。

5.0 KiB Raw Blame History Unescape Escape