常见 HTTP 状态码分类和解释及服务端向前端返回响应时的最完整格式

目前的开发项目，准备明年的国产化，用了十年的自研系统借这个机会全部重写，订立更严格的规范，这里把返回格式及对应状态码记录一下。

常见 HTTP 状态码及解释

HTTP 状态码用于表示客户端请求的响应状态，它们分为五类：2xx 表示成功，3xx 表示重定向，4xx 表示客户端错误，5xx 表示服务器错误。以下是各类状态码的详细解释。

2xx 成功响应

3xx 重定向

4xx 客户端错误

5xx 服务器错误

状态码使用建议

成功场景

• 200 OK：用于数据获取（GET 请求）和数据更新（PUT 请求）的成功响应。
• 201 Created：用于新资源创建成功，POST 或 PUT 请求中常见。
• 204 No Content：用于不返回数据的请求，例如删除或不需返回内容的请求。

错误场景

• 400 Bad Request：用于无效参数错误，并返回详细的 errors 信息。
• 401 Unauthorized：用于身份认证失败。
• 403 Forbidden：用于权限不足时的响应。
• 404 Not Found：用于资源不存在的情况，客户端请求的 URL 错误时常见。
• 422 Unprocessable Entity：用于语义错误或数据校验失败，并可返回具体错误信息。

系统级别问题

• 500 Internal Server Error、502 Bad Gateway、503 Service Unavailable：用于服务器内部、网关或资源不可用等问题，通常表明可以稍后重试请求。

示例响应结构

设计响应结构时，可以包含 status、code、message、data 和 errors 等字段，以便前端能快速判断响应结果。

成功响应结构示例

{
  "status": "success",
  "code": 200,
  "message": "获取用户信息成功",
  "data": {
    "user": {
      "id": 1,
      "username": "user123",
      "email": "[email protected]",
      "phone": "12345678901",
      "role": "admin"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "errors": []
}

错误响应结构示例

{
  "status": "error",
  "code": 400,
  "message": "请求参数错误",
  "data": {},
  "errors": [
    {
      "field": "username",
      "message": "用户名不能为空"
    },
    {
      "field": "password",
      "message": "密码长度必须大于6个字符"
    }
  ]
}

错误响应格式（带有数据）

1. 部分成功的数据： 在一些批量操作（如文件上传或数据验证）中，前端可能希望了解哪些请求成功，哪些失败，以便更好地展示处理状态。
2. 默认值提示： 当输入缺少时，data 可以返回可用的默认值或推荐值。

如果允许在错误情况下返回 data，建议在 errors 中提供尽可能详细的说明，以便前端清楚如何使用 data 中的内容。可以考虑以下格式：

{
  "code": 400,
  "message": "请求参数错误，部分数据不可用",
  "data": {
    "user": {
      "username": "user123",     // 部分有效数据
      "email": "[email protected]"
    },
    "defaults": {
      "role": "guest"             // 默认值或推荐值
    }
  },
  "errors": [
    {
      "field": "phone",
      "message": "手机号格式不正确"
    },
    {
      "field": "password",
      "message": "密码长度必须大于6个字符"
    }
  ]
}

结构设计建议

• data 和 errors 可共存，允许在错误响应中返回部分有效数据及详细错误信息。
• message 提供简短描述，便于用户理解。
• code 以 HTTP 状态码的数字形式显示，便于客户端判断请求状态。
• code 和 status 可以考虑合并

这种设计能确保数据结构清晰，便于前后端调试与维护。