# 8.1 统一响应格式

:::tip 概述
所有接口返回统一 JSON 信封。对外业务码只有三种：**0 成功、1 失败（msg 说明原因）、401 未认证**——前端判断零歧义，详细原因经 msg 透出。
:::

## 信封结构

```typescript
interface Res {
    code: number;   // 0=成功，1=失败，401=登录过期
    ok: boolean;    // 是否成功
    msg: string;    // 提示信息
    data: any;      // 数据（无数据为 null 或 {}）
}
```

## 成功

```json
{
    "code": 0,
    "ok": true,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "username": "admin"
    }
}
```

自定义成功文案用 `OkMsg(msg, data)`（如导入结果提示）。

## 分页

```json
{
    "code": 0,
    "ok": true,
    "msg": "操作成功",
    "data": {
        "records": [ { "id": 1, "name": "示例" } ],
        "total": 100,
        "size": 20,
        "current": 1,
        "pages": 5
    }
}
```

records 为空时输出 `[]` 而非 null（NewPageData 保证）。

## 失败

```json
{ "code": 1, "ok": false, "msg": "案例名称已存在", "data": {} }
```

## 未认证

```json
{ "code": 401, "ok": false, "msg": "登录已过期，请重新登录", "data": {} }
```

401 **原码透出**（不映射为 1），前端据此跳登录页。

## 码映射规则（后端内部 → 对外）

后端内部错误码丰富（400/403/429/1001…，见 [8.2 错误码对照表](/zh/api-spec/error-code.html)），经 response.Fail 统一收敛：

```text
内部 401 → 对外 401（原样，触发前端跳登录）
其余非 0 → 对外 1（msg 取内部码的中文消息）
```

这样前端只需三分支：`code===0` 成功 / `code===401` 跳登录 / 其余弹 msg。

## HTTP 状态码

响应体 code 与 HTTP 状态码同步（写信封时按 code 定状态），非 2xx 时响应体仍是 JSON 信封——不存在裸错误页。

## 构造 API（后端）

| 函数 | 用途 |
|---|---|
| response.Ok(data) | 成功 |
| response.OkMsg(msg, data) | 成功 + 自定义文案 |
| response.Page(list, total) | 分页 |
| response.Fail(err) | 失败（apperr 按码，其余通用 1） |
| response.FailCode(base, format, args) | 指定错误码 + 格式化消息 |

## 下一步

→ [8.2 错误码对照表](/zh/api-spec/error-code.html)