目前开发的项目很大程度上是为明年的国产化做准备了,所以借这个机会把用了十年的自研系统全部重写,订立更严格的规范,本文记录一下返回格式及对应状态码。
常见 HTTP 状态码及解释
HTTP 状态码用于表示客户端请求的响应状态,它们分为五类:2xx 表示成功,3xx 表示重定向,4xx 表示客户端错误,5xx 表示服务器错误。以下是各类状态码的详细解释。
2xx 成功响应
状态码 | 含义 | 解释 |
---|---|---|
200 | OK | 请求成功,服务器返回了请求的数据。GET 请求通常返回数据,PUT/POST 请求返回更新或创建的数据。 |
201 | Created | 请求成功创建了新资源,通常用于 POST 或 PUT 请求。响应头包含新资源的 URL。 |
202 | Accepted | 请求已接受,但尚未完成处理,通常用于异步任务。 |
204 | No Content | 请求成功,但服务器未返回内容,常用于删除操作或不需返回内容的操作。 |
3xx 重定向
状态码 | 含义 | 解释 |
---|---|---|
301 | Moved Permanently | 资源的 URL 已永久更改,客户端应重定向到新的 URL,响应头包含 Location 字段。 |
302 | Found | 资源的 URL 暂时更改,客户端通常会重定向到响应头中的 Location 字段。 |
304 | Not Modified | 资源未更改,客户端可以使用缓存版本,通常用于浏览器缓存优化。 |
4xx 客户端错误
状态码 | 含义 | 解释 |
---|---|---|
400 | Bad Request | 请求有误,服务器无法处理,通常由于无效的请求参数。错误详情通常在响应体的 errors 字段中返回。 |
401 | Unauthorized | 未经授权,通常是由于缺少或无效的身份认证(如 Token)。 |
403 | Forbidden | 已认证用户无权访问该资源,即使认证通过也无法访问。 |
404 | Not Found | 资源未找到,通常表示客户端请求的 URL 或资源不存在。 |
405 | Method Not Allowed | 请求方法不被允许,例如对只支持 GET 的资源使用了 POST。 |
422 | Unprocessable Entity | 请求格式正确,但语义错误,服务器无法处理。例如,提交了无效的数据格式。 |
5xx 服务器错误
状态码 | 含义 | 解释 |
---|---|---|
500 | Internal Server Error | 服务器内部错误,可能是未知问题或代码异常导致无法完成请求。 |
502 | Bad Gateway | 作为网关或代理的服务器从上游服务器收到无效响应,通常表示服务器之间的通信问题。 |
503 | Service Unavailable | 服务器暂时无法处理请求,通常用于服务器维护或过载。 |
504 | Gateway Timeout | 作为网关或代理的服务器未能在规定时间内从上游服务器获得响应。 |
状态码使用建议
成功场景
- 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": "user123@example.com","phone": "12345678901","role": "admin"},"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"errors": []
}
错误响应结构示例
{"status": "error","code": 400,"message": "请求参数错误","data": {},"errors": [{"field": "username","message": "用户名不能为空"},{"field": "password","message": "密码长度必须大于6个字符"}]
}
错误响应格式(带有数据)
- 部分成功的数据: 在一些批量操作(如文件上传或数据验证)中,前端可能希望了解哪些请求成功,哪些失败,以便更好地展示处理状态。
- 默认值提示: 当输入缺少时,data 可以返回可用的默认值或推荐值。
如果允许在错误情况下返回 data,建议在 errors 中提供尽可能详细的说明,以便前端清楚如何使用 data 中的内容。可以考虑以下格式:
{"code": 400,"message": "请求参数错误,部分数据不可用","data": {"user": {"username": "user123", // 部分有效数据"email": "user123@example.com"},"defaults": {"role": "guest" // 默认值或推荐值}},"errors": [{"field": "phone","message": "手机号格式不正确"},{"field": "password","message": "密码长度必须大于6个字符"}]
}
结构设计建议
- data 和 errors 可共存,允许在错误响应中返回部分有效数据及详细错误信息。
- message 提供简短描述,便于用户理解。
- code 以 HTTP 状态码的数字形式显示,便于客户端判断请求状态。
- code 和 status 可以考虑合并
这种设计能确保数据结构清晰,便于前后端调试与维护。