签入版本

2026-09-16 13:28:20 +08:00
parent 6cd5e80de0
commit c97d87847f
410 changed files with 68726 additions and 0 deletions
@@ -0,0 +1,154 @@
+# 统一响应封装（R 对象）
+
+:::tip 说明
+`src/core/response.py` 提供统一的 API 响应封装，所有接口返回格式为 `{code, data, msg, ok}`。R 对象是全局统一的响应工具类。
+:::
+
+## 响应格式
+
+```json
+{
+    "code": 0,
+    "data": {},
+    "msg": "操作成功",
+    "ok": true
+}
+```
+
+| 字段 | 类型 | 说明 |
+|:-----|:-----|:-----|
+| `code` | int | 状态码：0=成功，非0=失败 |
+| `data` | any | 响应数据 |
+| `msg` | string | 提示信息 |
+| `ok` | bool | 是否成功 |
+
+## R 对象方法
+
+### R.ok — 成功响应
+
+```python
+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 — 失败响应
+
+```python
+# 基本失败
+R.failed(handler)
+
+# 自定义消息
+R.failed(handler, msg="用户名已存在")
+
+# 自定义状态码
+R.failed(handler, code=401, msg="未授权")
+```
+
+### R.response — 自定义响应
+
+```python
+# 完全自定义
+R.response(handler, code=0, data={}, msg="自定义", ok=True)
+```
+
+## 实现原理
+
+```python
+# 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 状态码
+
+```python
+class Codes:
+    SUCCESS = 0          # 成功
+    FAILED = 1           # 业务失败
+    UNAUTHORIZED = 401   # 未授权
+    FORBIDDEN = 403      # 无权限
+    NOT_FOUND = 404      # 资源不存在
+    SERVER_ERROR = 500   # 服务器错误
+```
+
+## 使用规范
+
+### Handler 层使用
+
+```python
+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 层使用
+
+```python
+class LinkService(BaseService):
+    async def add(self, handler):
+        # Service 返回 R 对象
+        # ...
+        return R.ok(handler, msg="添加成功")
+```
+
+### 异常处理中的使用
+
+```python
+# 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=...)` 完成响应。