# 统一响应封装（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=...)` 完成响应。