如何設計 API 返回碼（錯誤碼）？

前言

客戶端請求 API，通常需要通過返回碼來判斷 API 返回的結果是否符合預期，以及該如何處理返回的內容等。

相信很多同學都喫過返回碼定義混亂的虧，有的 API 用返回碼是 int 類型，有的是 string 類型，有的用 0 表示成功，又有的用 1 表示成功，還有用 “true” 表示成功，碰上這種事情，只能說：頭疼。

API 返回碼的設計還是要認真對待，畢竟好的返回碼設計可以降低溝通成本以及程序的維護成本。

HTTP 狀態碼參考

以 HTTP 狀態碼爲例，爲了更加清晰的表述和區分狀態碼的含義，HTTP 狀態做了分段。

對於後端開發來說，我們通常見到的都是：

2XX 狀態碼，比如 200-> 請求成功。

5XX 狀態碼，比如 502-> 服務器異常，通常就是服務沒正常運行，或者代碼執行出錯。

通過狀態碼即可初步判斷問題原因，HTTP 狀態的設計思路值得借鑑。

參數約定

雖說是返回碼設計，但是隻有 code 是不行的，還要有對應的 message，讓人可以看懂。

參考 HTTP 狀態碼的思路，我們對錯誤碼進行分段。

通過這樣的設計，不論是程序還是人都可以非常方便的區分 API 的返回結果，關鍵是統一！

個性化 Message

通常我們的 Message 都是寫給工程師看的，但是在不同的場景下，同樣的錯誤，可能需要給用戶看到不一樣的錯誤提示。

比方說 20000-29999 表示訂單創建失敗：

• 20001，訂單創建失敗，存在進行中的訂單

• 20002，訂單創建失敗，上一個訂單正在排隊創建中

這兩種錯誤情況如果是給用戶看，可能就只適合看到：很抱歉，您有一個正在進行中的訂單，請到我的訂單列表中處理。

但是對於 API 來說，返回的信息又必須是準確的，但用戶看到的就必須轉譯，這個轉譯的工作調用方可以做，但是通常 API 提供者來提供個性化的 Message 能力會更好。

我們可以把轉譯的消息配置到數據庫，並緩存到 Redis 或者 API 本機。

然後在請求處理結束即將返回的時候，根據 application_id+code，去匹配替換 message。

這樣我們就可以讓手機 APP 的用戶、微信小程序的用戶、網頁下單的企業用戶看到不同的消息。

返回信息的統一處理

有了統一的 code，我們就可以通過 Nginx 或者 APM 工具統計 API 請求 Code 數量及分佈信息。

我們可以根據單位時間內 99999 的數量來做 API 的異常告警。

我們可以根據 Code 的返回餅圖，幫助我們發現系統、業務流程中的問題。

等等……

總之，好的返回碼設計，可以幫助我們提高溝通效率，降低代碼的維護成本

原文鏈接：https://ken.io/note/api-errorcode-or-resultcode-desgin

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/B0HiHcfOfbYgHSNGM4w1fg