對于錯誤碼的設(shè)計，不同的開發(fā)團(tuán)隊有不同的風(fēng)格習(xí)慣。本文分享阿里文娛技術(shù)專家長統(tǒng)對于錯誤碼的看法，希望從錯誤碼使用的不同場景討論得到一個合理的錯誤碼規(guī)約，得到一個面向日志錯誤碼標(biāo)準(zhǔn)和一個面向外部傳遞的錯誤碼標(biāo)準(zhǔn)。

一 前言

在工作中，接觸過不少外部接口，其中包括：支付寶，微信支付，微博開發(fā)平臺，阿里云等等。每家公司錯誤碼風(fēng)格都不盡相同，有使用純數(shù)字的，有使用純英文的，也有使用字母和數(shù)字組合的。也接觸過很多內(nèi)部系統(tǒng)，錯誤碼設(shè)計也不盡相同。

錯誤碼的輸出路徑

面向日志輸出

• 服務(wù)內(nèi)傳遞，最終是輸出到日志。
• 域內(nèi)服務(wù)間，比如同時大麥電商之間的系統(tǒng)，最終目的是輸出到日志。

面向外部傳遞

• 域內(nèi)向域外
• 服務(wù)端傳遞到前端
• OpenAPI 錯誤碼
• 內(nèi)部不同域之間

錯誤碼使用場景

• 通過錯誤碼配置監(jiān)控大盤。
• 通過日志進(jìn)行問題排查，快速定位問題。
• 后端服務(wù)之間錯誤碼傳遞。
• 前端展示的錯誤提示/OpenAPI。

本文希望從錯誤碼使用的不同場景討論得到一個合理的錯誤碼規(guī)約，得到一個面向日志錯誤碼標(biāo)準(zhǔn)和一個面向外部傳遞的錯誤碼標(biāo)準(zhǔn)。

PS：本文引用全部引自阿里巴巴《Java 開發(fā)手冊》，下稱《手冊》。

二 什么是錯誤碼

錯誤碼要回答的最根本的問題是，誰的錯?錯在哪?

那么一個錯誤能表示出誰的錯和錯在哪里就是一個好的錯誤碼嗎?答案顯然是否定的，這個標(biāo)準(zhǔn)太基礎(chǔ)了。

• 好的錯誤碼必須能夠快速知曉錯誤來源。
• 好的錯誤碼必須易于記憶和對比。
• 好的錯誤碼必須能夠脫離文檔和系統(tǒng)平臺達(dá)到線下輕量溝通的目的(這個要求比較高)。

引自《手冊》- 異常日志-錯誤碼

錯誤碼的制定原則：快速溯源、簡單易記、溝通標(biāo)準(zhǔn)化。

說明：錯誤碼想得過于完美和復(fù)雜，就像康熙字典中的生僻字一樣，用詞似乎精準(zhǔn)，但是字典不容易隨身攜帶并且簡單易懂。

正例：錯誤碼回答的問題是誰的錯?錯在哪?

1)錯誤碼必須能夠快速知曉錯誤來源，可快速判斷是誰的問題。

2)錯誤碼易于記憶和比對(代碼中容易 equals)。

3)錯誤碼能夠脫離文檔和系統(tǒng)平臺達(dá)到線下輕量化地自由溝通的目的。

這個原則寫在異常日志-錯誤碼這個章節(jié)，我認(rèn)為同樣適用在面向用戶的錯誤碼。

??

三 錯誤碼規(guī)范

錯誤碼定義要有字母也要有數(shù)字

純數(shù)字錯誤碼

錯誤碼即人性，感性認(rèn)知+口口相傳，使用純數(shù)字來進(jìn)行錯誤碼編排不利于感性記憶和分類。

說明：數(shù)字是一個整體，每位數(shù)字的地位和含義是相同的。

反例：一個五位數(shù)字 12345，第1位是錯誤等級，第 2 位是錯誤來源，345 是編號，人的大腦不會主動地分辨每位數(shù)字的不同含義。

《手冊》說明了純數(shù)字錯誤碼存在的問題。

純字母錯誤碼

那么純字母錯誤碼不香嗎?有兩個問題：

• 對于使用漢語的我們用英語去準(zhǔn)確描述一個錯誤有時是比較困難的。
• 純英文字母的錯誤碼不利于排序。

錯誤碼盡量有利于不同文化背景的開發(fā)者進(jìn)行交流與代碼協(xié)作。

說明：英文單詞形式的錯誤碼不利于非英語母語國家(如阿拉伯語、希伯來語、俄羅斯語等)之間的開發(fā)者互相協(xié)作。

快速溯源 | 簡單易記 | 溝通標(biāo)準(zhǔn)化

什么是快速溯源?就是一眼看上去就知道哪里出了什么問題。

李雷負(fù)責(zé) A 服務(wù)，韓梅梅負(fù)責(zé) B 服務(wù)。韓梅梅發(fā)現(xiàn)服務(wù) B 出現(xiàn)了一個錯誤碼，韓梅梅能夠快速定位這是服務(wù) A 的內(nèi)部業(yè)務(wù)異常造成的問題，這個時候韓梅梅就可以拿著錯誤碼找到李雷說，"hi，Li Lei，How old are you。(李雷，怎么老是你)"。李雷拿過來錯誤碼一看，內(nèi)心萬馬奔騰，一下就能知道這是上游 Polly 負(fù)責(zé)的應(yīng)用阿爾法出了錯。

怎么能達(dá)到這個效果呢?

• 首先要有一套標(biāo)準(zhǔn)并且在域內(nèi)各個業(yè)務(wù)都在用同樣的標(biāo)準(zhǔn)。
• 其次要求錯誤碼有自我解釋的能力是有信息含量的有意義。
• 最后在域內(nèi)要傳遞錯誤碼。

錯誤碼標(biāo)準(zhǔn)的意義

開宗明義借用了《手冊》對于錯誤碼定義的原則作為錯誤碼規(guī)范能夠給我們帶來的收益。我想再次強(qiáng)調(diào)并且試著從反面闡述沒有錯誤碼標(biāo)準(zhǔn)會帶來的成本。

錯誤碼是用來做溝通的：系統(tǒng)與系統(tǒng)間的溝通，人與人間的溝通，人與系統(tǒng)間的溝通。

試想下面這個場景：

韓梅梅看到一個異常日志其中一個純數(shù)字的錯誤碼。

韓梅梅需要理解這串?dāng)?shù)字代表的是什么，它到底是不是一個錯誤碼，經(jīng)過幾秒鐘確定下來這是一個錯誤碼，但她不能確定這是不是本系統(tǒng)中錯誤碼，因為在她負(fù)責(zé)的系統(tǒng)是由韓梅梅、Lucy 和 Lily 三個人共同維護(hù)的，每個人都按照自己的理解定義了一套錯誤碼。

韓梅梅去系統(tǒng)源碼中查找這個錯誤碼，但是發(fā)現(xiàn)這個錯誤碼并不是本系統(tǒng)的錯誤碼。

然后再前翻兩頁后翻兩頁從日志上下文中確定這是李雷負(fù)責(zé)系統(tǒng)的錯誤碼，“Li Lie，how old are you?”。

韓梅梅把錯誤碼甩到李雷臉上，李雷一臉懵逼，這是我的系統(tǒng)的錯誤碼嗎?

李雷也不確定，因為李雷負(fù)責(zé)的系統(tǒng)是由李雷、林濤和 Jim 維護(hù)的，也是三人共同維護(hù)的。

李雷只好打開源碼，還真是!

上邊的場景經(jīng)過了發(fā)現(xiàn)-初判斷-判斷來源-確定來源-溝通-二次判斷-二次確認(rèn)七個步驟。

希望上邊的場景描述能夠說明沒有統(tǒng)一標(biāo)準(zhǔn)的錯誤所帶來的成本。

四 面向日志的錯誤碼

輸出到日志的錯誤碼有兩個用途：

• 用來快速溯源找到問題。
• 用來形成監(jiān)控大盤。

錯誤碼設(shè)計

《手冊》對于錯誤碼的建議有非常多的可取參考的地方：

錯誤碼不體現(xiàn)版本號和錯誤等級信息。

說明：錯誤碼以不斷追加的方式進(jìn)行兼容。錯誤等級由日志和錯誤碼本身的釋義來決定。

錯誤碼為字符串類型，共 5 位，分成兩個部分：錯誤產(chǎn)生來源+四位數(shù)字編號。

錯誤碼不能直接輸出給用戶作為提示信息使用。

說明：堆棧(stack_trace)、錯誤信息(error_message)、錯誤碼(error_code)、提示信息(user_tip)是一個有效關(guān)聯(lián)并互相轉(zhuǎn)義的和諧整體，但是請勿互相越俎代庖。

在獲取第三方服務(wù)錯誤碼時，向上拋出允許本系統(tǒng)轉(zhuǎn)義，由 C 轉(zhuǎn)為 B，并且在錯誤信息上帶上原有的第三方錯誤碼。

結(jié)合錯誤碼設(shè)計原則、錯誤碼用途、規(guī)約建議，面向服務(wù)端日志的錯誤碼應(yīng)該是如下形式。

錯誤碼分為一級宏觀錯誤碼、二級宏觀錯誤碼、三級宏觀錯誤碼。

錯誤碼即人性，感性認(rèn)知+口口相傳，使用純數(shù)字來進(jìn)行錯誤碼編排不利于感性記憶和分類。

說明：數(shù)字是一個整體，每位數(shù)字的地位和含義是相同的。

反例：一個五位數(shù)字 12345，第 1 位是錯誤等級，第 2 位是錯誤來源，345 是編號，人的大腦不會主動地分辨每位數(shù)字的不同含義。

按照《手冊》的建議設(shè)計出的面向日志的錯誤碼定義共十三位(十位有意義，三位連接符)，并且應(yīng)該具有如下分類：

• 應(yīng)用標(biāo)識，表示錯誤屬于哪個應(yīng)用，三位數(shù)字。
• 功能域標(biāo)識，表示錯誤屬于應(yīng)用中的哪個功能模塊，三位數(shù)字。
• 錯誤類型，表示錯誤屬于那種類型，一位字母。
• 錯誤編碼，錯誤類型下的具體錯誤，三位數(shù)字。

??

《手冊》還有一條是規(guī)定錯誤碼應(yīng)該如何定義：

錯誤碼為字符串類型，共 5 位，分成兩個部分：錯誤產(chǎn)生來源+四位數(shù)字編號。

說明：錯誤產(chǎn)生來源分為 A/B/C，A 表示錯誤來源于用戶，比如參數(shù)錯誤，用戶安裝版本過低，用戶支付超時等問題;B 表示錯誤來源于當(dāng)前系統(tǒng)，往往是業(yè)務(wù)邏輯出錯，或程序健壯性差等問題;C 表示錯誤來源于第三方服務(wù)，比如 CDN 服務(wù)出錯，消息投遞超時等問題;四位數(shù)字編號從 0001 到 9999，大類之間的步長間距預(yù)留 100。

五位錯誤碼的好處是易記，但是對于面向日志的錯誤碼場景利用錯誤碼制作需要分類的業(yè)務(wù)監(jiān)控大盤將變得比較困難，比如統(tǒng)計應(yīng)用 A 的功能 B 的錯誤出現(xiàn)次數(shù)。

同樣在系統(tǒng)間傳遞這個類型的錯誤碼非常有可能發(fā)生錯誤碼沖突。

當(dāng)然對于分為四段的錯誤碼同樣尤其不好的一面，應(yīng)用標(biāo)識和功能域標(biāo)識需要有專人去管理或者開發(fā)一個錯誤碼管理工具，否則時間一長很容易產(chǎn)生定義的混亂形成破窗。

《手冊》對于錯誤碼定義我認(rèn)為非常適合面向外部傳遞的錯誤碼。簡單、易記、是大家熟悉的錯誤碼樣式，并且透出的錯誤碼數(shù)量是非常有限的。

不用枚舉定義錯誤碼

國際化支持是一個不使用枚舉定義錯誤碼很重要的理由。

我們通過 i18n 的支持可以做到錯誤碼、錯誤狀態(tài)、錯誤描述的管理。

五 面向外部傳遞的錯誤碼

面向外部傳遞的錯誤碼是為了把域內(nèi)的錯誤信息傳遞出去。

可以讓域外系統(tǒng)通過錯誤碼進(jìn)行錯誤碼進(jìn)行后續(xù)的動作或是中斷操作或是記錄日志繼續(xù)執(zhí)行。

可以讓前端通過錯誤碼給出用戶準(zhǔn)確的錯誤提示或者忽略錯誤進(jìn)行重試。

錯誤碼設(shè)計

根據(jù)《手冊》給出的錯誤碼定義建議設(shè)計出的面向外部傳遞的錯誤碼共五位，并且有如下分類：

• 錯誤類型，表示錯誤來源，一位字母。
• 錯誤編碼，表示具體錯誤，四位數(shù)字。

??

錯誤碼的后三位編號與 HTTP 狀態(tài)碼沒有任何關(guān)系。

錯誤碼即人性，感性認(rèn)知+口口相傳，使用純數(shù)字來進(jìn)行錯誤碼編排不利于感性記憶和分類。

說明：數(shù)字是一個整體，每位數(shù)字的地位和含義是相同的。

反例：一個五位數(shù)字 12345，第1位是錯誤等級，第 2 位是錯誤來源，345 是編號，人的大腦不會主動地分辨每位數(shù)字的不同含義。

下圖是《手冊》給出的錯誤碼示例：

??

他山之石

他山之石不一定能攻玉。

谷歌 API 錯誤碼定義

谷歌 API 的錯誤碼定義與 HTTP 狀態(tài)碼有著非常強(qiáng)的聯(lián)系，并且是一個全數(shù)字錯誤碼定義。

沒有明顯的錯誤分類，快速識別和自解釋能力比較弱。

??

騰訊 OpenAPI(文智)錯誤碼定義

這也是一個全數(shù)字的錯誤碼，沒有明確的分類字段，純數(shù)字的某一位已看不出明顯的分類。

不利于進(jìn)行感性記憶。

??

微博 API 錯誤碼定義

同樣是全數(shù)字的錯誤碼定義：

??

其他建議

《手冊》中有一條建議：

全部正常，但不得不填充錯誤碼時返回五個零：00000。

這也是在其他家 API 錯誤碼中能夠看到的定義。

參考

《阿里巴巴java開發(fā)手冊》《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)