HTTP 状态码对 RESTful API 的设计和使用的影响-JavaScript中文网-JavaScript教程资源分享门户

在设计和使用 RESTful API 时，HTTP 状态码是非常重要的一部分。通过正确使用 HTTP 状态码，可以让 API 更加符合标准，使用者也可以更加容易地理解和处理 API 返回的结果。本文将介绍 HTTP 状态码的基础知识和常见的使用场景，并用实例代码演示它们在 RESTful API 中的应用。

HTTP 状态码简介

HTTP 状态码是指服务器返回给客户端的三位数字代码，用来表示 HTTP 请求的处理结果。HTTP/1.1 协议规定了五种状态码类别，它们分别是：

1xx（信息性状态码）：服务器已经接收到了请求，但需要更多时间来处理。
2xx（成功状态码）：服务器成功接收、理解并处理了请求。
3xx（重定向状态码）：需要进一步的操作才能完成请求。例如，需要跳转到其他 URL。
4xx（客户端错误状态码）：客户端发送了错误的请求。例如，URL 找不到、请求无效等。
5xx（服务器错误状态码）：服务器不能完成对请求的处理。例如，服务器出现错误。

每个状态码的具体含义请参考 RFC 7231。

HTTP 状态码对 RESTful API 的设计与使用

在设计 RESTful API 时，我们通常会遵循 HTTP 协议的规范，使用 HTTP 方法来表示对资源的操作，使用 HTTP 状态码来表示请求的结果。

2xx 状态码

2xx 状态码表示请求成功。在 RESTful API 中，常见的 2xx 状态码有：

200 OK：表示请求已成功，并返回了请求的资源。
201 Created：表示请求已成功，且服务器已创建了新的资源。
204 No Content：表示请求已成功，但没有任何内容需要返回。通常在更新资源或者删除资源时使用。

例如，当我们使用 GET 方法请求某个资源时，如果请求成功，服务器应该返回 200 OK 状态码，并在 response body 中返回请求的资源内容。

示例代码：

HTTP/1.1 200 OK
Content-Type: application/json
{
  "name": "John Smith",
  "age": 30,
  "email": "john.smith@example.com"
}

3xx 状态码

3xx 状态码表示需要进行进一步的操作才能完成请求。在 RESTful API 中，常见的 3xx 状态码有：

301 Moved Permanently：表示请求的资源已永久移动到新的 URL。
302 Found：表示请求的资源已暂时移动到新的 URL。
307 Temporary Redirect：表示请求的资源已暂时移动到新的 URL，客户端需要重发请求。
308 Permanent Redirect：表示请求的资源已永久移动到新的 URL，客户端需要更新 URL。

例如，当我们使用 POST 方法创建资源时，如果服务器需要将请求的资源保存到新的 URL，应该返回 201 Created 状态码和 301 Moved Permanently 或 308 Permanent Redirect 状态码。

示例代码：

HTTP/1.1 201 Created
Content-Location: https://example.com/new_resource

HTTP/1.1 308 Permanent Redirect
Location: https://example.com/new_resource

4xx 状态码

4xx 状态码表示客户端发送了错误的请求。在 RESTful API 中，常见的 4xx 状态码有：

400 Bad Request：表示请求的语法错误或请求无效。
401 Unauthorized：表示请求需要用户认证。
403 Forbidden：表示请求被服务器拒绝，客户端没有足够的权限。
404 Not Found：表示请求的资源不存在。
405 Method Not Allowed：表示请求的方法不被允许。
406 Not Acceptable：表示服务器无法根据客户端请求中的 Accept 头部字段返回格式正确的响应。
422 Unprocessable Entity：表示服务器无法处理请求的格式，通常在 POST、PUT 请求中使用。
429 Too Many Requests：表示用户在给定的时间内发送了过多的请求。

例如，当我们使用 POST 方法创建资源时，如果请求的格式不正确，服务器应该返回 422 Unprocessable Entity 状态码。

示例代码：

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
  "errors": [
    { "message": "missing required field: name", "field": "name" }
  ]
}

5xx 状态码

5xx 状态码表示服务器出现错误，无法完成对请求的处理。在 RESTful API 中，常见的 5xx 状态码有：

500 Internal Server Error：表示服务器出现了错误，无法完成对请求的处理。
502 Bad Gateway：表示服务器充当网关或代理服务器时收到了无效响应。
503 Service Unavailable：表示服务器暂时无法处理请求。通常在服务器过载或维护时使用。
504 Gateway Timeout：表示客户端与服务器之间的网关或代理服务器之间发生超时。

例如，当我们使用 GET 方法请求资源时，如果服务器出现了内部错误，应该返回 500 Internal Server Error 状态码。

示例代码：

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
  "message": "internal server error"
}

总结

HTTP 状态码是 RESTful API 设计中非常重要的一部分，它可以给客户端提供有用的信息，指导客户端如何处理 API 的返回结果。正确使用 HTTP 状态码还可以让 API 更加符合标准，提高易用性和可维护性。在开发 RESTful API 时，请务必考虑它们的使用场景，选择合适的状态码，使 API 更加优雅、稳定和易用。

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/64dd8516f6b2d6eab38b94a9