如何設計API返回碼(錯誤碼)?
from :https://mp.weixin.qq.com/s/fbx-FhR8UoaVRSusI6h-DQ
客戶端請求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的返回餅圖,幫助我們發現系統、業務流程中的問題。
等等……
總之,好的返回碼設計,可以幫助我們提高溝通效率,降低程式碼的維護成本