RESTful API 中如何正确使用 HTTP 状态码-JavaScript中文网-JavaScript教程资源分享门户

在设计和开发 RESTful API 中，HTTP 状态码是一项非常重要的元素。它们可以提供对客户端的请求操作结果的详细信息，同时还可以帮助开发者识别和调试 API 中可能出现的问题。本文将探讨如何正确地使用 HTTP 状态码来构建健壮的 RESTful API。

HTTP 状态码的基本概念

HTTP 状态码是一个三位数字，其中第一个数字表示当前响应所属的响应类别。它们由 HTTP 协议定义，并且通常由客户端和服务器之间的请求和响应交互使用。

以下是一些常见的 HTTP 状态码类别：

1xx（信息性状态码）：反映请求已经被接受或正在进行处理。
2xx（成功状态码）：反映请求已经被成功接受、理解、并被处理。
3xx（重定向状态码）：反映需要客户端的进一步操作以完成请求。
4xx（客户端错误状态码）：反映客户端发出的请求错误或无法完成请求。
5xx（服务器错误状态码）：反映服务器正在处理请求时出现错误。

2xx 状态码

2xx 状态码是 RESTful API 中最常用的状态码科，它们表示请求已经成功处理，并且给予客户端正确的响应。其中，最常见的状态码是：

200 OK

200 OK 是最常见的状态码。它表明服务器已经成功处理请求，并返回了所请求的实体。这通常发生在 GET 或 PUT 请求中。

以下是一个示例代码：

HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": 1,
    "name": "Restful API",
    "description": "This is a RESTful API example."
}

201 Created

201 Created 响应状态码表示一项新资源已成功创建。通常发生在 POST 请求中。

以下是一个示例代码：

HTTP/1.1 201 Created
Location: /api/v1/posts/1
Content-Type: application/json
{
    "id": 1,
    "title": "New Post",
    "content": "This is a new post."
}

3xx 状态码

3xx 状态码表示需要客户端执行附加操作以完成请求，例如重定向。以下是其中两个常见的 3xx 状态码：

301 Moved Permanently

301 Moved Permanently 响应状态码表示所请求的资源已经被永久移动到一个新的地址。客户端被要求使用新地址重新发出请求。

以下是一个示例代码：

HTTP/1.1 301 Moved Permanently
Location: http://example.com/new-resource-url

304 Not Modified

304 Not Modified 响应状态码表示请求的资源已经未修改，可以使用缓存的版本。这通常用于 GET 请求中。

以下是一个示例代码：

HTTP/1.1 304 Not Modified
Date: Tue, 20 Aug 2019 08:59:58 GMT

4xx 状态码

4xx 状态码是由客户端发起的错误或无法完成请求时返回的响应。以下是其中一些常见的状态码：

400 Bad Request

400 Bad Request 响应状态码表示服务器无法理解客户端所发出的请求，通常是由于客户端发送了不正确的数据。

以下是一个示例代码：

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "message": "Invalid parameter values",
    "details": {
        "post_id": "Post ID should be an integer value."
    }
}

401 Unauthorized

401 Unauthorized 响应状态码表示客户端未被授权以访问所请求的资源。这通常发生在需要验证的 RESTful API 中。

以下是一个示例代码：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Restricted area"

404 Not Found

404 Not Found 响应状态码表示所请求的资源不存在。

以下是一个示例代码：

HTTP/1.1 404 Not Found
Content-Type: application/json
{
    "message": "Item not found.",
    "details": {}
}

5xx 状态码

5xx 状态码表示服务器错误。以下是其中两个常见的状态码：

500 Internal Server Error

500 Internal Server Error 响应状态码表示服务器遇到了无法处理的错误，通常是由于服务器故障或代码错误。

以下是一个示例代码：

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
    "message": "An unexpected error occurred.",
    "details": {}
}

502 Bad Gateway

502 Bad Gateway 响应状态码表示服务器作为网关或代理，无法从上一级服务器收到有效响应。

以下是一个示例代码：

HTTP/1.1 502 Bad Gateway
Content-Type: application/json
{
    "message": "Unable to contact upstream server.",
    "details": {}
}

总结

RESTful API 中正确使用 HTTP 状态码可以提供对 API 请求处理结果的详细描述，帮助客户端更好地理解响应信息。重要的是要选择正确的状态码类别，以便尽可能地准确地描述每个请求和响应。

本文已经介绍了常见的 HTTP 状态码以及如何在 RESTful API 中使用它们。我们希望这篇文章对您有所帮助，并能在应用程序设计和开发中提供指导和参考。

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