1.4 KiB
1.4 KiB
12.1 API 响应规范
:::tip 必须遵守 所有接口一律返回统一 JSON 信封，对外码值只有 0 / 1 / 401 三值语义。业务代码禁止自造响应形态。 :::
信封
{ "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 是面向用户的中文提示（不含技术栈细节）