# 12.1 API 响应规范

:::tip 必须遵守
所有接口一律返回统一 JSON 信封，对外码值只有 0 / 1 / 401 三值语义。业务代码禁止自造响应形态。
:::

## 信封

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

| 码值 | 语义 | 前端行为 |
|---|---|---|
| 0 | 成功 | 取 data |
| 1 | 失败 | 弹 msg |
| 401 | 未认证 | 跳登录（或刷新令牌） |

内部细分码（400/403/429/1xxx）只用于服务端日志与文档，对外统一收敛（401 除外）。

## 构造规约

| 场景 | 写法 |
|---|---|
| 成功带数据 | `response.Ok(data)` |
| 成功自定义文案 | `response.OkMsg(msg, data)` |
| 分页 | `dto.NewPageData(...)` 经信封返回 |
| 业务失败 | `return nil, consts.CodeXxx` / `apperr.Newf(...)` |
| 禁止 | handler 手写 JSON、自定义 code 集、裸写 HTTP 状态 |

## 禁则

- 禁止返回 HTML 错误页（NoRoute/panic 已保证 JSON 兜底）
- 禁止 data 内嵌套第二套 code/msg
- 禁止吞错后返回"成功"空数据
- 禁止在业务层直接 `response.Write`（信封由绑定层与中间件统一负责）

## 检查点

- 新接口响应经信封且 code 语义正确
- 前端只按 0/1/401 三分支处理
- 错误 msg 是面向用户的中文提示（不含技术栈细节）

## 相关

- [8.1 统一响应格式](/zh/api-spec/response.html)
- [8.2 错误码对照表](/zh/api-spec/error-code.html)