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

一、前言

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

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

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

二、HTTP 狀態(tài)碼參考

以 HTTP 狀態(tài)碼為例，為了更加清晰的表述和區(qū)分狀態(tài)碼的含義，HTTP 狀態(tài)做了分段。

圖片

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

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

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

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

三、參數(shù)約定

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

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

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

四、個(gè)性化 Message

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

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

20001，訂單創(chuàng)建失敗，存在進(jìn)行中的訂單

20002，訂單創(chuàng)建失敗，上一個(gè)訂單正在排隊(duì)創(chuàng)建中

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

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

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

圖片

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

圖片

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

五、返回信息的統(tǒng)一處理

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

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

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

等等

總之，好的返回碼設(shè)計(jì)，可以幫助我們提高溝通效率，降低代碼的維護(hù)成本。

審核編輯：劉清