API 设计中 HTTP 状态代码的终极参考

发布于2024-11-17

The Ultimate Reference for HTTP Status Codes in API Design

在 Web 开发和 API 设计领域，HTTP 状态代码在客户端和服务器之间传达请求结果方面发挥着至关重要的作用。这些代码提供了一种标准化的方式来指示在处理 HTTP 请求期间发生的特定条件、成功或错误。了解这些状态代码对于开发人员至关重要，因为它有助于调试、错误处理和创建更强大的应用程序。

1. 1xx 信息

这些状态代码表示临时响应。它们在实践中很少使用，但在某些情况下可能会有所帮助。

100 Continue：服务器已收到请求标头，客户端应继续发送请求正文。
101 Switching Protocols：请求者要求服务器切换协议并且服务器已同意这样做。

2. 2xx 成功

这些状态代码表明客户端的请求已成功接收、理解并接受。

200 OK：请求成功，响应中包含请求的数据或结果。
- 示例：检索用户的个人资料信息。
201 Created：请求成功，创建了新资源。
- 示例：创建新用户帐户或发布新博客条目。
204 No Content：服务器成功处理请求，但没有返回任何内容。
- 示例：更新不需要响应正文的用户设置。
206 部分内容：由于客户端发送的范围标头，服务器仅传送部分资源。
- 示例：流式传输视频内容或分块下载大文件。

3. 3xx重定向

这些状态代码表明用户代理需要采取进一步的操作来满足请求。

301 Moved Permanently：请求的资源已永久移动到新的URL。
302 Found：请求的资源暂时驻留在不同的 URL 下。
304 Not Modified：表示资源自请求头指定的版本以来尚未被修改。

4. 4xx客户端错误

这些状态代码适用于客户端似乎犯了错误的情况。

400 Bad Request：由于语法无效或输入错误，服务器无法处理请求。
- 示例：在请求正文中发送格式错误的 JSON。
- 用法：当请求本身格式错误或包含无效参数时使用。
401 Unauthorized：请求需要用户认证。
- 示例：尝试在不提供有效凭据的情况下访问受保护的 API 端点。
- 用途：需要身份验证且未提供或无效时使用。
403 Forbidden：服务器理解请求，但拒绝授权。
- 示例：用户尝试访问仅限管理员的功能。
- 用法：当用户通过身份验证但无权执行请求的操作时使用。
404 Not Found：在服务器上找不到请求的资源。
- 示例：尝试检索已删除的用户配置文件。
- 用法：当请求的资源不存在时使用。
405 Method Not allowed：请求 URI 标识的资源不允许使用请求中指定的方法。
- 示例：向仅接受 GET 请求的端点发送 POST 请求。
409 冲突：由于与资源的当前状态冲突，无法处理请求。
- 示例：尝试使用系统中已存在的电子邮件创建用户。
- 用法：与资源当前状态存在冲突时使用，例如重复条目。
422 Unprocessable Entity：服务器理解请求的内容类型和语法，但无法处理其中包含的指令。
- 示例：提交包含无效数据的表单，导致服务器端验证失败。
- 用法：用于请求语法正确但数据语义不正确的验证错误。
429 Too Many Requests：用户在给定时间内发送了太多请求（“速率限制”）。
- 示例：实施 API 速率限制以防止滥用。