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文档,调整文档分类顺序将响应契约置于首位
This commit is contained in:
@@ -10,13 +10,16 @@
|
||||
|
||||
首页体验、团队共创和极境视界内容的字段、图片、排序与商品领域隔离约束见 [home-api.md](./home-api.md)。该文档是本主契约的首页内容补充,适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。
|
||||
|
||||
所有 Admin JSON 接口遵循 [三端统一 API 响应契约](./api-response-contract.md)。
|
||||
|
||||
## 通用约定
|
||||
|
||||
- API 前缀:`/api/admin`。
|
||||
- 除登录接口外均需 `Authorization: Bearer <admin-jwt>`。
|
||||
- JSON 请求统一使用 camelCase 字段。
|
||||
- 变更接口写入审计日志后再提交事务。
|
||||
- 失败响应统一包含 `message`、`code` 和可选 `details`。
|
||||
- 成功业务结果统一放在 `data`;创建成功为 HTTP/code `201`。
|
||||
- 失败统一返回数字 `code`、用户可读 `msg`、`data: null`,业务错误码放在可选的 `errorCode`。
|
||||
|
||||
## 接口清单
|
||||
|
||||
@@ -74,7 +77,7 @@ type SiteModule =
|
||||
{ "email": "admin@example.test", "password": "<password>" }
|
||||
```
|
||||
|
||||
成功响应包含 `token` 和 `{ id, email, name, role }`。
|
||||
成功响应包裹为 `data: { token, user: { id, email, name, role } }`;具体字段结构保持现有登录接口约定。
|
||||
|
||||
## 兼容边界
|
||||
|
||||
|
||||
Reference in New Issue
Block a user