API响应规范

概述

项目统一使用 R 模块封装 API 响应，所有接口返回一致的 JSON 格式，便于前端统一处理。

核心原则

• 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict
• 成功响应 code=0，失败响应 code=1
• 响应体始终包含 code、data、msg、ok 四个字段

响应格式

成功响应

{
    "code": 0,
    "data": { ... },
    "msg": "操作成功",
    "ok": true
}

失败响应

{
    "code": 1,
    "data": null,
    "msg": "错误信息",
    "ok": false
}

分页响应

{
    "code": 0,
    "data": [...],
    "count": 100,
    "msg": "操作成功",
    "ok": true
}

R 模块使用方法

R.ok() 成功响应

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() 失败响应

# 基础失败响应
return R.failed()

# 自定义错误消息
return R.failed('岗位名称不能重复')

# 自定义错误码和消息
return R.failed(msg='未授权', code=401)

R.page() 分页响应

# 分页响应（由 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	服务器错误	未捕获的异常

错误码与 HTTP 状态码

业务错误码（code 字段）始终为 0 或 1，HTTP 状态码始终为 200。401/403/422 等仅在全局异常处理器中使用，常规业务错误统一返回 code=1。

在 Router 中使用

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)

响应封装层级

• 分页/列表查询：service 返回 R.ok() 或 R.page()
• 详情查询：service 返回 dict/None，router 包 R.ok(data=result)
• 写操作（增/删/改/状态）：service 直接返回 R 对象

WTForms 验证错误响应

WTForms 验证错误由 parse_request_body 函数自动转换为标准格式：

{
    "code": 1,
    "data": null,
    "msg": "岗位名称不能为空",
    "ok": false
}

总结

API 响应规范通过 R 模块统一封装：R.ok() 返回成功、R.failed() 返回失败、R.page() 返回分页。所有响应保持 {code, data, msg, ok} 四字段结构，HTTP 状态码始终为 200。业务层错误统一用 code=1，前端只需判断 ok 字段即可。