HTTP 状态码与 FastAPI 中的 status_code 参数

在 FastAPI 中，status_code 参数用于指定 HTTP 响应的状态码，它可以直接嵌入在路径操作函数的装饰器中，如 @app.get(), @app.post() 等。这种做法使得 API 响应更加清晰、符合标准，且能够根据不同的请求类型和操作结果返回合适的状态码。

HTTP 状态码的分类与作用

HTTP 状态码是三位数的数字，表示服务器处理请求后的响应状态。它们分为五个主要类别：

1. 1xx（信息性状态码）：

   • 用于通知客户端请求正在处理中。这些状态码通常不带响应体，极少会直接由开发者手动设置。

2. 2xx（成功响应）：

   • 200 OK: 表示请求已成功处理。默认的成功状态码。
   • 201 Created: 表示请求成功，并且已经创建了新的资源，通常用于 POST 请求成功创建记录时。
   • 204 No Content: 请求成功处理，但没有返回内容，通常用于 DELETE 请求或某些无返回体的更新操作。

3. 3xx（重定向）：

   • 这些状态码表示请求需要客户端进行进一步操作，如重定向到另一个 URL。最常见的重定向状态码包括 301 Moved Permanently 和 302 Found。在开发中，307 Temporary Redirect 是一个较常见的临时重定向响应。

4. 4xx（客户端错误）：

   • 这些状态码表示客户端提交的请求存在问题。比如，404 Not Found 表示请求的资源未找到，400 Bad Request 表示请求格式错误。开发者通常会使用这些状态码来反馈客户端的错误请求。

5. 5xx（服务器错误）：

   • 这些状态码表示服务器端出现了错误，无法处理请求。例如，500 Internal Server Error 表示服务器发生了不可预知的错误。一般情况下，这些错误是由服务器配置或代码问题引起的，开发者通常无需手动设置。

在 FastAPI 中使用 status_code 参数

FastAPI 提供了 status_code 参数，可以让开发者显式指定每个路径操作的响应状态码。通过这种方式，开发者能够清晰地表达每个 API 操作的结果，并确保符合 HTTP 标准。

• 直接使用数字状态码：可以直接在装饰器中设置如 status_code=201 来返回 201 Created 状态码。
• 使用 FastAPI 内置的状态常量：FastAPI 还提供了 status 模块，里面包含了常见的 HTTP 状态码常量，例如 status.HTTP_201_CREATED，这样可以提高代码的可读性和可维护性，同时也能借助编辑器的自动补全功能。

status_code 的实际应用

通过合理设置 HTTP 状态码，FastAPI 能够使得 API 响应符合 RESTful API 的设计标准。例如，当客户端成功提交数据创建资源时，服务器应返回 201 Created，而当客户端请求的资源无法找到时，则返回 404 Not Found。这种做法不仅提升了接口的语义清晰度，也使得 API 的使用者能够更容易地理解请求和响应的状态。

总的来说，使用 status_code 参数在 FastAPI 中为每个请求设置合适的 HTTP 状态码，可以有效增强 API 的健壮性、标准化以及用户体验。在实际开发中，确保正确使用这些状态码对于维护和扩展 API 至关重要。