RESTful API 中的 Status code 是否要遵照規範

緣起

事情是這樣的，我在知乎受到邀請回答一個問題，主要是問 ID 找不到到底要不要用 Status 404 。我回答的仍是比較早的，那時候只有一兩個回答。我原本覺得這是沒啥爭議的，在一個學術的地方討論學術問題，固然是要遵照規範了，結果過了幾個小時大跌眼鏡。自造 code 黨居然支持率第一，還好平時見的也不少的全 200 黨沒有受到支持，否則真的吐血了。

爲何要遵照規範

通常那種說特殊狀況特殊處理，不要拘泥於規範的人，大多都是本身沒搞清楚某些知識，拿這句話看成偷懶的藉口。其實通常作項目沒那麼多特殊狀況。

爲了更好的適應各類庫

大部分完善的 HTTP 請求庫，都會依照 RFC 的規範去設計錯誤處理的流程，雖然處理方式各有不一樣，但必定會在文檔說明錯誤處理的部分的。使用 RFC 標準能最大限度的兼容各類 HTTP 客戶端。你說如今你用的HTTP客戶端不處理 Status Code，可是你無法保證未來不重構，重構的時候仍是不處理。

通常調用 api 使用 js 或者 python 的機率比較大，咱們看看知名的庫。在 js 裏，最近比較流行的 axios 默認會把 200 系列外的 code 歸到異常裏。在 python 裏，最流行的 http client 是 requests ，它更爲詳盡的預處理了 status code 。

爲了開發者更好上手

另外在管理團隊的方面，咱們的原則是儘可能的減小一個項目的「規範」，這樣才能更容易去遵照。能用標準的地方，必定不要本身定一個更復雜的規則。不管是服務端的維護者仍是 API 的消費者是會換人流動的，每一個進入項目的人熟悉一大堆無謂的自定義項目規範都要成本。

更簡單的辦法是參考大廠

其實給項目定規範，最不靠譜的是本身拍腦殼，稍好一點的是去知乎或論壇問，更好一點的是去 google 搜，最簡單的是直接去看大廠的產品或者規範啊。 API 原本就是個公開暴露的東西，還有比這更好找參考的嗎？咱們來看看：

• Google 遵照規範
• Github 遵照規範
• Microsoft 遵照規範 順便說一句，微軟的 API 規範真的很具備指導意義。
• Twitter 遵照規範
• 阿里雲 遵照規範
• 騰訊雲 不遵照規範 所有 200 事實上騰訊的技術比較混亂，每一個項目都不同。但最新要執行的統一規範是所有 返回 200 用返回值中的錯誤碼代表錯誤。
• 百度雲 遵照規範

個人建議

不少人也許用着很簡陋的 Web 框架，致使誤覺得返回了錯誤碼，就不能返回 Response Body 了。其實你返回 204 外的任何 Status Code，最好都伴隨着返回 Body 。

在項目規範裏，能夠規定 Status Code 遵守 RFC 標準，或者選定一個集合出來，把一些不經常使用的去掉。而後若是不是200系列的代碼，必須伴隨着這樣的一個錯誤結構：

{
    "error": "UserNotFound",
    "message": "該用戶沒有找到"
 }
複製代碼

這樣錯誤分爲了三層結構，第一層是 Status Code，使用者能大概知道是什麼問題。第二層Error 是一個 Key 使用約定好的無空格的英文，給使用者作判斷用，使用者能夠根據 Key 自定義接下來的操做。第三層是 message ，有些 Key 使用者能夠決定直接把 Message 顯示個終端客戶。

若是是微服務項目，須要要求每一個服務無論用什麼語言，都要把錯誤統一成這個樣子。若是開發者告訴你框架不支持，那這必定不是個好框架，改重構了。好的框架不只能讓你自定義錯誤內容，還能作到所謂的「框架本身出錯的返回」也由你自定義。好比路由沒有找到之類的。

最後

我實在不明白爲何一個最扯淡的答案，要自造一個 600 的 status code ，能夠得票第一。知乎用戶到底有沒有一點獨立的判斷精神啊，只要裝的一本正經，再擺出來一點資歷，哪怕是胡說八道，你們也紛紛點贊。也許真的不適合在知乎去回答技術問題了。