HTTP 的業(yè)務(wù)錯誤碼

Http 定義了 5大類別的錯誤碼，這些錯誤碼是通用的，其中只有 5XX 是表示后臺服務(wù)的錯誤。各個系統(tǒng)的后端服務(wù)的用途/業(yè)務(wù)相差甚遠(yuǎn)，為數(shù)不多 5XX 遠(yuǎn)遠(yuǎn)不夠用來表示可能出現(xiàn)的各種情況。于是，后端系統(tǒng)需要根據(jù)自己的業(yè)務(wù)制定業(yè)務(wù)級別的錯誤碼，而 Http 的錯誤碼，我們稱其為協(xié)議級別的錯誤碼。

1. 業(yè)務(wù)碼格式

業(yè)務(wù)碼不屬于 Http 協(xié)議的成員，是實踐中的產(chǎn)物。它是定義在返回的消息實體中的，并沒有固定的格式，但無非就是下面3種模塊。

【錯誤級別（可選）】-【功能模塊（必要）】-【具體錯誤編號（必要）】

錯誤碼一般由 5～6 位整數(shù)組成，例子如下：

2. 出參格式

出參的格式主要有2種

1. 不管成功失敗都是固定的字段。
2. 成功了只返回業(yè)務(wù)實體對象，失敗了只返回錯誤信息。

2.1 固定出參

2.1.1 成功

{
	"code":0,	# 0 表示成功
	"msg":"success"	# success
	"data":{
		“name”:"鞋子"，
		"inventory":1000
	}
}

2.1.2失敗

{
	"code":10001,	# 錯誤碼
	"msg":"庫存不足"	# 錯誤描述信息
	"data":{}		# 業(yè)務(wù)實體
}

2.2 不固定出參

2.2.1 成功

{
	“name”:"鞋子"，
	"inventory":1000
}

2.2.2 失敗

{
	"code":10001,	# 錯誤碼
	"msg":"庫存不足"	# 錯誤描述信息
}

我本人是比較推崇第二種格式，因為大部分情況下都是成功，每次又要帶上 code，msg 沒有實質(zhì)性的作用，還占用帶寬。另一個是接口文檔的書寫方面，每個接口把 code，msg 帶上會覺得很麻煩，不帶上又怕不熟悉的人看了出錯。一個比較友好規(guī)范的接口文檔，我認(rèn)為應(yīng)該是由成功和失敗2個獨(dú)立的部分組成，正常的業(yè)務(wù)出入?yún)⒎懦晒φ故荆〉挠袑ｉT的錯誤碼表查詢。

3. 國際化

國際化的功能離不開錯誤碼的支持，客戶端指定語言到服務(wù)端去請求，當(dāng)出錯了服務(wù)端會根據(jù)錯誤碼和語言找到對應(yīng)的國際化提示語。

從上面圖中我們發(fā)現(xiàn)，錯誤碼不僅僅是客戶端與服務(wù)端的交互，后臺各個服務(wù)間的交互也需要約定的一套錯誤碼。

1. 一般一個系統(tǒng)的錯誤碼 code 都是唯一確定的。
2. msg 不同場景下可能不一樣，提供給用戶的肯定是需要友好且不能暴露底層細(xì)節(jié)，給開發(fā)人員看的就要詳細(xì)專業(yè)的錯誤內(nèi)容。
3. 網(wǎng)關(guān)服務(wù)上面維護(hù)著多套不同語言的錯誤碼提示語，響應(yīng)的時候會根據(jù)客戶端帶的 Lang 信息進(jìn)行國際化轉(zhuǎn)譯。

一般國際化的系統(tǒng)中會有多份 xxx_lang.properties文件，每一份代表一種語言的消息提示語。中文一般會轉(zhuǎn)為 Unicode 編碼進(jìn)行存儲（這個過程一般開發(fā)工具可以設(shè)置自動轉(zhuǎn)），這樣的處理可以規(guī)避不同開發(fā)環(huán)境下不同編碼導(dǎo)致中文亂碼。

4. 行業(yè)案例

接口有的是寫給小組內(nèi)部開發(fā)人員交流使用的，有的是對外開放給第三方調(diào)用的，接口文檔是程序之間交互的橋梁。支付寶 / 微信 的接口是開發(fā)人員使用度比較廣的第三方接口，我們經(jīng)常會去調(diào)用他們的支付，小程序相關(guān)的接口，下面著重看看他們的錯誤碼是如何定義的。

4.1 支付寶

1. 在獨(dú)立的頁面維護(hù)了 公共錯誤碼

• code 是 5 位整數(shù)。
• 明細(xì)的錯誤碼 sub_code 是用字母表示的，他這邊 code 相當(dāng)于一個大類，大類下面又有明細(xì)的小類。
• 解決方案是給用戶的提示語。

2. 業(yè)務(wù)接口詳細(xì)列舉了成功和錯誤的參數(shù) 業(yè)務(wù)接口

• 所有出入?yún)⒍加性敿?xì)說明，包括示例。
• 成功和失敗都有固定返回 code msg 字段。

4.2 微信

1. 獨(dú)立的頁面維護(hù)了全局 錯誤碼

• 錯誤碼由5位整數(shù)構(gòu)成

2. 每個接口一個獨(dú)立的 參數(shù)說明頁面

• 正常情況下出參只返回業(yè)務(wù)實體
• 異常情況才有 errCode errMsg
• 每個接口下也可能有自己的業(yè)務(wù)錯誤碼
  

5. 小結(jié)

錯誤碼是接口文檔中很重要的一部分，它是 Http 協(xié)議碼的補(bǔ)充，錯誤碼并沒有固定的格式要求，但是一般由 業(yè)務(wù)模塊+模塊下的詳細(xì)錯誤信息 組成。此外，還需要根據(jù)場景定義錯誤場景下的消息提示符，可以根據(jù)客戶端的語言返回相應(yīng)語言的提示符。給用戶的錯誤信息中也盡量避免過多展示底層實現(xiàn)細(xì)節(jié)，減小系統(tǒng)風(fēng)險暴露。