开发者必备：HTTP 状态码速查手册

开发者必备：HTTP 状态码速查手册 - 深入理解 Web 通信的基石

在现代软件开发中，无论是构建 Web 应用、移动 App 后端、微服务还是调用第三方 API，HTTP（超文本传输协议）都扮演着至关重要的角色。它是 Web 数据交换的基础，而理解 HTTP 协议的核心部分之一，就是掌握 HTTP 状态码。这些三位数的代码是服务器对客户端请求的响应，告知请求处理的结果。它们不仅仅是简单的数字，更是调试问题、优化性能、设计健壮 API 的关键线索。

对于开发者而言，熟悉 HTTP 状态码的含义和应用场景，如同掌握了一门 Web 通信的“语言”。它能帮助我们快速定位问题是出在客户端、服务器还是网络层面，能指导我们设计出更符合 RESTful 规范的 API，也能让我们更好地理解浏览器、缓存、代理服务器等中间件的行为。

本手册旨在提供一份详尽的 HTTP 状态码参考，不仅涵盖常用代码，也包括一些不那么常见但同样重要的状态码，并深入探讨其含义、使用场景及对开发者的意义，助你成为更专业的 Web 开发者。

HTTP 状态码的分类

HTTP 状态码被设计为五大类，通过首位数字进行区分，这种分类方式极大地帮助了我们理解响应的大致性质：

• 1xx (Informational - 信息性状态码): 表示请求已被接收，继续处理。这类状态码比较少见，通常用于协议层面的交互。
• 2xx (Successful - 成功状态码): 表示请求已成功被服务器接收、理解、并接受。这是我们最期望看到的状态码。
• 3xx (Redirection - 重定向状态码): 表示要完成请求，需要进一步操作。通常用来指示客户端需要访问另一个 URI。
• 4xx (Client Error - 客户端错误状态码): 表示客户端看起来似乎发生了错误，阻碍了服务器的处理。例如，请求语法错误、资源未找到、未授权等。
• 5xx (Server Error - 服务器错误状态码): 表示服务器在处理一个看似有效的请求时发生了内部错误。这通常意味着服务器端代码或配置存在问题。

接下来，我们将深入探讨每一类中的重要状态码。

1xx 信息性响应 (Informational Responses)

这类状态码表示服务器收到了请求的初始部分，客户端应继续发送剩余部分，或者如果请求已经完成，则忽略这个响应。它们在常规 Web 浏览或 API 调用中并不常见，更多是在协议协商阶段使用。

• 100 Continue: 服务器已收到请求头，并且客户端应继续发送请求体（例如，在 POST 请求中）。客户端在发送包含较大请求体的请求前，可以先发送一个包含 Expect: 100-continue 头部的请求，服务器若返回 100，则客户端继续发送；若返回 417 (Expectation Failed)，则表示无法满足期望。这可以避免因服务器不接受请求而浪费带宽传输大数据。
• 101 Switching Protocols: 服务器根据客户端的 Upgrade 请求头，同意切换协议。例如，从 HTTP/1.1 升级到 WebSocket 或 HTTP/2。开发者在使用 WebSocket 时可能会间接遇到此状态码。

2xx 成功响应 (Successful Responses)

这是开发者最乐于见到的状态码类别，表明客户端的请求被成功处理。

• 200 OK: 最常见的成功状态码。表示请求已成功。响应的含义取决于请求方法：
  • GET: 资源已获取，并在响应体中发送。
  • HEAD: 实体头已在响应头中发送，无响应体。
  • POST: 操作成功，响应体中可能包含操作结果。
  • PUT/DELETE: 操作成功，响应体中可能包含状态信息。
  • TRACE: 服务器收到了请求消息，响应体包含请求消息本身。
• 201 Created: 请求成功，并且服务器创建了新的资源。通常在 POST 或 PUT 请求成功创建资源后返回。响应头中通常包含一个 Location 字段，指向新创建资源的 URI。这是设计 RESTful API 时创建资源的标准响应。
  • 开发者注意： 务必在响应头中提供 Location，告知客户端新资源的位置。
• 202 Accepted: 服务器已接受请求，但尚未完成处理。该请求最终可能会或可能不会被执行，并且在处理发生时是异步的。适用于需要长时间处理的操作，如批处理任务、发送邮件等。服务器可以告知客户端一个监控处理状态的链接。
  • 开发者注意： 这并不保证最终成功，需要提供机制让客户端查询状态或接收后续通知。
• 204 No Content: 服务器成功处理了请求，但没有返回任何内容（响应体为空）。通常用于 PUT（更新资源成功，无需返回内容）或 DELETE（删除资源成功）操作。浏览器在收到 204 响应后，通常不会更新页面。
  • 开发者注意： 确保响应体确实为空。对于需要确认信息的场景，可能 200 OK 更合适。
• 206 Partial Content: 服务器成功处理了客户端的范围请求（通过 Range 请求头指定），只返回了资源的一部分。常用于大文件下载（断点续传）和视频流。响应头中必须包含 Content-Range 来指示返回的数据范围。
  • 开发者注意： 实现范围请求支持时，需要精确处理 Range 请求头和 Content-Range 响应头。

3xx 重定向消息 (Redirection Messages)

这类状态码告诉客户端，需要采取进一步的操作才能完成请求，通常是需要访问另一个 URL。

• 301 Moved Permanently: 请求的资源已被永久移动到新的 URI。响应头中的 Location 字段会指明新的地址。搜索引擎会根据 301 更新其索引。浏览器通常会缓存这个重定向。
  • 开发者注意： 用于网站改版、URL 结构调整等永久性变更。务必提供正确的 Location。滥用可能影响 SEO。
• 302 Found (Previously "Moved Temporarily"): 请求的资源临时位于不同的 URI。客户端应继续使用原有 URI 进行后续请求。Location 头指示临时位置。与 301 不同，搜索引擎不会更新索引。
  • 开发者注意： 历史上，很多客户端会错误地将后续对 302 的请求方法改为 GET（即使原始请求是 POST）。因此，产生了 303 和 307。现在仍广泛用于临时的页面跳转，如登录后跳转回原页面。
• 303 See Other: 服务器要求客户端使用 GET 方法访问另一个 URI 来获取请求结果。通常在处理 POST 请求后，为了防止用户刷新页面导致重复提交，服务器会返回 303，将用户重定向到一个表示结果的页面。
  • 开发者注意： 明确表示后续请求必须是 GET，解决了 302 的歧义。是 POST-Redirect-GET (PRG) 模式的标准实践。
• 304 Not Modified: 客户端发送了一个条件性 GET 请求（通常带有 If-Modified-Since 或 If-None-Match 请求头），但资源自上次请求以来没有发生变化。服务器告知客户端可以直接使用其本地缓存的版本。响应体必须为空。
  • 开发者注意： 这是实现高效 HTTP 缓存的关键。正确配置资源的 Last-Modified 和 ETag 响应头，并处理客户端的条件请求头，可以极大节省带宽和服务器资源。
• 307 Temporary Redirect: 类似于 302，但要求客户端在重定向时不得改变原始请求的方法。如果原始请求是 POST，重定向后的请求也必须是 POST。
  • 开发者注意： 如果需要临时重定向且保持请求方法不变（特别是对于非 GET/HEAD 方法），应使用 307 而不是 302。
• 308 Permanent Redirect: 类似于 301，但要求客户端在重定向时不得改变原始请求的方法。如果原始请求是 POST，重定向后的请求也必须是 POST。
  • 开发者注意： 如果需要永久重定向且保持请求方法不变，应使用 308 而不是 301。

4xx 客户端错误响应 (Client Error Responses)

这类状态码表示客户端似乎发送了一个错误的请求，服务器无法或不会处理该请求。开发者在调试前端或 API 调用问题时会频繁遇到。

• 400 Bad Request: 最通用的客户端错误状态码。表示服务器无法理解客户端的请求，通常因为请求语法错误、无效的请求消息帧或欺骗性的请求路由。
  • 开发者注意： 这是一个笼统的错误码。如果可能，应尽量使用更具体的 4xx 代码。在 API 设计中，常用于请求参数验证失败，此时应在响应体中提供详细的错误信息。
• 401 Unauthorized: 请求要求身份验证。客户端需要提供有效的凭据（如用户名密码、Token）才能访问资源。响应头中通常包含一个 WWW-Authenticate 字段，告知客户端如何进行认证（例如，Basic, Bearer）。
  • 开发者注意： 这表示“未认证”，而不是“未授权”。用户需要先登录或提供凭证。与 403 不同。
• 403 Forbidden: 服务器理解请求，但拒绝执行。即使提供了身份验证信息，也无权访问该资源。这通常表示权限不足。
  • 开发者注意： 这表示“已认证，但未授权”。用户已登录，但其角色或权限不允许执行该操作。不要在响应体中泄露过多关于为什么被拒绝的敏感信息。
• 404 Not Found: 服务器找不到请求的资源。URL 没有与之匹配的资源。这是 Web 上最常见的错误之一。
  • 开发者注意： 可能是 URL 拼写错误、资源已被删除或从未存在。在 API 中，也可能表示尝试访问一个不存在的对象 ID。提供友好的 404 页面或 API 错误信息很重要。有时也用于隐藏资源存在的事实以增强安全性（相比 403）。
• 405 Method Not Allowed: 服务器知道该资源存在，但请求使用了不被允许的 HTTP 方法。例如，对一个只允许 GET 的资源发送 POST 请求。
  • 开发者注意： 响应头中必须包含一个 Allow 字段，列出该资源支持的方法（如 Allow: GET, HEAD）。
• 406 Not Acceptable: 服务器无法根据客户端请求头中的 Accept 字段（如 Accept, Accept-Charset, Accept-Encoding, Accept-Language）生成一个可接受的响应表示。
  • 开发者注意： 发生在内容协商失败时。例如，客户端只接受 application/json，但服务器只能生成 application/xml。
• 408 Request Timeout: 服务器在等待客户端发送完整请求时超时。这可能是网络问题或客户端配置问题。
  • 开发者注意： 服务器可以决定关闭连接。这不是指服务器处理请求超时（那是 504）。
• 409 Conflict: 请求与服务器当前状态冲突，无法完成。常用于 PUT 请求中，当尝试更新资源的某个版本，而该资源已被其他人修改（版本冲突）。也可能用于尝试创建一个已存在的唯一资源。
  • 开发者注意： 响应体中应包含足够的信息帮助客户端理解冲突的性质并解决它，例如提供资源的当前状态或版本信息。
• 410 Gone: 请求的资源曾经存在，但现在已被永久删除，并且没有转发地址。类似于 404，但更明确地表示资源是永久消失的。客户端应删除对该资源的所有引用。
  • 开发者注意： 比 404 更能清晰地传达资源状态，有助于客户端和搜索引擎进行资源清理。
• 413 Payload Too Large (Formerly "Request Entity Too Large"): 请求体的大小超过了服务器能处理的限制。
  • 开发者注意： 服务器可以关闭连接或在响应头中包含 Retry-After 字段建议客户端稍后重试（如果过载是暂时的）。需要检查服务器配置（如 Nginx 的 client_max_body_size）。
• 415 Unsupported Media Type: 服务器无法处理请求附带的媒体类型（由 Content-Type 请求头指定）。例如，API 期望 application/json，但客户端发送了 application/xml。
  • 开发者注意： 检查客户端发送的 Content-Type 是否正确，以及服务器端是否配置为支持该类型。
• 422 Unprocessable Entity: 请求格式正确（语法没问题），但由于包含语义错误，服务器无法处理。常用于 WebDAV，但也广泛用于 REST API 中表示数据验证失败。例如，POST 请求的 JSON 结构有效，但其中的某个字段值不符合业务规则（如邮箱格式错误、密码太短）。
  • 开发者注意： 这是比 400 更具体的验证错误码。强烈建议在响应体中提供详细的字段级错误信息，方便客户端修正。
• 429 Too Many Requests: 用户在给定的时间内发送了太多的请求（触发了速率限制）。
  • 开发者注意： 用于保护服务器资源，防止滥用。响应头中可以包含 Retry-After 字段，告知客户端需要等待多久才能再次尝试。

5xx 服务器错误响应 (Server Error Responses)

这类状态码表示服务器在处理请求的过程中遇到了错误，导致无法完成请求。问题出在服务器端。

• 500 Internal Server Error: 最通用的服务器错误状态码。表示服务器遇到了一个未曾预料的状况，导致其无法完成请求。这是一个非常笼统的错误，通常表示服务器代码中存在 bug、配置错误或运行时异常。
  • 开发者注意： 这是开发者最不希望暴露给用户的错误，但又是调试的起点。绝对不能在响应体中向最终用户显示详细的错误堆栈或敏感信息。应记录详细的服务器端日志以供排查。提供一个通用的、友好的错误页面或消息。
• 501 Not Implemented: 服务器不支持完成请求所需的功能。例如，服务器无法识别请求方法（不是 HTTP 标准方法）或没有能力执行该请求。
  • 开发者注意： 通常意味着服务器软件需要更新或配置，或者客户端请求了尚在开发中的功能。
• 502 Bad Gateway: 服务器作为网关或代理，从上游服务器（如应用服务器）收到了无效的响应。
  • 开发者注意： 问题通常不在于 Web 服务器（如 Nginx, Apache）本身，而在于其后面运行的应用（如 PHP, Node.js, Java 应用）。需要检查应用服务器的日志和状态。可能是应用崩溃、超时或返回了格式错误的响应。
• 503 Service Unavailable: 服务器当前无法处理请求，通常是由于暂时过载或正在进行维护。这是一个临时状态。
  • 开发者注意： 这是一个对用户相对友好的错误，因为它暗示问题是暂时的。可以在响应头中包含 Retry-After 字段，建议客户端何时可以重试。常用于部署、重启服务或流量高峰期。
• 504 Gateway Timeout: 服务器作为网关或代理，未能及时从上游服务器获得响应。
  • 开发者注意： 与 502 类似，问题源于上游服务器。但这特指上游服务器响应超时。可能是应用处理请求时间过长，或者网络连接问题。需要检查应用性能、数据库查询、外部 API 调用等耗时操作。

状态码使用的最佳实践与总结

1. 语义准确性: 选择最能精确反映请求处理结果的状态码。避免滥用通用代码（如用 400 代替所有客户端错误，用 500 代替所有服务器错误）。
2. 提供上下文信息: 特别是对于 4xx 和 5xx 错误，响应体应包含有用的错误信息（对开发者友好，对最终用户安全），帮助诊断问题。对于 API，可以遵循如 RFC 7807 (Problem Details for HTTP APIs) 的标准格式。
3. 区分 4xx 和 5xx: 清晰地区分是客户端问题还是服务器问题，这是快速定位故障的关键。
4. 善用 2xx: 不要只满足于 200 OK。使用 201 Created, 202 Accepted, 204 No Content 等可以更精确地表达成功状态。
5. 理解重定向: 正确使用 301, 302, 303, 307, 308 对 SEO、用户体验和应用逻辑至关重要。理解永久与临时、方法保持与否的区别。
6. 缓存控制: 结合 304 Not Modified 与 ETag, Last-Modified, Cache-Control 等头部，实现高效的 HTTP 缓存策略。
7. 日志记录: 在服务器端详尽记录请求和响应（包括状态码），尤其对于 5xx 错误，日志是排查问题的生命线。
8. 监控: 监控应用和 API 的状态码分布，特别是 4xx 和 5xx 的激增，可以及时发现问题。

结语:

HTTP 状态码是 Web 架构的基石之一，它们是客户端与服务器之间简洁而强大的沟通语言。深入理解每个状态码的精确含义、适用场景以及潜在影响，是每一位开发者提升技能、构建高质量 Web 应用和服务的必经之路。本手册旨在为你提供一个全面而实用的参考，希望它能伴随你的开发旅程，助你更从容地应对 Web 开发中的各种挑战，更高效地进行调试和设计。记住，每一次与状态码的“邂逅”，都是一次理解 Web 运作机制的宝贵机会。不断学习，不断实践，你将更加精通这门 Web 通信的艺术。