來源：麥?zhǔn)寰幊?

作者：麥?zhǔn)?

代碼評(píng)審會(huì)上，氣氛有點(diǎn)緊張！

羅老師正在看張三的代碼，并指出了一個(gè)問題：

你這個(gè)API，在用戶沒登錄的情況下，應(yīng)該返回401，不應(yīng)該返回200。要遵守HTTP協(xié)議的規(guī)范。

張三對(duì)此不以為然的說：

我們約定了都返回200的，具體的錯(cuò)誤信息放在返回的JSON里。我又沒有違法，不能為了規(guī)范而規(guī)范吧。

羅老師竟無言以對(duì)。他趕快去查看Facebook，谷歌等業(yè)界大亨的做法，可是他們的做法也不統(tǒng)一。到底要不要遵守HTTP Status Code呢？

聽我細(xì)細(xì)道來，本文涵蓋：

• HTTP和Rest API的基本知識(shí)
• Rest API使用HTTP Status Code的最佳實(shí)踐
• Rest API的錯(cuò)誤處理最佳實(shí)踐

HTT協(xié)議和Restful API

你很可能已經(jīng)熟悉HTTP和Restful API。不管你是否熟悉，讓我們用1分鐘的時(shí)間來簡(jiǎn)單回顧一下：

HTTP協(xié)議定義了瀏覽器和網(wǎng)頁(yè)服務(wù)器之間的交互過程。它的核心概念就2個(gè)：

• Request - 瀏覽器要打開一個(gè)網(wǎng)頁(yè)，給服務(wù)器發(fā)送一個(gè)Request，里面包含了網(wǎng)址，參數(shù)，及其他信息。
• Response - 服務(wù)器返回一Response給瀏覽器，包括狀態(tài)碼，比如200表示成功，4xx和5xx都表示不同類型的失敗，以及網(wǎng)頁(yè)的具體內(nèi)容。

有了標(biāo)準(zhǔn)的協(xié)議就好辦了，任何人都可以開發(fā)瀏覽器出來，只要你寫的軟件都能遵守這個(gè)協(xié)議就行。我記得我研究生時(shí)候一門課的大作業(yè)就是開發(fā)一個(gè)簡(jiǎn)易的瀏覽器。

控制了瀏覽器，就控制了網(wǎng)絡(luò)流量，就不怕沒錢賺了，所以各大廠商都在努力推廣自己的瀏覽器，就有了IE, Edge，Chrome，F(xiàn)ireFox，QQ瀏覽器，以及360瀏覽器等。有的瀏覽器又好用又文明，有的瀏覽器很流氓，有的瀏覽器不遵守協(xié)議，讓開發(fā)人員恨得牙根癢癢。

Rest API說白了就是一個(gè)網(wǎng)頁(yè)地址，不過它只返回JSON或者XML格式的數(shù)據(jù)，而不是HTML網(wǎng)頁(yè)。

HTTP Status Code

每個(gè)HTTP的Response都包含一個(gè)Status Code，表示請(qǐng)求的狀態(tài)，是成功，還是失敗，失敗的原因是什么等等。

HTTP的Status Code一共有幾十個(gè)，詳細(xì)列表可以查看相關(guān)標(biāo)準(zhǔn)。但絕大部分人平時(shí)只會(huì)接觸到最常見的少于10個(gè)的代碼：

有了這套標(biāo)準(zhǔn)，處理請(qǐng)求的程序首先根據(jù)狀態(tài)碼判定請(qǐng)求是否成功，然后做相應(yīng)的處理。

Rest API是否應(yīng)該遵循HTTP Status Code

Rest API理論上也應(yīng)該遵守HTTP的規(guī)定，根據(jù)不同的情況，返回相應(yīng)的狀態(tài)碼。但理論只是理論，大家對(duì)此的認(rèn)識(shí)是不同的?；旧戏殖闪藘膳桑?

• 200派：不管對(duì)錯(cuò)，一律返回200，在返回的JSON中再具體指明錯(cuò)誤的原因。
• 正規(guī)派：另外一派堅(jiān)持使用規(guī)范的HTTP狀態(tài)碼。如果是沒有登錄，就返回401，如果是沒權(quán)限就返回403。

這兩派都有重量級(jí)的公司參與，比如FaceBook就是200派，而Google, Twilio等是正規(guī)派：

200派的理由很簡(jiǎn)單：反正我都需要處理返回的JSON，干脆我就把具體狀態(tài)寫在JSON里面，就不用管HTTP的狀態(tài)碼了，都用200好了。你看Facebook這樣的大公司都用200了。

而正規(guī)派的人的理由就顯得略微有點(diǎn)不正規(guī)，大部分人說：因?yàn)檫@是規(guī)范。Rest API是基于HTTP的，就應(yīng)該遵守HTTP的狀態(tài)碼。

我是正規(guī)派的人，但我也覺得上面的理由有點(diǎn)薄弱。到底有什么好處？在什么情況下有好處？拿點(diǎn)實(shí)實(shí)在在的好處或者理由來？

首先，這肯定不是一個(gè)非黑即白的問題，200派和正規(guī)派都是可行的。只要API的提供者和請(qǐng)求者協(xié)調(diào)好，都不會(huì)帶來很大的問題。但是我們?nèi)匀粦?yīng)該適度遵守HTTP的狀態(tài)碼。實(shí)實(shí)在在的理由如下：

1. 作為一個(gè)開放的API，可能會(huì)被不同的消費(fèi)者使用。為了最大限度的適應(yīng)不同的消費(fèi)者，最好的方法就是大家遵守一個(gè)業(yè)界規(guī)范，那就是HTTP的狀態(tài)碼。下面的2點(diǎn)都是舉例來證明第1點(diǎn)。
2. 很多JavaScript框架設(shè)計(jì)上就是基于HTTP協(xié)議的，根據(jù)不同的狀態(tài)碼做不同的處理，比如下面的JQuery的Ajax請(qǐng)求就可以根據(jù)HTTP的狀態(tài)碼執(zhí)行不同的代碼塊：$.ajax({
   url: 'https://maishucode.com/page/2',
   type: 'GET',
   success: function(data){
   alert('成功返回'); //返回2xx，執(zhí)行這個(gè)代碼塊
   }, error: function(data) {
   alert('出錯(cuò)啦!'); //返回4xx或者5xx，執(zhí)行這個(gè)代碼塊
   }});如果API沒有正確的使用HTTP狀態(tài)碼，上面的代碼中需要手動(dòng)解析JSON里面的狀態(tài)碼，再做分支的判斷。
3. 為了通用，很多中間系統(tǒng)根據(jù)狀態(tài)碼來分析系統(tǒng)的訪問數(shù)據(jù)，比如ELK可以根據(jù)HTTP的狀態(tài)碼分析有多少成功的請(qǐng)求，多少失敗的請(qǐng)求。如果都統(tǒng)一返回200，那么就沒法分析出：有哪些未登錄的訪問，有哪些未授權(quán)的訪問，有多少服務(wù)器端錯(cuò)誤等。但是這里有利也有弊，有些流氓的中間系統(tǒng)會(huì)根據(jù)狀態(tài)碼劫持網(wǎng)頁(yè)，比如有些瀏覽器和路由器就會(huì)劫持404網(wǎng)頁(yè)，顯示它自己的廣告頁(yè)。具體做法是：當(dāng)路由器或者瀏覽器發(fā)現(xiàn)請(qǐng)求返回的是404，它們就會(huì)丟掉Response，而顯示一個(gè)自己的廣告網(wǎng)頁(yè)。這種劫持是非常無恥的行為。404也是服務(wù)器返回給請(qǐng)求者的一個(gè)消息，網(wǎng)頁(yè)仍然可能包含重要的內(nèi)容。再說了，不管什么消息，中間人都不應(yīng)該劫持。

• 總結(jié)一下，我支持使用合理的HTTP狀態(tài)碼的。原因上面已經(jīng)說了。但是慎用404，因?yàn)榭赡軙?huì)被眾多流氓劫持。但是還有兩點(diǎn):
• 不要濫用HTTP狀態(tài)碼，基本上就用我前面列舉出來的那些就夠了。
• 使用HTTP狀態(tài)碼后，仍然需要使用和業(yè)務(wù)相關(guān)的狀態(tài)碼。這就是下面要說的。

Rest API的錯(cuò)誤處理最佳實(shí)踐

使用了HTTP狀態(tài)碼以后，讓API符合了一定的標(biāo)準(zhǔn)，這很好。但HTTP狀態(tài)碼不能涵蓋我們具體的業(yè)務(wù)場(chǎng)景，我們?nèi)匀恍枰x和業(yè)務(wù)場(chǎng)景相對(duì)應(yīng)的錯(cuò)誤碼。下面我推薦一個(gè)錯(cuò)誤處理的返回格式，舉例如下：

{ "status":403,
   "error": {     
      "code":'40041',      
      "message":"用戶缺少訪問特工名單權(quán)限",     
      "moreInfo":"https://maishucode.com/errors/40041", 
      "traceId":"9527"      }, 
   "data":{
  }
}

下面是對(duì)每個(gè)字段的解釋：

• status: HTTP狀態(tài)碼，不能為空，必須和HTTP header中的狀態(tài)碼一致。
• code: 具體業(yè)務(wù)代碼，可以為空。這里需要技術(shù)人員和業(yè)務(wù)人員一起定義一套錯(cuò)誤代碼規(guī)則。
• message: 對(duì)錯(cuò)誤信息的簡(jiǎn)單解釋
• moreInfo: 對(duì)錯(cuò)誤信息的詳細(xì)解釋的網(wǎng)址。包含錯(cuò)誤的詳細(xì)解釋，可能的原因，如何修正等。
• traceId: 通過這個(gè)字段可以去日志文件中查找和本次操作相關(guān)的日志。
• data: 存放具體的業(yè)務(wù)數(shù)據(jù)。

我要說的說完了！雖然這沒有絕對(duì)的對(duì)錯(cuò)，但是符合良好的規(guī)范，提供充分的信息給調(diào)用用肯定是沒錯(cuò)的。你覺得呢？在留言區(qū)留下你的意見吧！