48 lines
1.4 KiB
Markdown
48 lines
1.4 KiB
Markdown
# 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)
|