统一响应封装（R 对象）

说明

src/core/response.py 提供统一的 API 响应封装，所有接口返回格式为 {code, data, msg, ok}。R 对象是全局统一的响应工具类。

响应格式

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

字段	类型	说明
code	int	状态码：0=成功，非0=失败
data	any	响应数据
msg	string	提示信息
ok	bool	是否成功

R 对象方法

R.ok — 成功响应

from core import response as R

# 基本成功
R.ok(handler)

# 带数据
R.ok(handler, data={"id": 1, "name": "admin"})

# 自定义消息
R.ok(handler, msg="注册成功")

# 带分页
R.ok(handler, data={"list": [...], "total": 100})

R.failed — 失败响应

# 基本失败
R.failed(handler)

# 自定义消息
R.failed(handler, msg="用户名已存在")

# 自定义状态码
R.failed(handler, code=401, msg="未授权")

R.response — 自定义响应

# 完全自定义
R.response(handler, code=0, data={}, msg="自定义", ok=True)

实现原理

# src/core/response.py
from core.base_handler import BaseHandler

class R:
    @staticmethod
    def ok(handler: BaseHandler, data=None, msg="操作成功"):
        handler.finish({
            "code": Codes.SUCCESS,
            "data": data,
            "msg": msg,
            "ok": True,
        })

    @staticmethod
    def failed(handler: BaseHandler, msg="操作失败", code=Codes.FAILED):
        handler.finish({
            "code": code,
            "data": None,
            "msg": msg,
            "ok": False,
        })

    @staticmethod
    def response(handler: BaseHandler, code=0, data=None, msg="", ok=True):
        handler.finish({
            "code": code,
            "data": data,
            "msg": msg,
            "ok": ok,
        })

Codes 状态码

class Codes:
    SUCCESS = 0          # 成功
    FAILED = 1           # 业务失败
    UNAUTHORIZED = 401   # 未授权
    FORBIDDEN = 403      # 无权限
    NOT_FOUND = 404      # 资源不存在
    SERVER_ERROR = 500   # 服务器错误

使用规范

Handler 层使用

class LinkDetailHandler(BaseHandler):
    @permission_required("sys:link:detail")
    async def get(self, id):
        # Service 返回原始数据时，用 R.ok 包装
        return R.ok(self, data=link_service.get_detail(id))

Service 层使用

class LinkService(BaseService):
    async def add(self, handler):
        # Service 返回 R 对象
        # ...
        return R.ok(handler, msg="添加成功")

异常处理中的使用

# src/core/base_handler.py
def write_error(self, status_code, **kwargs):
    exc = kwargs.get("exc_info", (None, None, None))[1]
    if isinstance(exc, BaseAppError):
        self.finish({"code": exc.code, "data": None, "msg": exc.msg, "ok": False})

与 Tornado 的区别

方面	说明
响应方式	R.ok(self, data=...) / R.failed(self, msg=...)
底层实现	self.finish(body) 写出 JSON
Handler 参数	self（Handler 实例）

总结

R 对象是统一响应封装的核心工具，所有 API 返回 {code, data, msg, ok} 格式。成功用 R.ok()，失败用 R.failed()，自定义用 R.response()。Handler 层直接调用 R.ok(self, data=...) 完成响应。