# 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": {
        "records": [ ... ],
        "total": 100,
        "size": 10,
        "current": 1,
        "pages": 10
    },
    "msg": "操作成功",
    "ok": true
}
```

## R 模块使用方法

### R.ok() 成功响应

```python
from utils import 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)
```

## 字段定义

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | int | 状态码：0=成功，1=失败 |
| `data` | any/null | 响应数据，失败时为 null |
| `msg` | string | 提示消息 |
| `ok` | boolean | 是否成功 |

## 状态码规范

| 状态码 | 含义 | 使用场景 |
|--------|------|---------|
| 0 | 成功 | 操作成功 |
| 1 | 失败 | 业务逻辑失败（如参数校验、唯一性冲突） |

:::tip 错误码与 HTTP 状态码
业务错误码（code 字段）始终为 0 或 1，HTTP 状态码始终为 200。401/403 等仅在中间件中使用，常规业务错误统一返回 `code=1`。
:::

## 在 View 中使用

```python
from utils import R

# 查询详情：service 返回 dict，view 包 R.ok
class ExampleDetailView(PermissionRequired, View):
    def get(self, request, id):
        result = services.get_example_detail(id)
        return R.ok(data=result)

# 添加记录：service 直接返回 R 对象
class ExampleAddView(PermissionRequired, View):
    def post(self, request):
        return services.add_example(request)

# 删除记录：service 直接返回 R 对象
class ExampleDeleteView(PermissionRequired, View):
    def delete(self, request, id):
        return services.delete_examples(id)
```

:::tip 响应封装层级
- **分页/列表查询**：service 返回 `R.ok(data=page_data)`
- **详情查询**：service 返回 dict/None，view 包 `R.ok(data=result)`
- **写操作（增/删/改/状态）**：service 直接返回 `R` 对象
:::

## Django 表单验证错误响应

Django 表单验证错误由 `regular.get_err(form)` 转换为标准格式：

```json
{
    "code": 1,
    "data": null,
    "msg": "案例名称不能为空",
    "ok": false
}
```

## 总结

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