RESTful API 最佳实践：正确使用 HTTP 状态码-JavaScript中文网-JavaScript教程资源分享门户

RESTful API 是一种基于 HTTP 协议的 API 设计风格，它通过 URL 和 HTTP 方法来对资源进行操作，被广泛应用于 Web 开发和移动应用开发中。HTTP 状态码是 RESTful API 中非常重要的一部分，它用于表示服务器响应的状态和结果，正确使用 HTTP 状态码可以提高 API 的可读性、可维护性和可靠性。

本文将介绍 RESTful API 中常用的 HTTP 状态码及其含义，以及如何在实际开发中正确使用 HTTP 状态码。

HTTP 状态码的分类

HTTP 状态码由 3 位数字组成，分为 5 类，每一类代表一种不同的状态。具体分类如下：

1xx（信息类）：表示接收到请求并且正在处理中。
2xx（成功类）：表示请求已经被成功接收、理解、并处理。
3xx（重定向类）：表示需要客户端采取进一步的操作才能完成请求。
4xx（客户端错误类）：表示客户端发送的请求有错误，服务器无法处理。
5xx（服务器错误类）：表示服务器在处理请求时发生了错误。

常用的 HTTP 状态码

成功类状态码

200 OK：表示请求已经被成功处理，返回的是请求的结果。
201 Created：表示请求已经被成功处理，并且在服务器上创建了新的资源。
204 No Content：表示请求已经被成功处理，但是没有返回任何内容。

重定向类状态码

301 Moved Permanently：表示请求的资源已经被永久移动到新的 URL 上。
302 Found：表示请求的资源已经被临时移动到新的 URL 上。
304 Not Modified：表示客户端发送的请求已经包含了所有需要的信息，服务器可以直接使用缓存的数据，无需返回内容。

客户端错误类状态码

400 Bad Request：表示客户端发送的请求有错误，服务器无法处理。
401 Unauthorized：表示客户端需要进行身份验证才能访问请求的资源。
403 Forbidden：表示客户端没有权限访问请求的资源。
404 Not Found：表示请求的资源不存在。
422 Unprocessable Entity：表示客户端发送的请求格式正确，但是服务器无法处理。

服务器错误类状态码

500 Internal Server Error：表示服务器在处理请求时发生了错误。
502 Bad Gateway：表示服务器作为网关或代理，从上游服务器收到无效的响应。
503 Service Unavailable：表示服务器暂时无法处理请求，通常是由于维护或过载。

如何正确使用 HTTP 状态码

在实际开发中，正确使用 HTTP 状态码可以提高 API 的可读性、可维护性和可靠性。下面是一些使用 HTTP 状态码的最佳实践：

返回正确的状态码：API 应该根据请求的结果返回正确的状态码，例如请求成功返回 200，请求被拒绝返回 403。
返回恰当的错误信息：API 应该返回恰当的错误信息，帮助开发者快速定位问题。例如，当请求的资源不存在时，应该返回 404 状态码和错误信息。
避免使用 200 状态码返回错误信息：当发生错误时，API 不应该使用 200 状态码返回错误信息，这会让开发者难以区分成功和失败的请求。
使用标准的状态码：API 应该使用标准的状态码，避免自定义状态码，这样可以增加 API 的可读性和可维护性。
使用状态码和响应体一起传递信息：API 应该使用状态码和响应体一起传递信息，响应体应该包含请求的结果或错误信息，这样可以让开发者更好地理解请求的结果。

下面是一个使用 HTTP 状态码的示例代码：

// javascriptcn.com 代码示例
const express = require('express');
const app = express();

app.get('/user/:id', function (req, res) {
  const userId = req.params.id;
  const user = getUserById(userId);

  if (!user) {
    res.status(404).send('User not found');
  } else {
    res.status(200).json(user);
  }
});

app.post('/user', function (req, res) {
  const newUser = req.body;

  if (!isValidUser(newUser)) {
    res.status(422).send('Invalid user data');
  } else {
    createUser(newUser);
    res.status(201).send('User created successfully');
  }
});

app.listen(3000, function () {
  console.log('Server listening on port 3000');
});

上面的示例代码中，我们使用了不同的状态码来表示不同的请求结果，例如当请求的用户不存在时，我们返回 404 状态码和错误信息；当请求的用户数据无效时，我们返回 422 状态码和错误信息；当创建用户成功时，我们返回 201 状态码和成功信息。

总结

HTTP 状态码是 RESTful API 中非常重要的一部分，正确使用 HTTP 状态码可以提高 API 的可读性、可维护性和可靠性。在实际开发中，我们应该根据请求的结果返回正确的状态码，返回恰当的错误信息，避免使用 200 状态码返回错误信息，使用标准的状态码，使用状态码和响应体一起传递信息。

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/65812706d2f5e1655dc598a2