166 lines
4.1 KiB
Markdown
166 lines
4.1 KiB
Markdown
# API响应规范
|
||
|
||
## 概述
|
||
|
||
项目统一使用 `R` 模块封装 API 响应，所有接口返回一致的 JSON 格式，便于前端统一处理。
|
||
|
||
:::tip 核心原则
|
||
- 所有接口必须通过 `R.ok()` 或 `R.failed()` 返回，禁止直接返回 dict
|
||
- 成功响应 `code=0`，失败响应 `code=1`
|
||
- 响应体始终包含 `code`、`data`、`msg`、`ok` 四个字段
|
||
:::
|
||
|
||
## 响应格式
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": { ... },
|
||
"msg": "操作成功",
|
||
"ok": true
|
||
}
|
||
```
|
||
|
||
### 失败响应
|
||
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"data": null,
|
||
"msg": "错误信息",
|
||
"ok": false
|
||
}
|
||
```
|
||
|
||
### 分页响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": [...],
|
||
"count": 100,
|
||
"msg": "操作成功",
|
||
"ok": true
|
||
}
|
||
```
|
||
|
||
## R 模块使用方法
|
||
|
||
### R.ok() 成功响应
|
||
|
||
```python
|
||
from src.core import response as R
|
||
|
||
# 基础成功响应
|
||
return R.ok()
|
||
|
||
# 带数据的成功响应
|
||
return R.ok(data=user_info)
|
||
|
||
# 自定义提示消息
|
||
return R.ok(msg='添加成功')
|
||
|
||
# 附加额外字段（如 count）
|
||
return R.ok(data=result, count=total)
|
||
```
|
||
|
||
### R.failed() 失败响应
|
||
|
||
```python
|
||
# 基础失败响应
|
||
return R.failed()
|
||
|
||
# 自定义错误消息
|
||
return R.failed('岗位名称不能重复')
|
||
|
||
# 自定义错误码和消息
|
||
return R.failed(msg='未授权', code=401)
|
||
```
|
||
|
||
### R.page() 分页响应
|
||
|
||
```python
|
||
# 分页响应（由 BaseService.get_page 自动调用）
|
||
return R.page(data=records, total=100, current=1, size=10)
|
||
```
|
||
|
||
## 字段定义
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `code` | int | 状态码：0=成功，1=失败，401=未认证，403=无权限 |
|
||
| `data` | any/null | 响应数据，失败时为 null |
|
||
| `msg` | string | 提示消息 |
|
||
| `ok` | boolean | 是否成功 |
|
||
|
||
## 状态码规范
|
||
|
||
| 状态码 | 含义 | 使用场景 |
|
||
|--------|------|---------|
|
||
| 0 | 成功 | 操作成功 |
|
||
| 1 | 失败 | 业务逻辑失败（如参数校验、唯一性冲突） |
|
||
| 401 | 未认证 | token 缺失或过期 |
|
||
| 403 | 无权限 | 用户无对应权限 |
|
||
| 404 | 资源不存在 | 请求的资源未找到 |
|
||
| 422 | 验证错误 | WTForms 参数校验失败 |
|
||
| 500 | 服务器错误 | 未捕获的异常 |
|
||
|
||
:::tip 错误码与 HTTP 状态码
|
||
业务错误码（code 字段）始终为 0 或 1，HTTP 状态码始终为 200。401/403/422 等仅在全局异常处理器中使用，常规业务错误统一返回 `code=1`。
|
||
:::
|
||
|
||
## 在 Router 中使用
|
||
|
||
```python
|
||
from src.core import response as R
|
||
|
||
# 查询详情：service 返回 dict，router 包 R.ok
|
||
@position_blue.route('/detail/<int:id>', methods=['GET'])
|
||
@check_permission('sys:position:detail')
|
||
def detail(id):
|
||
from src.modules.system.position.service import get_position_detail
|
||
result = get_position_detail(id)
|
||
return R.ok(data=result)
|
||
|
||
# 添加记录：service 直接返回 R 对象
|
||
@position_blue.route('/add', methods=['POST'])
|
||
@check_permission('sys:position:add')
|
||
def add():
|
||
from src.modules.system.position.service import add_position
|
||
from src.modules.system.position.schema import PositionForm
|
||
data = parse_request_body(request, PositionForm)
|
||
return add_position(data)
|
||
|
||
# 删除记录：service 直接返回 R 对象
|
||
@position_blue.route('/delete/<int:id>', methods=['DELETE'])
|
||
@check_permission('sys:position:delete')
|
||
def delete(id):
|
||
from src.modules.system.position.service import delete_position
|
||
return delete_position(id)
|
||
```
|
||
|
||
:::tip 响应封装层级
|
||
- **分页/列表查询**：service 返回 `R.ok()` 或 `R.page()`
|
||
- **详情查询**：service 返回 dict/None，router 包 `R.ok(data=result)`
|
||
- **写操作（增/删/改/状态）**：service 直接返回 `R` 对象
|
||
:::
|
||
|
||
## WTForms 验证错误响应
|
||
|
||
WTForms 验证错误由 `parse_request_body` 函数自动转换为标准格式：
|
||
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"data": null,
|
||
"msg": "岗位名称不能为空",
|
||
"ok": false
|
||
}
|
||
```
|
||
|
||
## 总结
|
||
|
||
API 响应规范通过 `R` 模块统一封装：`R.ok()` 返回成功、`R.failed()` 返回失败、`R.page()` 返回分页。所有响应保持 `{code, data, msg, ok}` 四字段结构，HTTP 状态码始终为 200。业务层错误统一用 `code=1`，前端只需判断 `ok` 字段即可。
|