HTTP JSON API 规范

导语

💡 本文介绍一套简洁实用的 HTTP JSON API 规范，包含响应体结构与分级状态码设计，帮助团队提升协作效率、降低对接成本。

响应体

返回的数据包含在 HTTP 响应体中。数据必须是一个 JSON Object，包含 code、msg、data 共 3 个字段，其中 data 是可选的。

{
  "code": 0,
  "msg": "success",
  "data": { … } 
}

code (状态码)：
- 类型：整型数字（Integer）
- 作用：精确反馈调用结果。它不仅区分成功与失败，还承载具体的错误分类。
msg (说明信息)：
- 类型：字符串（String）
- 作用：对状态码的文字说明，使客户端能够获取更多信息并进行后续处理。
data (数据载体)：
- 类型：对象（Object）
- 作用：承载具体的响应数据。在无返回数据或操作失败时，该字段可以省略。

状态码

采用 5 位数阶梯式状态码（A-BB-CC），便于维护与扩展：

   A       BB       CC
   │       │        │
   │       │        └── 具体错误序号 (00-99)
   │       └─────────── 业务模块编号 (00-99)
   └─────────────────── 状态大类 (0=success)

code 共 5 位数字，第一位为状态大类（A），中间两位为业务模块编号（BB），最后两位为具体错误序号（CC）。

大类划分

首位	大类	对应 HTTP 状态码
0	成功	200 OK
1	请求错误	400 Bad Request
2	鉴权错误	401 Unauthorized / 403 Forbidden
3	资源错误	404 Not Found
4	业务错误	422 Unprocessable Entity
5	系统内部错误	500 Internal Server Error
6	依赖服务错误	502 Bad Gateway / 503 Service Unavailable
7	限流	429 Too Many Requests
8	(保留)	-
9	(保留)	-