RESTful API 已经成为 Web 开发中常用的架构风格，可以帮助前端和后端开发者实现资源的创建、读取、更新和删除操作。对于 RESTful API 的开发者来说，了解 HTTP 返回码规范是非常重要的，因为 HTTP 返回码可以让 API 的用户了解与请求相关的状态，并且在返回错误时给出有用的信息，提高了程序的健壮性和用户体验。
在这篇文章里，我们将详细介绍 RESTful API 的 HTTP 返回码规范，包括状态码的分类、具体的状态码及其含义，并给出相应状态码的示例代码。同时，我们也会探讨如何根据不同的返回码来处理 API 的响应，并提供一些指导性的思路。
HTTP 返回码的分类
HTTP 返回码可以分为五类，这五类码的第一位数字表示状态码的类别，状态码的具体含义则由后两位数字决定：
- 1xx（Informational）：表示请求已经被接收，继续处理。
- 2xx（Successful）：表示请求已经成功被接收、理解、并接受。
- 3xx（Redirection）：表示需要进一步操作，比如重定向。
- 4xx（Client Error）：表示客户端请求错误，服务器无法处理。
- 5xx（Server Error）：表示服务器端错误，无法完成请求。
在 RESTful API 中，比较常用的返回码有 200、401、404、422 和 500 等。
接下来我们来详细介绍每个返回码的含义。
具体的 HTTP 返回码及其含义
200 OK
200 OK 表示成功的请求返回。这个状态码经常用于 GET、POST、PUT 和 DELETE 方法。成功的响应会返回请求信息的主体部分。
示例代码：
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 123
{
"name": "RESTful API",
"version": "1.0.0"
}201 Created
201 Created 表示资源已经成功创建。通常情况下，这个状态码会在 POST 方法中使用。
示例代码：
-- -------------------- ---- ------- -------- --- ------- ------------- ---------------- --------------- --- --------- ----------------- - ------- ---------- ----- - -
400 Bad Request
400 Bad Request 表示客户端请求错误。当客户端的请求没有遵循 API 设计的规则时，服务器会返回这个状态码。
示例代码：
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 64
{
"message": "The request is malformed.",
"code": "INVALID_REQUEST"
}401 Unauthorized
401 Unauthorized 表示未进行身份验证或者验证失败。客户端需要提供正确的身份验证信息才能访问API的资源。
示例代码：
-- -------------------- ---- -------
-------- --- ------------
----------------- ----- ----------- ------- ------
------------- ---------- -------------
--------- -----
------
------
---------- ------------- ----------------
-------
------
--------
----------------- -------------
---------
-------
-------403 Forbidden
403 Forbidden 表示客户端请求被拒绝。通常情况下，API 服务器有设置，仅允许授权用户访问API。
示例代码：
HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: 32
{
"message": "Access denied.",
"code": "FORBIDDEN"
}404 Not Found
404 Not Found 表示客户端请求的资源不存在。这个状态码通常会在客户端请求一个错误的 URL 时出现。
示例代码：
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 32
{
"message": "Resource not found.",
"code": "NOT_FOUND"
}405 Method Not Allowed
405 Method Not Allowed 表示请求方法是不被允许的。比如，客户端试图在一个只读的资源上进行 write 请求。
示例代码：
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Content-Length: 45
{
"message": "The method is not allowed.",
"code": "METHOD_NOT_ALLOWED"
}422 Unprocessable Entity
422 Unprocessable Entity 表示客户端的请求被服务器所理解，但是请求参数不符合服务器的要求或者格式不正确。
示例代码：
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: 43
{
"message": "Request parameter is invalid.",
"code": "VALIDATION_FAILED"
}500 Internal Server Error
500 Internal Server Error 表示服务器错误。通常情况下，这个状态码会在 API 服务器无法执行 API 请求时返回。
示例代码：
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 34
{
"message": "Internal server error.",
"code": "SERVER_ERROR"
}如何处理 HTTP 返回码
了解 HTTP 返回码的含义并不意味着我们已经掌握了如何处理它们。在面对各种返回码时，我们需要清晰地知道该如何处理它们，以使 API 的结果信息从状态码中表现的足够明确和友好。
以下是一些处理与 HTTP 返回码有关的错误的指导性思路：
- 处理 200：绝大多数情况下，HTTP 200 是正常响应的状态码，如果有必要可以使用 Your API is working as expected. 返回这个状态码。
- 处理 201：成功创建资源并返回 201 状态码。同时，下一步的处理就取决于你是否要在请求正文中返回该资源的详细信息。如果要，则为此资源提供一个位置，然后返回状态码201 和资源的详细信息。
- 处理 401：可以显示一个 "Unauthorised!" 或 "401 unauthorised!" 和一个重试机制，或者简单地声明 "Invalid request" 以避免暴露服务器的细节。
- 处理 403：与401相同，通常会提供一个 "Access Denied" 的消息。但是，中心重点是确保一个清晰的机制，可以让用户访问需要认证才能获得的功能，而不是简单地停留在 "You cannot access this page" 的信息上。
- 处理 404：可视为用户的错误，但作为API的拥有者，我们需要确保提供尽可能精准的错误信息。这一步始终围绕着确保错误提示是清晰的，并且稍后能够解决 404 错误。
- 处理 405：与404类似，因为它可以作为 "this request was completely wrong" 的信息。应该考虑一下这样的细节，以确保客户端已经理解它是因为提交了禁止请求而收到了错误。
结论
本文详细介绍了 RESTful API 的 HTTP 返回码规范，并给出了每个状态码的具体含义和示例代码。对于想要开发 RESTful API 的前端和后端工程师来说，了解这些状态码规范是非常重要的。同时，文章也提供了处理 HTTP 返回码的思路，可以帮助开发者更好地处理和响应 API 请求。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/66f64f20c5c563ced5822f50