8.1 统一响应格式

概述

全部接口返回统一 JSON 信封：code/ok/msg/data 四字段。code=0 成功、1 通用失败、401 未认证（配合 HTTP 401）；前端按 code 分流。分页用 PageData 泛型壳。

信封结构

// 成功
{
  "code": 0,
  "ok": true,
  "msg": "操作成功",
  "data": { "id": 1 }
}

// 失败
{
  "code": 1,
  "ok": false,
  "msg": "用户不存在",
  "data": {}
}

// 未认证（HTTP 401）
{
  "code": 401,
  "ok": false,
  "msg": "登录已过期，请重新登录",
  "data": {}
}

字段约定

字段	类型	说明
code	int	0=成功；1=通用失败；401=未认证；细分业务码见 8.2（前端主要看 0/1/401）
ok	bool	与 code==0 等价的布尔便捷字段
msg	string	提示信息；失败时前端弹出
data	object	业务数据；失败时为空对象 {}（非 null）

Fail 映射规则

response.Fail(err)：
  gerror 码 == 401 → 原样保留（配合 HTTP 401，前端跳登录）
  其余             → 一律降级 code=1

设计含义：consts 中的细分错误码（1001 用户不存在……）主要用于
日志与服务端语义区分；前端统一按 1 弹 msg 即可。

分页壳（PageData[T]）

{
  "code": 0, "ok": true, "msg": "操作成功",
  "data": {
    "records": [ ... ],
    "total": 100,
    "size": 10,
    "current": 1,
    "pages": 10
  }
}

字段	说明
records	行数组；为空输出 [] 而非 null
total	总条数
size	每页条数（pageSize，默认 10 上限 500）
current	当前页码（pageNo，默认 1）
pages	总页数

其他通用出参形态

新增：  {"id": 1}                         （IdRes）
修改/删除：{}                             （空结构体）
列表（非分页）：[ ... ]                    （数组直接作 data）
详情：  { ...单对象... }

状态页

404 → {"code":1,"msg":"接口不存在: GET /api/xxx"}
500 → {"code":1,"msg":"服务器内部错误"}
非 200 一律输出统一 JSON 信封，不返回 HTML

前端处理模板

// 响应拦截器分流（语义示意）
if (code === 0) return data;            // 成功解包
if (code === 401) { 跳登录/尝试refresh; }
if (code === 1) ElMessage.error(msg);   // 统一弹窗

开发规约

• 出参 json 一律驼峰；唯一例外是登录/令牌接口的下划线字段（见 8.6）
• 业务错误用 gerror.NewCode(consts.Xxx, "消息") 上抛，由 Bind 包装层统一 Fail
• 不要在业务代码手写 JSON 响应（统一信封在包装层完成）
• data 为 nil 时框架输出 {}/[]，业务无需特殊处理