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:
@@ -6,6 +6,7 @@
|
||||
|
||||
- API 前缀:`/api/public`。
|
||||
- 响应使用 JSON;时间使用 ISO 8601 字符串。
|
||||
- 所有 `/health` 和 `/api/public/**` JSON 响应遵循 [三端统一 API 响应契约](./api-response-contract.md),成功业务对象位于 `data`,失败时 `data` 为 `null`。
|
||||
- H5 本地开发通过 `/api` 代理访问后端。
|
||||
- 内容接口失败时,MiniAPP 使用 `src/content.ts` 的本地兜底内容。
|
||||
|
||||
@@ -137,7 +138,7 @@ type PublicConciergeResponse = {
|
||||
}
|
||||
```
|
||||
|
||||
无可用顾问时返回 `{ "advisors": [] }`。MiniAPP 应处理 loading、错误、重试和空态,不能依赖固定顾问姓名或本地模拟数组。
|
||||
无可用顾问时返回 `data: { "advisors": [] }`。MiniAPP 应处理 loading、错误、重试和空态,不能依赖固定顾问姓名或本地模拟数组。
|
||||
|
||||
## 首页内容
|
||||
|
||||
@@ -265,8 +266,12 @@ type DemandForm = {
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "<customer-jwt>",
|
||||
"customer": { "id": "customer-id", "phoneMasked": "138****0000" }
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"token": "<customer-jwt>",
|
||||
"customer": { "id": "customer-id", "phoneMasked": "138****0000" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -277,5 +282,9 @@ type DemandForm = {
|
||||
成功响应:
|
||||
|
||||
```json
|
||||
{ "id": "customer-id", "phoneMasked": "138****0000" }
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"data": { "id": "customer-id", "phoneMasked": "138****0000" }
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user