签入版本

DjangoAdmin_FastAPI_NaiveVue/zh/volume7/api-response.md

@@ -0,0 +1,162 @@
+# 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 core 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)
+```
+
+### R.page() 分页响应
+
+```python
+# 分页响应（由 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 | 验证错误 | Pydantic 参数校验失败 |
+| 500 | 服务器错误 | 未捕获的异常 |
+
+:::tip 错误码与 HTTP 状态码
+业务错误码（code 字段）始终为 0 或 1，HTTP 状态码始终为 200。401/403/422 等仅在全局异常处理器中使用，常规业务错误统一返回 `code=1`。
+:::
+
+## 在 Endpoint 中使用
+
+```python
+from core import R
+
+# 查询详情：service 返回 dict，endpoint 包 R.ok
+@router.get('/detail/{id}')
+def detail(request: Request, id):
+    result = position_service.get_detail(id)
+    return R.ok(data=result)
+
+# 添加记录：service 直接返回 R 对象
+@router.post('/add')
+def add(request: Request, data: PositionForm):
+    return position_service.add(request, data)
+
+# 删除记录：service 直接返回 R 对象
+@router.delete('/delete/{id}')
+def delete(request: Request, id):
+    return position_service.delete(id)
+```
+
+:::tip 响应封装层级
+- **分页/列表查询**：service 返回 `R.ok()` 或 `R.page()`
+- **详情查询**：service 返回 dict/None，endpoint 包 `R.ok(data=result)`
+- **写操作（增/删/改/状态）**：service 直接返回 `R` 对象
+:::
+
+## Pydantic 验证错误响应
+
+Pydantic 验证错误由全局 `RequestValidationError` 处理器自动转换为标准格式：
+
+```json
+{
+    "code": 1,
+    "data": null,
+    "msg": "name: 字段不能为空 / status: 输入值超出范围",
+    "ok": false
+}
+```
+
+## 总结
+
+API 响应规范通过 `R` 模块统一封装：`R.ok()` 返回成功、`R.failed()` 返回失败、`R.page()` 返回分页。所有响应保持 `{code, data, msg, ok}` 四字段结构，HTTP 状态码始终为 200。业务层错误统一用 `code=1`，前端只需判断 `ok` 字段即可。