来源：麦叔编程

作者：麦叔

代码评审会上，气氛有点紧张！

罗老师正在看张三的代码，并指出了一个问题：

你这个API，在用户没登录的情况下，应该返回401，不应该返回200。要遵守HTTP协议的规范。

张三对此不以为然的说：

我们约定了都返回200的，具体的错误信息放在返回的JSON里。我又没有违法，不能为了规范而规范吧。

罗老师竟无言以对。他赶快去查看Facebook，谷歌等业界大亨的做法，可是他们的做法也不统一。到底要不要遵守HTTP Status Code呢？

听我细细道来，本文涵盖：

• HTTP和Rest API的基本知识
• Rest API使用HTTP Status Code的最佳实践
• Rest API的错误处理最佳实践

HTT协议和Restful API

你很可能已经熟悉HTTP和Restful API。不管你是否熟悉，让我们用1分钟的时间来简单回顾一下：

HTTP协议定义了浏览器和网页服务器之间的交互过程。它的核心概念就2个：

• Request - 浏览器要打开一个网页，给服务器发送一个Request，里面包含了网址，参数，及其他信息。
• Response - 服务器返回一Response给浏览器，包括状态码，比如200表示成功，4xx和5xx都表示不同类型的失败，以及网页的具体内容。

有了标准的协议就好办了，任何人都可以开发浏览器出来，只要你写的软件都能遵守这个协议就行。我记得我研究生时候一门课的大作业就是开发一个简易的浏览器。

控制了浏览器，就控制了网络流量，就不怕没钱赚了，所以各大厂商都在努力推广自己的浏览器，就有了IE, Edge，Chrome，FireFox，QQ浏览器，以及360浏览器等。有的浏览器又好用又文明，有的浏览器很流氓，有的浏览器不遵守协议，让开发人员恨得牙根痒痒。

Rest API说白了就是一个网页地址，不过它只返回JSON或者XML格式的数据，而不是HTML网页。

HTTP Status Code

每个HTTP的Response都包含一个Status Code，表示请求的状态，是成功，还是失败，失败的原因是什么等等。

HTTP的Status Code一共有几十个，详细列表可以查看相关标准。但绝大部分人平时只会接触到最常见的少于10个的代码：

有了这套标准，处理请求的程序首先根据状态码判定请求是否成功，然后做相应的处理。

Rest API是否应该遵循HTTP Status Code

Rest API理论上也应该遵守HTTP的规定，根据不同的情况，返回相应的状态码。但理论只是理论，大家对此的认识是不同的。基本上分成了两派：

• 200派：不管对错，一律返回200，在返回的JSON中再具体指明错误的原因。
• 正规派：另外一派坚持使用规范的HTTP状态码。如果是没有登录，就返回401，如果是没权限就返回403。

这两派都有重量级的公司参与，比如FaceBook就是200派，而Google, Twilio等是正规派：

200派的理由很简单：反正我都需要处理返回的JSON，干脆我就把具体状态写在JSON里面，就不用管HTTP的状态码了，都用200好了。你看Facebook这样的大公司都用200了。

而正规派的人的理由就显得略微有点不正规，大部分人说：因为这是规范。Rest API是基于HTTP的，就应该遵守HTTP的状态码。

我是正规派的人，但我也觉得上面的理由有点薄弱。到底有什么好处？在什么情况下有好处？拿点实实在在的好处或者理由来？

首先，这肯定不是一个非黑即白的问题，200派和正规派都是可行的。只要API的提供者和请求者协调好，都不会带来很大的问题。但是我们仍然应该适度遵守HTTP的状态码。实实在在的理由如下：

1. 作为一个开放的API，可能会被不同的消费者使用。为了最大限度的适应不同的消费者，最好的方法就是大家遵守一个业界规范，那就是HTTP的状态码。下面的2点都是举例来证明第1点。
2. 很多JavaScript框架设计上就是基于HTTP协议的，根据不同的状态码做不同的处理，比如下面的JQuery的Ajax请求就可以根据HTTP的状态码执行不同的代码块：$.ajax({
   url: 'https://maishucode.com/page/2',
   type: 'GET',
   success: function(data){
   alert('成功返回'); //返回2xx，执行这个代码块
   },
   error: function(data) {
   alert('出错啦!'); //返回4xx或者5xx，执行这个代码块
   }
   });如果API没有正确的使用HTTP状态码，上面的代码中需要手动解析JSON里面的状态码，再做分支的判断。
3. 为了通用，很多中间系统根据状态码来分析系统的访问数据，比如ELK可以根据HTTP的状态码分析有多少成功的请求，多少失败的请求。如果都统一返回200，那么就没法分析出：有哪些未登录的访问，有哪些未授权的访问，有多少服务器端错误等。但是这里有利也有弊，有些流氓的中间系统会根据状态码劫持网页，比如有些浏览器和路由器就会劫持404网页，显示它自己的广告页。具体做法是：当路由器或者浏览器发现请求返回的是404，它们就会丢掉Response，而显示一个自己的广告网页。这种劫持是非常无耻的行为。404也是服务器返回给请求者的一个消息，网页仍然可能包含重要的内容。再说了，不管什么消息，中间人都不应该劫持。

• 总结一下，我支持使用合理的HTTP状态码的。原因上面已经说了。但是慎用404，因为可能会被众多流氓劫持。但是还有两点:
• 不要滥用HTTP状态码，基本上就用我前面列举出来的那些就够了。
• 使用HTTP状态码后，仍然需要使用和业务相关的状态码。这就是下面要说的。

Rest API的错误处理最佳实践

使用了HTTP状态码以后，让API符合了一定的标准，这很好。但HTTP状态码不能涵盖我们具体的业务场景，我们仍然需要定义和业务场景相对应的错误码。下面我推荐一个错误处理的返回格式，举例如下：

{ "status":403,
   "error": {     
      "code":'40041',      
      "message":"用户缺少访问特工名单权限",     
      "moreInfo":"https://maishucode.com/errors/40041", 
      "traceId":"9527"
     }, 
   "data":{
  }
}

下面是对每个字段的解释：

• status: HTTP状态码，不能为空，必须和HTTP header中的状态码一致。
• code: 具体业务代码，可以为空。这里需要技术人员和业务人员一起定义一套错误代码规则。
• message: 对错误信息的简单解释
• moreInfo: 对错误信息的详细解释的网址。包含错误的详细解释，可能的原因，如何修正等。
• traceId: 通过这个字段可以去日志文件中查找和本次操作相关的日志。
• data: 存放具体的业务数据。

我要说的说完了！虽然这没有绝对的对错，但是符合良好的规范，提供充分的信息给调用用肯定是没错的。你觉得呢？在留言区留下你的意见吧！