如何設(shè)計API返回碼（錯誤碼）？

作者：ken
來源：ken.io/note/api-errorcode-or-resultcode-desgin
上一篇：我裸辭全職接單第一個月的收入

前言
客戶端請求API，通常需要通過返回碼來判斷API返回的結(jié)果是否符合預(yù)期，以及該如何處理返回的內(nèi)容等。

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

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

HTTP狀態(tài)碼參考
以HTTP狀態(tài)碼為例，為了更加清晰的表述和區(qū)分狀態(tài)碼的含義，HTTP狀態(tài)做了分段。搜索公眾號互聯(lián)網(wǎng)架構(gòu)師后臺回復(fù)“2T”，獲取一份驚喜禮包。


對于后端開發(fā)來說，我們通常見到的都是：

2XX狀態(tài)碼，比如200->請求成功。

5XX狀態(tài)碼，比如502->服務(wù)器異常，通常就是服務(wù)沒正常運行，或者代碼執(zhí)行出錯。

通過狀態(tài)碼即可初步判斷問題原因，HTTP狀態(tài)的設(shè)計思路值得借鑒。

參數(shù)約定
雖說是返回碼設(shè)計，但是只有code是不行的，還要有對應(yīng)的message，讓人可以看懂。


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


通過這樣的設(shè)計，不論是程序還是人都可以非常方便的區(qū)分API的返回結(jié)果，關(guān)鍵是統(tǒng)一！

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

搜索公眾號互聯(lián)網(wǎng)架構(gòu)師后臺回復(fù)“2T”，獲取一份驚喜禮包。

比方說20000-29999表示訂單創(chuàng)建失?。?/span>

20001，訂單創(chuàng)建失敗，存在進行中的訂單
20002，訂單創(chuàng)建失敗，上一個訂單正在排隊創(chuàng)建中

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

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

我們可以把轉(zhuǎn)譯的消息配置到數(shù)據(jù)庫，并緩存到Redis或者API本機。


然后在請求處理結(jié)束即將返回的時候，根據(jù)application_id+code，去匹配替換message。


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

返回信息的統(tǒng)一處理
有了統(tǒng)一的code，我們就可以通過Nginx或者APM工具統(tǒng)計API請求Code數(shù)量及分布信息。

我們可以根據(jù)單位時間內(nèi)99999的數(shù)量來做API的異常告警。

我們可以根據(jù)Code的返回餅圖，幫助我們發(fā)現(xiàn)系統(tǒng)、業(yè)務(wù)流程中的問題。

等等……

總之，好的返回碼設(shè)計，可以幫助我們提高溝通效率，降低代碼的維護成本。
相關(guān)閱讀：2T架構(gòu)師學(xué)習(xí)資料干貨分享