HTTP 的業(yè)務錯誤碼

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

1. 業(yè)務碼格式

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

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

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

2. 出參格式

出參的格式主要有2種

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

2.1 固定出參

2.1.1 成功

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

2.1.2失敗

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

2.2 不固定出參

2.2.1 成功

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

2.2.2 失敗

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

我本人是比較推崇第二種格式，因為大部分情況下都是成功，每次又要帶上 code，msg 沒有實質性的作用，還占用帶寬。另一個是接口文檔的書寫方面，每個接口把 code，msg 帶上會覺得很麻煩，不帶上又怕不熟悉的人看了出錯。一個比較友好規(guī)范的接口文檔，我認為應該是由成功和失敗2個獨立的部分組成，正常的業(yè)務出入參放成功展示，失敗的有專門的錯誤碼表查詢。

3. 國際化

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

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

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

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

4. 行業(yè)案例

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

4.1 支付寶

1. 在獨立的頁面維護了 公共錯誤碼

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

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

• 所有出入參都有詳細說明，包括示例。
• 成功和失敗都有固定返回 code msg 字段。

4.2 微信

1. 獨立的頁面維護了全局 錯誤碼

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

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

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

5. 小結

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