签入版本

EasyGoAdmin_Gin_AntdVue/zh/standards/api-response.md

@@ -1,135 +1,47 @@
 # 12.1 API 响应规范
 
-:::tip 概述
-所有接口返回统一的 JSON 结构，前端可据此判断请求结果。成功响应 `code=0`，失败响应 `code=1`（或 401/403/404/422）。
+:::tip 必须遵守
+所有接口一律返回统一 JSON 信封，对外码值只有 0 / 1 / 401 三值语义。业务代码禁止自造响应形态。
 :::
 
-## 统一格式
-
-```typescript
-interface ApiResponse {
-    code: number;   // 状态码：0=成功，其他=失败
-    ok: boolean;    // 是否成功
-    msg: string;    // 提示信息
-    data: any;      // 响应数据
-}
-```
-
-## 成功响应
+## 信封
 
 ```json
-{
-    "code": 0,
-    "ok": true,
-    "msg": "操作成功",
-    "data": {
-        "id": 1,
-        "username": "admin",
-        "createTime": "2026-01-01 00:00:00"
-    }
-}
+{ "code": 0, "ok": true, "msg": "操作成功", "data": {} }
 ```
 
-## 分页响应
+| 码值 | 语义 | 前端行为 |
+|---|---|---|
+| 0 | 成功 | 取 data |
+| 1 | 失败 | 弹 msg |
+| 401 | 未认证 | 跳登录（或刷新令牌） |
 
-```json
-{
-    "code": 0,
-    "ok": true,
-    "msg": "操作成功",
-    "data": {
-        "records": [
-            { "id": 1, "username": "admin" }
-        ],
-        "total": 100,
-        "size": 20,
-        "current": 1,
-        "pages": 5
-    }
-}
-```
+内部细分码（400/403/429/1xxx）只用于服务端日志与文档，对外统一收敛（401 除外）。
 
-## 失败响应
+## 构造规约
 
-```json
-{
-    "code": 1,
-    "ok": false,
-    "msg": "用户名已存在",
-    "data": null
-}
-```
+| 场景 | 写法 |
+|---|---|
+| 成功带数据 | `response.Ok(data)` |
+| 成功自定义文案 | `response.OkMsg(msg, data)` |
+| 分页 | `dto.NewPageData(...)` 经信封返回 |
+| 业务失败 | `return nil, consts.CodeXxx` / `apperr.Newf(...)` |
+| 禁止 | handler 手写 JSON、自定义 code 集、裸写 HTTP 状态 |
 
-## 字段说明
+## 禁则
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `code` | number | 状态码，0=成功 |
-| `ok` | boolean | 是否成功 |
-| `msg` | string | 提示信息 |
-| `data` | any | 响应数据，失败时通常为 null |
-| `data.records` | array | 分页数据列表 |
-| `data.total` | number | 总记录数 |
-| `data.size` | number | 每页条数 |
-| `data.current` | number | 当前页码 |
-| `data.pages` | number | 总页数 |
+- 禁止返回 HTML 错误页（NoRoute/panic 已保证 JSON 兜底）
+- 禁止 data 内嵌套第二套 code/msg
+- 禁止吞错后返回"成功"空数据
+- 禁止在业务层直接 `response.Write`（信封由绑定层与中间件统一负责）
 
-## 驼峰自动转换
+## 检查点
 
-响应数据自动从 snake_case 转为 camelCase：
+- 新接口响应经信封且 code 语义正确
+- 前端只按 0/1/401 三分支处理
+- 错误 msg 是面向用户的中文提示（不含技术栈细节）
 
-| 数据库字段 | 响应字段 |
-|-----------|---------|
-| `create_time` | `createTime` |
-| `user_name` | `userName` |
-| `is_delete` | `isDelete` |
+## 相关
 
-可通过 `config/api.php` 的 `camel_snake_convert` 配置关闭。
-
-## 后端构造方式
-
-```php
-// Controller 中
-return $this->success($data, '操作成功');       // 成功
-return $this->success(['id' => $id], '添加成功'); // 成功（带数据）
-return $this->fail('用户名已存在');              // 失败
-return $this->_page($result);                    // 分页
-```
-
-```php
-// Result 类直接调用
-Result::success($data, $msg);
-Result::page($records, $total, $current, $size);
-Result::fail($msg, $code);
-Result::unauthorized($msg);  // 401
-Result::forbidden($msg);     // 403
-Result::notFound($msg);      // 404
-Result::validateError($errors); // 422 参数验证失败
-```
-
-### validateError 示例
-
-`Result::validateError()` 用于参数验证失败场景，HTTP 状态码为 422，`data` 字段返回具体错误明细，便于前端逐字段提示：
-
-```php
-// 直接传字符串
-return Result::validateError('用户名不能为空');
-
-// 传数组，包含多个字段错误
-return Result::validateError([
-    'username' => '用户名不能为空',
-    'email'    => '邮箱格式不正确',
-]);
-```
-
-```json
-{
-    "code": 422,
-    "ok": false,
-    "msg": "参数验证失败",
-    "data": {
-        "username": "用户名不能为空",
-        "email": "邮箱格式不正确"
-    }
-}
-```
+- [8.1 统一响应格式](/zh/api-spec/response.html)
+- [8.2 错误码对照表](/zh/api-spec/error-code.html)