來源：麥叔編程

作者：麥叔

代碼評審會上，氣氛有點緊張！

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

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

張三對此不以為然的說：

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

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

聽我細細道來，本文涵蓋：

• HTTP和Rest API的基本知識
• Rest API使用HTTP Status Code的最佳實踐
• Rest API的錯誤處理最佳實踐

HTT協(xié)議和Restful API

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

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

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

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

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

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

HTTP Status Code

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

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

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

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

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

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

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

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

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

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

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

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

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

Rest API的錯誤處理最佳實踐

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

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

下面是對每個字段的解釋：

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

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