API 统一返回格式规范

前后端、网关、日志、APM 全部一套模板，零歧义。所有接口无论成功/失败，body 结构永远保持一致，方便全局拦截器统一序列化。

根对象字段（永远固定 3 个）

字段	类型	出现时机	说明
`code`	string	必有	业务状态码（自定义枚举，0 表示成功）
`msg`	string	必有	人类可读简短描述
`data`	any	可选	业务负载，失败时可为 `null` 或省略

HTTP 状态码只用于网关、负载均衡、浏览器缓存；真正的业务成败以 code=="0" 为准。

成功示例

单资源

json

{
  "code": "0",
  "msg": "OK",
  "data": {
    "userId": 123,
    "username": "alice"
  }
}

列表 + 分页

json

{
  "code": "0",
  "msg": "OK",
  "data": {
    "list": [
      { "userId": 1, "username": "A" },
      { "userId": 2, "username": "B" }
    ],
    "total": 152,
    "page": 3,
    "size": 20,
    "hasNext": true
  }
}

创建成功（HTTP 201 可保留，但 body 仍统一）

http

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "code": "0",
  "msg": "Created",
  "data": { "userId": 123 }
}

无内容删除

http

HTTP/1.1 204 No Content

（body 为空，跳过统一格式）

失败示例

通用业务失败

json

{
  "code": "USER_NOT_FOUND",
  "msg": "用户不存在",
  "data": null
}

字段校验失败（仍返回 HTTP 200，业务 code 非 0）

json

{
  "code": "PARAM_INVALID",
  "msg": "参数校验失败",
  "data": {
    "fields": {
      "email": "非法邮箱格式",
      "age": "必须在 18~120 之间"
    }
  }
}

系统异常（HTTP 500，但 body 仍统一）

http

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
  "code": "INTERNAL_ERROR",
  "msg": "服务器内部错误",
  "data": null
}

业务状态码命名约定

状态码	含义
`"0"`	成功（固定，不可变）
`"FAIL"`	通用业务失败
`"PARAM_INVALID"`	参数错误
`"UNAUTHORIZED"`	鉴权失败
`"FORBIDDEN"`	权限不足
`"NOT_FOUND"`	资源不存在
`"CONFLICT"`	冲突/UNIQUE 冲突
`"TOO_MANY_REQUESTS"`	限流
`"UPSTREAM_TIMEOUT"`	第三方服务超时

全部大写 + 下划线，与 HTTP 状态码解耦，方便后期多语言映射。

快速记忆

永远 3 个字段：code / msg / data
code=="0" 即成功，其余皆失败
HTTP 状态码只给网关用，前端只看 code
失败时 data 可返回辅助信息（如 fields），但绝不抛异常堆栈给前端

字节笔记本

API 统一返回格式规范

根对象字段（永远固定 3 个）

成功示例

单资源

列表 + 分页

创建成功（HTTP 201 可保留，但 body 仍统一）

无内容删除

失败示例

通用业务失败

字段校验失败（仍返回 HTTP 200，业务 code 非 0）

系统异常（HTTP 500，但 body 仍统一）

业务状态码命名约定

快速记忆