趣說API HTTP 狀態碼的使用

在設計API HTTP 狀態碼的時候，咱們總能聽到兩種聲音：
第一種，也是你們最經常使用的：

全部接口的狀態碼都返回 200，而後在自定義錯誤碼：

# 正確響應
{
  "code: 200,
  "message": "success",
  "data": {
    "id": ...,
    ...
  }
}
# 錯誤響應
{
  "code: 1001, // 自定義錯誤類型
  "message": "error message",
  "data": {}
}

另外一種，Rest API,僅使用HTTP狀態代碼：

# 正確響應
HTTP/1.1 200
Content-Type: application/json
{
    "id": ...,
    ...
}

# 錯誤響應
HTTP/1.1 401 Unauthorized
{
  "message": "Bad credentials"
}

更多的錯誤碼規範能夠直接從 HTTP Status Code 查看。

爲何說是兩種聲音，其實如今基本規範的話都會直接選擇第二種，基本上，Github的

Github API v3以及如今廣泛後端框架的設計都對於Rest API 有着更好的支持。
因此上面聲音的爭執彷佛存在與先後端的更多些。

補充一下 Github v4 版本已經開始使用 GraphQL了， GraphQL 是一種查詢語言，相比於 Rest API的設計，如今國外比較喜歡和流行 GraphQL ，但好像國內還並未據說有過多的使用。

說一下二者的優缺點吧，
第一種：

• 優勢：客戶端僅須要處理做爲 json字符串的響應主體並忽略狀態。
• 缺點：標準化低。

第二種：

• 優勢：標準化高，客戶端僅須要處理做爲json字符串的響應主體並忽略狀態。
• 缺點：業務複雜度高時的使用場景使用不足。

而結合兩種優缺點，如今許多人開始有了第三種方式：
HTTP Status 與Json body 相結合

• 優勢：依舊能保證標準化，能夠處理兼容更多的業務場景。
• 缺點：客戶端處理的複雜度高，須要根據業務場景作更多的判斷選擇

參考資料

Github API v3
HTTP Status Code
dingo-api 錯誤響應
Github v4