导语
在前后端分离与微服务架构盛行的今天，设计一套统一、清晰且具备高可扩展性的 API 响应规范，是保障团队协同效率、降低系统对接成本的关键。
本文将介绍并解析一种优秀的 HTTP JSON API 规范，并探讨其设计背后的逻辑与最佳实践。
响应体
返回的数据包含在 HTTP 响应体中。数据必须是一个 JSON Object，包含 code、msg、data 共 3 个字段，其中 data 是可选的。
{
"code": 0,
"msg": "success",
"data": { … }
}code(状态码)：类型：整型数字（Integer）
作用：精确表达业务逻辑的执行结果。它不仅区分成功与失败，还承载具体的业务错误分类。
msg(说明信息)：类型：字符串（String）
作用：对状态码的文字说明。既可以是面向开发者的调试信息，也可以是直接展示给终端用户的友好提示。
data(数据载体)：类型：对象（Object）/ 数组（Array）
作用：承载具体的业务响应数据。在无返回数据或操作失败时，该字段可以省略。
状态码
为了解决状态码杂乱无章、难以维护的问题，本规范引入了 5 位数阶梯式状态码 机制。
A-BB-CC
A BB CC
│ │ │
│ │ └── 具体错误序号 (00-99)
│ └─────────── 业务模块编号 (00-99)
└─────────────────── 状态大类 (0=success)code 共 5 位数字，第一位为状态大类（A），中间两位为业务模块编号（BB），最后两位为具体错误序号（CC）。
大类划分
结语
统一的 API 规范不仅能够显著降低前后端沟通成本，还能使自动化测试、接口监控与网关告警的建设事半功倍。
通过精细化的 A-BB-CC 状态码设计与合理的 HTTP 状态映射，团队可以构建出既符合业界标准又具备高度灵活性的企业级 API 服务体系。