來源：https://ken.io/note/api-errorcode-or-resultcode-desgin
一、前言
客戶端請求API，通常需要通過回傳碼來判斷API回傳的結果是否符合預期，以及該如何處理回傳的內容等
相信很多同學都吃過回傳碼定義混亂的虧，有的API用回傳碼是int型別，有的是string型別，有的用0表示成功，又有的用1表示成功，還有用”true”表示成功，碰上這種事情，只能說：頭疼
API回傳碼的設計還是要認真對待，畢竟好的回傳碼設計可以降低溝通成本以及程式的維護成本
二、HTTP狀態碼參考
以HTTP狀態碼為例，為了更加清晰的表述和區分狀態碼的含義，HTTP狀態做了分段，
| 分段 | 分段描述 |
|---|---|
| 1XX | 資訊，服務器收到請求，需要請求者繼續執行操作 |
| 2XX | 成功，操作被成功接收并處理 |
| 3XX | 重定向，需要進一步的操作以完成請求 |
| 4XX | 客戶端錯誤，請求包含語法錯誤或無法完成請求 |
| 5XX | 服務器錯誤，服務器在處理請求的程序中發生了錯誤 |
對于后端開發來說，我們通常見到的都是：
2XX狀態碼，比如200->請求成功，
5XX狀態碼，比如502->服務器例外，通常就是服務沒正常運行，或者代碼執行出錯
通過狀態碼即可初步判斷問題原因，HTTP狀態的設計思路值得借鑒，
三、引數約定
雖說是回傳碼設計，但是只有code是不行的，還要有對應的message，讓人可以看懂
| 欄位 | 型別 | 說明 |
|---|---|---|
| code | int | 回傳碼 |
| message | string | 回傳碼說明 |
參考HTTP狀態碼的思路，我們對錯誤碼進行分段
| 回傳碼值 | 說明 |
|---|---|
| 0 | 成功 |
| 99999 | 系統發生未知例外 |
| 10000-19999 | 引數校驗錯誤 |
| 20000-29999 | A步驟執行失敗 |
| 30000-39999 | B步驟執行失敗 |
通過這樣的設計，不論是程式還是人都可以非常方便的區分API的回傳結果，關鍵是統一！
四、個性化Message
通常我們的message都是寫給工程師看的，但是在不同的場景下，同樣的錯誤，可能需要給用戶看到不一樣的錯誤提示，
比方說 20000-29999表示訂單創建失敗：
- 20001，訂單創建失敗，存在進行中的訂單
- 20002，訂單創建失敗，上一個訂單正在排隊創建中
這兩種錯誤情況如果是給用戶看，可能就只適合看到：很抱歉，您有一個正在進行中的訂單，請到我的訂單串列中處理，
但是對于API來說，回傳的資訊又必須是準確的，但用戶看到的就必須轉譯，這個轉譯的作業呼叫方可以做，但是通常API提供者來提供個性化的Message能力會更好
我們可以把轉譯的訊息配置到資料庫，并快取到Redis或者API本機
| application_id | code | message |
|---|---|---|
| 100001 | 20001 | 很抱歉，您有一個正在進行中的訂單，請到我的訂單串列中處理， |
| 100001 | 20002 | 很抱歉，您有一個正在進行中的訂單，請到我的訂單串列中處理， |
然后在請求處理結束即將回傳的時候，根據application_id+code，去匹配替換message
這樣我們就可以讓手機APP的用戶、微信小程式的用戶、網頁下單的企業用戶看到不同的訊息
五、回傳資訊的統一處理
有了統一的code，我們就可以通過Nginx或者APM工具統計API請求Code數量及分布資訊，
我們可以根據單位時間內99999的數量來做API的例外告警
我們可以根據Code的回傳餅圖，幫助我們發現系統、業務流程中的問題
等等，總之，好的回傳碼設計，可以幫助我們提高溝通效率，降低代碼的維護成本，
近期熱文推薦：
1.1,000+ 道 Java面試題及答案整理(2022最新版)
2.勁爆！Java 協程要來了，，，
3.Spring Boot 2.x 教程，太全了！
4.20w 程式員紅包封面，快快領取，，，
5.《Java開發手冊（嵩山版）》最新發布，速速下載！
覺得不錯，別忘了隨手點贊+轉發哦！
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/426371.html
標籤：其他