一 前言
在工作中，接觸過不少外部接口，其中包括：支付寶，微信支付，微網誌開發平台，阿裡雲等等。每家公司錯誤碼風格都不盡相同，有使用純數字的，有使用純英文的，也有使用字母和數字組合的。也接觸過很多内部系統，錯誤碼設計也不盡相同。
錯誤碼的輸出路徑
面向日志輸出
- 服務内傳遞，最終是輸出到日志。
- 域内服務間，比如同時大麥電商之間的系統，最終目的是輸出到日志。
面向外部傳遞
- 域内向域外
- 服務端傳遞到前端
- OpenAPI 錯誤碼
- 内部不同域之間
錯誤碼使用場景
- 通過錯誤碼配置監控大盤。
- 通過日志進行問題排查，快速定位問題。
- 後端服務之間錯誤碼傳遞。
- 前端展示的錯誤提示/OpenAPI。
本文希望從錯誤碼使用的不同場景讨論得到一個合理的錯誤碼規約，得到一個面向日志錯誤碼标準和一個面向外部傳遞的錯誤碼标準。
PS：本文引用全部引自阿裡巴巴《Java 開發手冊》，下稱《手冊》。
二 什麼是錯誤碼
錯誤碼要回答的最根本的問題是，誰的錯？錯在哪？
那麼一個錯誤能表示出誰的錯和錯在哪裡就是一個好的錯誤碼嗎？答案顯然是否定的，這個标準太基礎了。
- 好的錯誤碼必須能夠快速知曉錯誤來源。
- 好的錯誤碼必須易于記憶和對比。
- 好的錯誤碼必須能夠脫離文檔和系統平台達到線下輕量溝通的目的（這個要求比較高）。
引自《手冊》- 異常日志-錯誤碼
錯誤碼的制定原則：快速溯源、簡單易記、溝通标準化。
說明：錯誤碼想得過于完美和複雜，就像康熙字典中的生僻字一樣，用詞似乎精準，但是字典不容易随身攜帶并且簡單易懂。
正例：錯誤碼回答的問題是誰的錯？錯在哪？
1）錯誤碼必須能夠快速知曉錯誤來源，可快速判斷是誰的問題。
2）錯誤碼易于記憶和比對（代碼中容易 equals）。
3）錯誤碼能夠脫離文檔和系統平台達到線下輕量化地自由溝通的目的。
這個原則寫在異常日志-錯誤碼這個章節，我認為同樣适用在面向使用者的錯誤碼。
三 錯誤碼規範
錯誤碼定義要有字母也要有數字
純數字錯誤碼
錯誤碼即人性，感性認知+口口相傳，使用純數字來進行錯誤碼編排不利于感性記憶和分類。
說明：數字是一個整體，每位數字的地位和含義是相同的。
反例：一個五位數字 12345，第1位是錯誤等級，第 2 位是錯誤來源，345 是編号，人的大腦不會主動地分辨每位數字的不同含義。
《手冊》說明了純數字錯誤碼存在的問題。
純字母錯誤碼
那麼純字母錯誤碼不香嗎？有兩個問題：
- 對于使用漢語的我們用英語去準确描述一個錯誤有時是比較困難的。
- 純英文字母的錯誤碼不利于排序。
錯誤碼盡量有利于不同文化背景的開發者進行交流與代碼協作。
說明：英文單詞形式的錯誤碼不利于非英語母語國家（如阿拉伯語、希伯來語、俄羅斯語等）之間的開發者互相協作。
快速溯源 | 簡單易記 | 溝通标準化
什麼是快速溯源？就是一眼看上去就知道哪裡出了什麼問題。
李雷負責 A 服務，韓梅梅負責 B 服務。韓梅梅發現服務 B 出現了一個錯誤碼，韓梅梅能夠快速定位這是服務 A 的内部業務異常造成的問題，這個時候韓梅梅就可以拿着錯誤碼找到李雷說，"hi，Li Lei，How old are you。(李雷，怎麼老是你)"。李雷拿過來錯誤碼一看，内心萬馬奔騰，一下就能知道這是上遊 Polly 負責的應用阿爾法出了錯。
怎麼能達到這個效果呢？
- 首先要有一套标準并且在域内各個業務都在用同樣的标準。
- 其次要求錯誤碼有自我解釋的能力是有資訊含量的有意義。
- 最後在域内要傳遞錯誤碼。
錯誤碼标準的意義
開宗明義借用了《手冊》對于錯誤碼定義的原則作為錯誤碼規範能夠給我們帶來的收益。我想再次強調并且試着從反面闡述沒有錯誤碼标準會帶來的成本。
錯誤碼是用來做溝通的：系統與系統間的溝通，人與人間的溝通，人與系統間的溝通。
試想下面這個場景：
韓梅梅看到一個異常日志其中一個純數字的錯誤碼。
韓梅梅需要了解這串數字代表的是什麼，它到底是不是一個錯誤碼，經過幾秒鐘确定下來這是一個錯誤碼，但她不能确定這是不是本系統中錯誤碼，因為在她負責的系統是由韓梅梅、Lucy 和 Lily 三個人共同維護的，每個人都按照自己的了解定義了一套錯誤碼。
韓梅梅去系統源碼中查找這個錯誤碼，但是發現這個錯誤碼并不是本系統的錯誤碼。
然後再前翻兩頁後翻兩頁從日志上下文中确定這是李雷負責系統的錯誤碼，“Li Lie，how old are you？”。
韓梅梅把錯誤碼甩到李雷臉上，李雷一臉懵逼，這是我的系統的錯誤碼嗎？
李雷也不确定，因為李雷負責的系統是由李雷、林濤和 Jim 維護的，也是三人共同維護的。
李雷隻好打開源碼，還真是！
上邊的場景經過了發現-初判斷-判斷來源-确定來源-溝通-二次判斷-二次确認七個步驟。
希望上邊的場景描述能夠說明沒有統一标準的錯誤所帶來的成本。
四 面向日志的錯誤碼
輸出到日志的錯誤碼有兩個用途：
- 用來快速溯源找到問題。
- 用來形成監控大盤。
錯誤碼設計
《手冊》對于錯誤碼的建議有非常多的可取參考的地方：
錯誤碼不展現版本号和錯誤等級資訊。
說明：錯誤碼以不斷追加的方式進行相容。錯誤等級由日志和錯誤碼本身的釋義來決定。
錯誤碼為字元串類型，共 5 位，分成兩個部分：錯誤産生來源+四位數字編号。
錯誤碼不能直接輸出給使用者作為提示資訊使用。
說明：堆棧（stack_trace）、錯誤資訊(error_message)、錯誤碼（error_code）、提示資訊（user_tip）是一個有效關聯并互相轉義的和諧整體，但是請勿互相越俎代庖。
在擷取第三方服務錯誤碼時，向上抛出允許本系統轉義，由 C 轉為 B，并且在錯誤資訊上帶上原有的第三方錯誤碼。
結合錯誤碼設計原則、錯誤碼用途、規約建議，面向服務端日志的錯誤碼應該是如下形式。
錯誤碼分為一級宏觀錯誤碼、二級宏觀錯誤碼、三級宏觀錯誤碼。
反例：一個五位數字 12345，第 1 位是錯誤等級，第 2 位是錯誤來源，345 是編号，人的大腦不會主動地分辨每位數字的不同含義。
按照《手冊》的建議設計出的面向日志的錯誤碼定義共十三位（十位有意義，三位連接配接符），并且應該具有如下分類：
- 應用辨別，表示錯誤屬于哪個應用，三位數字。
- 功能域辨別，表示錯誤屬于應用中的哪個功能子產品，三位數字。
- 錯誤類型，表示錯誤屬于那種類型，一位字母。
- 錯誤編碼，錯誤類型下的具體錯誤，三位數字。
《手冊》還有一條是規定錯誤碼應該如何定義：
說明：錯誤産生來源分為 A/B/C，A 表示錯誤來源于使用者，比如參數錯誤，使用者安裝版本過低，使用者支付逾時等問題；B 表示錯誤來源于目前系統，往往是業務邏輯出錯，或程式健壯性差等問題；C 表示錯誤來源于第三方服務，比如 CDN 服務出錯，消息投遞逾時等問題；四位數字編号從 0001 到 9999，大類之間的步長間距預留 100。
五位錯誤碼的好處是易記，但是對于面向日志的錯誤碼場景利用錯誤碼制作需要分類的業務監控大盤将變得比較困難，比如統計應用 A 的功能 B 的錯誤出現次數。
同樣在系統間傳遞這個類型的錯誤碼非常有可能發生錯誤碼沖突。
當然對于分為四段的錯誤碼同樣尤其不好的一面，應用辨別和功能域辨別需要有專人去管理或者開發一個錯誤碼管理工具，否則時間一長很容易産生定義的混亂形成破窗。
《手冊》對于錯誤碼定義我認為非常适合面向外部傳遞的錯誤碼。簡單、易記、是大家熟悉的錯誤碼樣式，并且透出的錯誤碼數量是非常有限的。
不用枚舉定義錯誤碼
國際化支援是一個不使用枚舉定義錯誤碼很重要的理由。
我們通過 i18n 的支援可以做到錯誤碼、錯誤狀态、錯誤描述的管理。
五 面向外部傳遞的錯誤碼
面向外部傳遞的錯誤碼是為了把域内的錯誤資訊傳遞出去。
可以讓域外系統通過錯誤碼進行錯誤碼進行後續的動作或是中斷操作或是記錄日志繼續執行。
可以讓前端通過錯誤碼給出使用者準确的錯誤提示或者忽略錯誤進行重試。
根據《手冊》給出的錯誤碼定義建議設計出的面向外部傳遞的錯誤碼共五位，并且有如下分類：
- 錯誤類型，表示錯誤來源，一位字母。
- 錯誤編碼，表示具體錯誤，四位數字。
錯誤碼的後三位編号與 HTTP 狀态碼沒有任何關系。
反例：一個五位數字 12345，第1位是錯誤等級，第 2 位是錯誤來源，345 是編号，人的大腦不會主動地分辨每位數字的不同含義。
下圖是《手冊》給出的錯誤碼示例：
他山之石
他山之石不一定能攻玉。
谷歌 API 錯誤碼定義
谷歌 API 的錯誤碼定義與 HTTP 狀态碼有着非常強的聯系，并且是一個全數字錯誤碼定義。
沒有明顯的錯誤分類，快速識别和自解釋能力比較弱。
騰訊 OpenAPI（文智）錯誤碼定義
這也是一個全數字的錯誤碼，沒有明确的分類字段，純數字的某一位已看不出明顯的分類。
不利于進行感性記憶。
微網誌 API 錯誤碼定義
同樣是全數字的錯誤碼定義：
其他建議
《手冊》中有一條建議：
全部正常，但不得不填充錯誤碼時傳回五個零：00000。
這也是在其他家 API 錯誤碼中能夠看到的定義。
參考
《阿裡巴巴java開發手冊》
《Google API Design Guide 》（
https://www.bookstack.cn/books/API-design-guide）
《阿裡雲-檔案存儲-錯誤碼》（
https://help.aliyun.com/document_detail/62603.html《微網誌開放平台-API-錯誤碼》（
https://open.weibo.com/wiki/Help/error《騰訊開放平台-錯誤碼》（
https://wiki.open.qq.com/wiki/%E9%94%99%E8%AF%AF%E7%A0%81