选择一个 HTTP 状态码不再是一件难事

有什么能比 HTTP 响应状态码更简单呢？页面渲染了吗？好极了，返回 200。页面不存在？那么是 404。想要跳转到另一个页面？302 或者可能是 301。

我喜欢把 HTTP 状态码想象成无线电波传输的 10 码 ¹。“呼叫，呼叫，我是 White Chocolate Thunder，发现 200 OK。”

—— Aaron Patterson (@tenderlove) 2015-10-7

生活是美好的…… 直到有人告诉你，你还没有做这个 REST²。然后你该失眠了，因为你需了解是否你的新资源返回符合 RFC 规范 ³，Roy-Fielding 规定的状态码。这里只有 200 吗？或者为什么没有 204 No Content？或许有 202 Accepted…… 或者有 201 Created？

使事情复杂化的是，官方的 HTTP/1.1 指南 —— RFC —— 是写于 1997 年的。† 在那一年，人们还在使用 Netscape 浏览器以 33.6 KB 的调制解调器来上网。在现在用 HTTP/1.1 就有点像把孙子兵法运用于现代企业战略，兵法无疑是伟大的，但我根本不知道如何具体运用。

能不能有一种直观的决策树来让你快速确定你要用到的少数状态码，并将那些不相关的和废弃的状态码排除掉？

当然可以，现在就能给你一个。

从何说起

它可能看起来很可笑，但是我曾经看到过太多人分不清这些，“这里应该用 503 Service Unavaliable 还是 404 Not Found？” 如果你曾经在这上面犹豫，那么你完全弄混了不同的响应类型，你的做法完全是错的。你应该回头看看上面这张流程图。

在深入到具体规范的流程图之前，有一些注意事项：

• 我建议你阅读 RFC 7231 和 httpstatuses.com
• 以下内容对开发网站和设计 RESTish API 有用。
  • 状态码对具体的 web server 实现是完全透明的
  • 当然这里完全忽略代理服务器
• 我将响应状态码粗略地归为三类：

最后但同样重要的，免责声明：我不保证我写的完全正确，我只是读了一些 RFC 文档在 Racksurg 公司实际工作时，每天用它来实现有用的 API。如果你认为我是错的或者我轻视了你最喜欢的状态码，那可能是我的失误，你可以通过评论告知我究竟错在哪里。

2XX/3XX

4XX

5XX

结语：究竟为什么状态码重要

我并不完全确定它们真的重要。

Facebook 上有许多聪明人，他们创建了 API 只返回 200。

反对挑选指定状态码的基本观点是：现有的状态码对于现代网站 / API 来说太通用了。它无法让客户端以任何一种有意义的方式处理包含特定应用格式的细节的返回信息 —— 例如表单的哪一个字段校验失败了以及为什么失败了。既然如此，那么为什么要在多余的没什么用的 HTTP 状态码上浪费时间？

如果要给出一个理由，来说明为什么使用特定的状态码很重要，公认的理由是 HTTP 是一个分层的系统，如果响应状态码是有特定含义的，任何代理、缓存或者位于客户端和服务器之间的 HTTP 框架能够更好地工作。我不认为这个理由足够更令人信服，尤其现在每个人都开始将服务迁移到 HTTPS，我们禁止了任何不被服务器直接控制的代理或缓存节点。

然而，我会给你三个理由为什么我认为状态码仍然很重要：

1. 客户端已经处理（或者可以方便地被扩展以便处理）具有特定行为的不同状态码：
   • 相比于 302 Found，301 Moved Permanently 在 Google 等搜索引擎上有更好的 SEO 效果。
   • 301 Moved Permanently 能够被缓存，而 429 Too Many Requests 不被缓存等等。 有的客户端库可以处理 429 Too Many Request，将请求回退并一天之后再次尝试请求。 有的客户端可以用同样的方式处理 503 Service Unavilable。
2. 即使对现代需求不能完全满足，许多状态码依然代表着值得处理的特定响应（因此为什么不直接使用标准状态码？）。
   • 那些本该返回 405 Method Not Allowed 却返回 404 的 API 让我疯狂地想，“究竟我是敲错了 URL 还是用错误的 HTTP method 请求了服务？”
   • 我能告诉你如果我们返回 502 Bad Gateway（上游服务问题）而不是返回让人困惑的 500 Internal Server Error，那么我们曾经能节省许多调试问题的时间。
3. 不管你信不信，反正我是信了，在广泛被使用的 API 中正在建立一个约定，以返回状态码例如 201 Created，429 Too Many Requests 以及 503 Service Unavialable。如果你遵循这个约定，用户将能更方便地使用你的网站 / API 并且解决任何他们可能遇到的问题。

在这里面，决定什么时候返回何种状态码是最难的，然而有了正确的知识（别再说我不知道，仔细看前面的流程图），挑选一个有意义的状态码变得简单很多。

说明

别去研究 RFC 2616，更别去研究 RFC 2068，真正有用的是 RFC 7231。

参考资料

• HTTP status code reference
• HTTP status codes used by world-famous APIs
• HTTP status codes visualized as a subway map
• Status Codes To Cat Memes As a Service
• Status Codes To Dog Memes As a Service
• 注 ¹：10 码，又称十个信号，用来表示常用的短语，在语音通信，特别是执法和公民波段（CB）无线电传输码字。
• 注 ²：表述性状态转移：REST
• 注 ³：Request For Comments（RFC），是一系列以编号排定的文件。文件收集了有关互联网相关信息，以及 UNIX 和互联网社区的软件文件。目前 RFC 文件是由 Internet Society（ISOC）赞助发行。基本的互联网通信协议都有在 RFC 文件内详细说明。RFC 文件还额外加入许多的论题在标准内，例如对于互联网新开发的协议及发展中所有的记录。因此几乎所有的互联网标准都有收录在 RFC 文件之中。