Like Share Discussion Bookmark Smile

J.J. Huang   2020-05-08   Java   瀏覽次數:

《阿里Java開發手冊》 | 異常日誌 - 錯誤碼

【強制】錯誤碼的製定原則:快速溯源、簡單易記、溝通標準化。
說明: 錯誤碼想得過於完美和復雜,就像康熙字典中的生僻字一樣,用詞似乎精準,但是字典不容易隨身攜帶並且簡單易懂。
正例:錯誤碼回答的問題是誰的錯?錯在哪?

  • 錯誤碼必須能夠快速知曉錯誤來源,可快速判斷是誰的問題。
  • 錯誤碼易於記憶和比對(程式碼中容易 equals)。
  • 錯誤碼能夠脫離文件和系統平台達到線下輕量化地自由溝通的目的。

【強制】錯誤碼不體現版本號和錯誤等級訊息。
說明:錯誤碼以不斷追加的方式進行兼容。錯誤等級由日誌和錯誤碼本身的釋義來決定。


【強制】全部正常,但不得不填充錯誤碼時返回五個零:00000。


【強制】錯誤碼為字符串類型,共 5 位,分成兩個部分:錯誤產生來源+四位數字編號。
說明:錯誤產生來源分為 A/B/C ,A 表示錯誤來源於用戶,比如參數錯誤,用戶安裝版本過低,用戶支付超時等問題;B 表示錯誤來源於當前系統,往往是業務邏輯出錯,或程序健壯性差等問題;C 表示錯誤來源於第三方服務,比如 CDN 服務出錯,消息投遞超時等問題;四位數字編號從 0001 到 9999,大類之間的步長間距預留 100,參考文末。


【強制】編號不與公司業務架構,更不與組織架構掛鉤,一切與平台先到先申請的原則進行,審批生效,編號即被永久固定。


【強制】錯誤碼使用者避免隨意定義新的錯誤碼。
說明:盡可能在原有錯誤碼附表中找到語義相同或者相近的錯誤碼在程式碼中使用即可。


【強制】錯誤碼不能直接輸出給用戶作為提示訊息使用。
說明:堆棧(stack_trace)、錯誤訊息(error_message)、錯誤碼(error_code)、提示訊息(user_tip)是一個有效關聯並互相轉義的和諧整體,但是請勿互相越俎代庖。


【推薦】錯誤碼之外的業務獨特訊息由 error_message 來承載,而不是讓錯誤碼本身涵蓋過多具體業務屬性。


【推薦】在獲取第三方服務錯誤碼時,向上拋出允許本系統轉義,由 C 轉為 B,並且在錯誤訊息上帶上原有的第三方錯誤碼。


【參考】錯誤碼分為一級宏觀錯誤碼、二級宏觀錯誤碼、三級宏觀錯誤碼。
說明:在無法更加具體確定的錯誤場景中,可以直接使用一級宏觀錯誤碼,分別是:A0001(用戶端錯誤)、B0001(系統執行出錯)、C0001(調用第三方服務出錯)
正例:調用第三方服務出錯是一級,中間件錯誤是二級,消息服務出錯是三級。


【參考】錯誤碼的後三位編號與 HTTP 狀態碼沒有任何關係。


【參考】錯誤碼盡量有利於不同文化背景的開發者進行交流與程式碼協作。
說明:英文單詞形式的錯誤碼不利於非英語母語國家(如阿拉伯語、希伯來語、俄羅斯語等)之間的開發者互相協作。


【參考】錯誤碼即人性,感性認知+口口相傳,使用純數字來進行錯誤碼編排不利於感性記憶和分類。
說明:數字是一個整體,每位數字的地位和含義是相同的。
反例:一個五位數字 12345,第 1 位是錯誤等級,第 2 位是錯誤來源,345 是編號,人的大腦不會主動地分辨每位數字的不同含義。


錯誤碼列表

錯誤碼 中文描述 說明
00000 一切 ok 正確執行後的返回
A0001 用戶端錯誤 一級宏觀錯誤碼
A0100 用戶註冊錯誤 二級宏觀錯誤碼
A0101 用戶未同意隱私協議
A0102 註冊國家或地區受限
A0110 用戶名校驗失敗
A0111 用戶名已存在
A0112 用戶名包含敏感詞
A0113 用戶名包含特殊字符
A0120 密碼校驗失敗
A0121 密碼長度不夠
A0122 密碼強度不夠
A0130 校驗碼輸入錯誤
A0131 短信校驗碼輸入錯誤
A0132 郵件校驗碼輸入錯誤
A0133 語音校驗碼輸入錯誤
A0140 用戶證件異常
A0141 用戶證件類型未選擇
A0142 大陸身份證編號校驗非法
A0143 護照編號校驗非法
A0144 軍官證編號校驗非法
A0150 用戶基本訊息校驗失敗
A0151 手機格式校驗失敗
A0152 地址格式校驗失敗
A0153 郵箱格式校驗失敗
A0200 用戶登陸異常 二級宏觀錯誤碼
A0201 用戶賬戶不存在
A0202 用戶賬戶被凍結
A0203 用戶賬戶已作廢
A0210 用戶密碼錯誤
A0211 用戶輸入密碼次數超限
A0220 用戶身份校驗失敗
A0221 用戶指紋識別失敗
A0222 用戶面容識別失敗
A0223 用戶未獲得第三方登陸授權
A0230 用戶登陸已過期
A0240 用戶驗證碼錯誤
A0241 用戶驗證碼嘗試次數超限
A0300 訪問權限異常 二級宏觀錯誤碼
A0301 訪問未授權
A0302 正在授權中
A0303 用戶授權申請被拒絕
A0310 因訪問對象隱私設置被攔截
A0311 授權已過期
A0312 無權限使用 API
A0320 用戶訪問被攔截
A0321 黑名單用戶
A0322 賬號被凍結
A0323 非法 IP 地址
A0324 閘道器訪問受限
A0325 地域黑名單
A0330 服務已欠費
A0340 用戶簽名異常
A0341 RSA 簽名錯誤
A0400 用戶請求參數錯誤 二級宏觀錯誤碼
A0401 包含非法惡意跳轉鏈接
A0402 無效的用戶輸入
A0410 請求必填參數為空
A0411 用戶訂單號為空
A0412 訂購數量為空
A0413 缺少時間戳參數
A0414 非法的時間戳參數
A0420 請求參數值超出允許的範圍
A0421 參數格式不匹配
A0422 地址不在服務範圍
A0423 時間不在服務範圍
A0424 金額超出限制
A0425 數量超出限制
A0426 請求批量處理總個數超出限制
A0427 請求 JSON 解析失敗
A0430 用戶輸入內容非法
A0431 包含違禁敏感詞
A0432 圖片包含違禁訊息
A0433 文件侵犯版權
A0440 用戶操作異常
A0441 用戶支付超時
A0442 確認訂單超時
A0443 訂單已關閉
A0500 用戶請求服務異常 二級宏觀錯誤碼
A0501 請求次數超出限制
A0502 請求並發數超出限制
A0503 用戶操作請等待
A0504​​ WebSocket 連接異常
A0505 WebSocket 連接斷開
A0506 用戶重複請求
A0600 用戶資源異常 二級宏觀錯誤碼
A0601 賬戶餘額不足
A0602 用戶磁盤空間不足
A0603 用戶內存空間不足
A0604 用戶 OSS 容量不足
A0605 用戶配額已用光 螞蟻森林澆水數或每天抽獎數
A0700 用戶上傳文件異常 二級宏觀錯誤碼
A0701 用戶上傳文件類型不匹配
A0702 用戶上傳文件太大
A0703 用戶上傳圖片太大
A0704 用戶上傳視頻太大
A0705 用戶上傳壓縮文件太大
A0800 用戶當前版本異常 二級宏觀錯誤碼
A0801 用戶安裝版本與系統不匹配
A0802 用戶安裝版本過低
A0803 用戶安裝版本過高
A0804 用戶安裝版本已過期
A0805 用戶 API 請求版本不匹配
A0806 用戶 API 請求版本過高
A0807 用戶 API 請求版本過低
A0900 用戶隱私未授權 二級宏觀錯誤碼
A0901 用戶隱私未簽署
A0902 用戶攝像頭未授權
A0903 用戶相機未授權
A0904 用戶圖片庫未授權
A0905 用戶文件未授權
A0906 用戶位置訊息未授權
A0907 用戶通訊錄未授權
A1000 用戶設備異常 二級宏觀錯誤碼
A1001 用戶相機異常
A1002 用戶麥克風異常
A1003 用戶聽筒異常
A1004 用戶揚聲器異常
A1005 用戶 GPS 定位異常
B0001 系統執行出錯 一級宏觀錯誤碼
B0100 系統執行超時 二級宏觀錯誤碼
B0101 系統訂單處理超時
B0200 系統容災功能被觸發 二級宏觀錯誤碼
B0210 系統限流
B0220 系統功能降級
B0300 系統資源異常 二級宏觀錯誤碼
B0310 系統資源耗盡
B0311 系統磁盤空間耗盡
B0312 系統內存耗盡
B0313 文件句柄耗盡
B0314 系統連接池耗盡
B0315 系統執行緒池(thread pool)耗盡
B0320 系統資源訪問異常
B0321 系統讀取磁盤文件失敗
C0001 調用第三方服務出錯 一級宏觀錯誤碼
C0100 中間件服務出錯 二級宏觀錯誤碼
C0110 RPC 服務出錯
C0111 RPC 服務未找到
C0112 RPC 服務未註冊
C0113 接口不存在
C0120 消息服務出錯
C0121 消息投遞出錯
C0122 消息消費出錯
C0123 消息訂閱出錯
C0124 消息分組未查到
C0130 緩存服務出錯
C0131 key 長度超過限制
C0132 value 長度超過限制
C0133 存儲容量已滿
C0134 不支持的資料格式
C0140 配置服務出錯
C0150 網路資源服務出錯
C0151 VPN 服務出錯
C0152 CDN 服務出錯
C0153 域名解析服務出錯
C0154 閘道器服務出錯
C0200 第三方系統執行超時 二級宏觀錯誤碼
C0210 RPC 執行超時
C0220 消息投遞超時
C0230 緩存服務超時
C0240 配置服務超時
C0250 資料庫服務超時
C0300 資料庫服務出錯 二級宏觀錯誤碼
C0311 表不存在
C0312 列不存在
C0321 多表關聯中存在多個相同名稱的列
C0331 資料庫死鎖
C0341 主鍵衝突
C0400 第三方容災系統被觸發 二級宏觀錯誤碼
C0401 第三方系統限流
C0402 第三方功能降級
C0500 通知服務出錯 二級宏觀錯誤碼
C0501 短信提醒服務失敗
C0502 語音提醒服務失敗
C0503 郵件提醒服務失敗

心得

看完這篇「錯誤碼」後,首先想說的是「錯誤碼列表」可以拿來做參考,畢竟每家公司需要定義的東西不太一樣;而錯誤碼最簡單要做到的就是簡單易懂清楚表達,可以省去很多查找問題的地方和時間。

結語

文章越看越多,技術越學越多,就會發現自己的不足;技術學到後面都會想要將基礎再重新在打得更加扎實。

以前在開發覺得理所當然的事情,例如:命名規則、命名規範,照著別人怎麼說就怎麼做的想法,並沒有好好去想為什麼要這樣設計和規範。
於是乎同事們推薦《阿里巴巴Java開發手冊》來做閱讀,書中提到種種規範《正確範例》、《錯誤範例》還有解釋定義說明;我相信在閱讀完這一系列後,一定會更加扎實且實在。

如對此書有興趣,建議去購買官方認證的書籍,給予官方支持。

註:如有侵權,通知即刪。


註:以上參考了
Alibaba-Java-Coding-Guidelines Github
Alibaba-Java-Coding-Guidelines English Version