这只是一个 200 OK 呀？不，也许是 202 Accepted……还是说其实是 201 Created？还是应该用 204 No Content 呢？为什么这感觉像哲学辩论，而不是在讨论状态码？
一转眼，你自信地返回了一个 404 Not Found 状态，却发现原来是 403 Forbidden。紧接着，你盯着错误日志，犯起愁来，疑惑这到底是 503 Service Unavailable 问题，还是你的理智一点点耗尽。
选择我的后端 REST API 的 HTTP 状态码总是有点棘手。我仔细阅读了 RFC 7231 和 httpstatuses.com，被众多的状态码选项所困扰。在这篇文章中，我打算提供一个何时使用每种状态码的详细指南。
此处省略内容
HTTP状态码在web API的客户端和服务器之间通信中至关重要。它们提供了一个快速了解请求结果的方式，帮助工程师诊断问题并优化用户体验。这些状态码被分为五组。
- 1xx（信息性）： 请求已接收，正在处理中。
- 2xx（成功）： 请求已成功接收、理解并接受。
- 3xx（重定向）： 需要进一步操作来完成请求。
- 4xx（客户端错误）： 请求有误。
- 5xx（服务器错误）： 服务器无法完成有效请求。
指南此处省略内容
1xx: 信息回复:注：若“1xx”为专用术语，请在文档中保持一致或在脚注中解释。
这些代码表示在请求处理过程中的临时响应，例如100-199。
| 代码 | 标题 | 使用场景 |
|---|---|---|
| 100 | 请继续 | 当客户端应继续发送剩余内容时使用。 |
| 101 | 切换协议 | 当客户端请求更改协议（例如，从 HTTP/1.1 更改为 HTTP/2），并且服务器同意时使用。 |
| 102 | 正在处理（WebDAV） | 当服务器仍在处理请求但尚未准备好最终响应时使用。 |
| 103 | 早期提示信息 | 与 Link 头一起使用时，指示客户端在服务器准备最终响应的过程中开始预加载资源。 |
最佳实践:
- 对于大型负载（例如文件上传），如果头信息无效，可以使用 100 Continue 状态码来避免传输不必要的数据。
- 保留 1xx 状态码用于特殊场景；大多数 API 实际上不需要它们。
……
2xx: 成功的回应这些状态码表明请求已被成功接收、解析并处理完毕。
=常见成功回应
| 代码 | 标题 | 使用场景 |
|---|---|---|
| 200 | OK | 当请求成功时使用。这是标准的HTTP请求成功的响应。 |
| 201 | Created | 当请求已被处理且一个或多个新资源已被创建时使用（例如，在成功POST请求后）。 |
| 202 | Accepted | 当请求已被接受处理，但处理尚未完成时使用。 |
| 203 | 非权威信息 | 当返回的元数据不是从源服务器而来，而是来自本地或第三方副本时使用。 |
| 204 | 无内容 | 当服务器成功处理请求但不需要返回任何内容时使用（例如，成功的DELETE请求）。 |
| 205 | 重置内容 | 当请求成功且客户端需要重置文档视图时使用（例如，在提交表单后清空表单）。 |
| 206 | 部分内容 | 当响应带有Range头的请求时使用，通常是返回资源的一部分。 |
| 207 | 多状态（WebDAV） | 当需要对多个操作分别报告状态时使用（在WebDAV中常见）。 |
| 208 | 已报告（WebDAV） | 当DAV绑定的成员已在之前的响应中列出，以避免重复时使用。 |
| 226 | 已使用实例（与HTTP Delta 编码相关） | 当服务器已完成请求且响应是实例操作的结果时使用。 |
最佳实践:
- 优先选择特定代码（201，204）而不是通用的200响应代码。
- 对于202，，提供检查异步任务状态的方法（例如，一个可轮询的端点）。
(Note: There is a double comma in the second sentence, which seems to be an artifact of the expert suggestion to add a comma after "对于202". It might be a typographical error in the instructions and could be adjusted based on the final decision on readability and correctness.)
……
3xx: 重定向响应这些代码显示用户还需要做额外的事情来完成这个请求。
| 代码 | 标题 | 使用场景 / 场景 |
|---|---|---|
| 300 | 多种选择 | 当资源有多种选择，客户端（或用户代理软件）可以选择其中一个时使用。 |
| 301 | 永久移动 | 当资源已永久移动到新的 URI 时使用。所有未来的请求都应指向新的 URI。 |
| 302 | 临时重定向 | 当资源暂时位于另一个 URI 时使用。（原为“临时移动”）。 |
| 303 | 查看其他 | 当请求资源位于不同的 URI 下，并且客户端应使用 GET 方法获取资源时使用。 |
| 304 | 未修改 | 当请求的资源从上一次请求以来没有更改时使用（通常与缓存机制一起使用）。 |
| 305 | 使用代理（已废弃） | 已废弃： 不推荐使用。 它表示应使用代理来访问资源。 |
| 306 | 切换代理 | 预留： 不再使用。 |
| 307 | 临时重定向 | 当资源暂时位于另一个 URI 时使用；客户端应使用相同的方法对原始 URI 进行未来的请求。 |
| 308 | 永久重定向 | 当资源已永久移动时使用，类似于 301 状态，但重新请求新 URI 时请求方法和内容体不会改变。 |
最佳做法:
- 用 301/308 进行永久重定向，用 302/307 进行临时重定向。
-
利用 304 通过缓存减少带宽。
-
- *
这些代码意味着客户端发送了一个无效的请求。
| 代码 | 标题 | 使用场景 / 场景 |
|---|---|---|
| 400 | 错误请求 | 当服务器因客户端错误（如请求语法错误）无法处理请求时使用。 |
| 401 | 未授权 | 当需要认证但认证失败或未提供认证信息时使用。（不同于403，客户端可以尝试重新认证。） |
| 402 | 需要支付 | 保留： 不常使用；最初打算用于未来与数字支付系统相关的目的。 |
| 403 | 禁止 | 当请求被理解但服务器拒绝授权（即使已提供认证信息）时使用。 |
| 404 | 未找到 | 当请求的资源在服务器上无法找到时使用。 |
| 405 | 方法不允许 | 当请求方法不受资源支持时使用（例如，向只读资源发送DELETE请求）。 |
| 406 | 不可接受 | 当请求的资源只能生成不符合请求中Accept头信息格式的内容时使用。 |
| 407 | 代理认证要求 | 当客户端必须先通过代理认证才能继续请求时使用。 |
| 408 | 请求超时 | 当服务器等待客户端请求超时后使用。 |
| 409 | 冲突 | 当请求因冲突（如同时更新导致编辑冲突）无法处理时使用。 |
| 410 | 消失 | 当请求的资源不再可用且不会再次可用时使用。 |
| 411 | 需要长度 | 当服务器需要请求指定Content-Length头但是该头缺失时使用。 |
| 412 | 前提失败 | 当请求中使用If-Match等头信息的一个前提条件未被服务器满足时使用。 |
| 413 | 实体过大 | 当请求实体过大超过服务器愿意或能够处理的大小时使用。 |
| 414 | URI过长 | 当提供的URI过长导致无法处理时使用。 |
| 415 | 不支持的媒体类型 | 当请求实体的媒体类型不被服务器或资源支持时使用。 |
| 416 | 范围不可满足 | 当客户端请求文件的一部分（使用Range头），但服务器无法提供该部分时使用。 |
| 417 | 期望失败 | 当服务器无法满足请求中的Expect请求头字段要求时使用。 |
| 418 | 我是一个茶壶 | 幽默 / 恶作剧： 原本定义在RFC 2324中，不期望在实际HTTP服务器中实现。 |
| 421 | 请求错误定位 | 当请求被发送到无法产生响应的服务器（例如，方案和权威组合不当）时使用。 |
| 422 | 实体处理不可行（WebDAV） | 当请求格式正确但因语义错误而无法继续执行时使用（常用于WebDAV）。 |
| 423 | 已锁定（WebDAV） | 当访问的资源被锁定，阻止进一步操作时使用。 |
| 424 | 依赖失败（WebDAV） | 当请求由于之前请求的失败（例如，依赖的操作失败）而失败时使用。 |
| 425 | 过早 | 当服务器不愿处理可能被重放的请求时实验性使用。（未广泛用于生产环境中。） |
| 426 | 升级需要 | 当客户端应切换到不同的协议（通常是因为需要安全通信）时使用。 |
| 428 | 需要前提 | 当服务器需要请求有条件（通常通过添加If-Match等头信息）时使用。 |
| 429 | 请求过多 | 当用户在给定时间段内发送了过多请求（“速率限制”）时使用。 |
| 431 | 请求头字段过大 | 当请求头字段过大导致无法处理时使用。 |
| 451 | 法律原因不可用 | 当因法律原因（如政府审查）无法提供请求资源时使用。 |
最佳实践:
- 避免使用模糊的400错误；尽可能使用具体的错误代码，比如404和429，以使表达更加流畅。
- 返回401用于认证失败，返回403用于授权问题。
-
在响应体中提供可操作的错误信息（例如，
{ "error": "无效的API密钥" }）。 -
- *
这些代码表示服务器未能处理请求。
注：500-599 是服务器错误的代码范围，通常表示服务器遇到了难以处理的错误。
| 代码 | 标题 | 使用场景 / 场景描述 |
|---|---|---|
| 500 | 内部服务器错误 | 当没有更具体的消息合适时，用作通用错误消息。表示服务器上出现了意外的条件。 |
| 501 | 尚未实现 | 当服务器不支持请求方法或无法处理请求时使用。 |
| 502 | 网关接收到无效响应 | 当一个作为网关或代理的服务器从上游服务器接收到无效响应时使用。 |
| 503 | 服务暂时无法服务 | 当服务器由于过载或维护而暂时无法服务时使用。这通常是暂时的。 |
| 504 | 网关超时 | 当一个作为网关或代理的服务器没有从上游服务器及时接收到响应时使用。 |
| 505 | 不支持的HTTP协议版本 | 当服务器不支持请求中使用的HTTP协议版本时使用。 |
| 506 | 变体也协商 | 当透明内容协商导致循环引用时使用此状态码。（在典型的应用程序中很少遇到。） |
| 507 | 存储不足（WebDAV） | 当服务器无法存储完成请求所需的表示（这种情况主要出现在WebDAV环境中）时使用。 |
| 508 | 检测到循环（WebDAV） | 当服务器在处理请求时检测到无限循环（通常在复杂的WebDAV操作中出现）时使用。 |
| 510 | 未扩展请求 | 当服务器需要进一步扩展请求才能完成时使用。 |
| 511 | 需要网络认证 | 当客户端需要进行网络认证以获取网络访问权限（常见于公共Wi-Fi网络中的网关场景）时使用。 |
最佳实践:
- 避免在开发时遇到 5xx 错误；这些错误表明应用程序出现了未处理的异常。
- 使用 503 状态码表示计划中的停机时间，并确保包含
Retry-After标头。 -
记录 5xx 错误以进行调试，但要对响应中的敏感信息进行屏蔽。
-
- *
希望现在在设计我的API时或处理HTTP响应时，我能根据情况选择最合适的状态码。
希望上面的文章也能给你带来更清晰的理解。掌握这些代码不仅提高了API的稳定性，还提升了每个人在开发过程中的体验。 🚀
*[Object-Oriented]: OO
共同學習，寫下你的評論
評論加載中...
作者其他優質文章
