前言

最近我司要制定開發(fā)規(guī)范斩郎。在討論接口返回的時(shí)候脑融，后端的同事詢問我們前端，錯(cuò)誤信息的返回缩宜，前端有什么意見肘迎？

所以做了一些調(diào)研給到后端的同事做參考。

錯(cuò)誤信息返回

在使用API時(shí)無可避免地會(huì)因?yàn)楦鞣N情況而導(dǎo)致接口返回錯(cuò)誤的信息锻煌。比如指定的query參數(shù)錯(cuò)誤妓布，又或者method不支持等，這些情況都會(huì)返回相關(guān)的錯(cuò)誤信息宋梧。另外服務(wù)器不穩(wěn)定或者停止運(yùn)行了匣沼，也必須將錯(cuò)誤信息返回。

顯然捂龄，當(dāng)錯(cuò)誤發(fā)生的時(shí)候释涛，只是籠統(tǒng)地返回“發(fā)生了錯(cuò)誤”是不行的。如果前端不了解發(fā)生了什么錯(cuò)誤跺讯，也就不知道該怎么去調(diào)試枢贿，怎么去修復(fù)這個(gè)bug。所以說刀脏，必須向前端返回盡可能多的信息局荚，以便前端找到出錯(cuò)的地方解決問題。

通過HTTP狀態(tài)碼表示出錯(cuò)信息

首先必須選擇合適的HTTP狀態(tài)碼愈污，之前我司的后端API沒有遵循這個(gè)規(guī)則耀态。例如API無論如何訪問，都會(huì)返回200狀態(tài)碼暂雹，只在返回消息體中的描述是否發(fā)生錯(cuò)誤首装。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "error": {
        "code": 2002,
        "message": "Invalid parameter"
    }
}

雖然這么處理前端也能理解API的錯(cuò)誤信息，但由于HTTP協(xié)議已經(jīng)完整地定義了各個(gè)狀態(tài)碼所表示的含義杭跪，所以返回恰當(dāng)?shù)臓顟B(tài)碼才能提高前端正確識(shí)別錯(cuò)誤的可能性仙逻。

如果出錯(cuò)了驰吓，仍然返回200狀態(tài)碼，有可能導(dǎo)致前端的處理發(fā)生混亂系奉，這種情況要一定要禁止檬贰。特別是通用的API，基本上都是先看狀態(tài)碼再?zèng)Q定下一步的處理缺亮，如果沒有返回正確的狀態(tài)碼翁涤，就會(huì)導(dǎo)致前端無法執(zhí)行適當(dāng)?shù)姆椒ㄈヌ幚恚瑥亩l(fā)各種不必要的問題萌踱。而且這種做法沒有盡可能地運(yùn)用HTTP協(xié)議葵礼，也給前端編寫錯(cuò)誤處理增加了難度。

• 狀態(tài)碼分類

下面主要來了解一下4xx和5xx的錯(cuò)誤碼：

4xx-前端發(fā)生了錯(cuò)誤

4xx的狀態(tài)碼主要是用于描述因前端請求的問題而引發(fā)的錯(cuò)誤并鸵，也就是說服務(wù)器端不存在出錯(cuò)問題鸳粉，但服務(wù)器端無法理解前端的請求，或者能理解但無法處理的請求能真。這一類的錯(cuò)誤赁严，統(tǒng)一使用4xx錯(cuò)誤碼扰柠。

5xx-服務(wù)器端發(fā)生錯(cuò)誤

5xx狀態(tài)碼表示錯(cuò)誤由服務(wù)器端的問題引發(fā)的。

向前端返回詳細(xì)的錯(cuò)誤信息

當(dāng)錯(cuò)誤發(fā)生時(shí)哗脖，除了需要返回相應(yīng)的狀態(tài)碼之外，還需要返回詳情的錯(cuò)誤信息扳还。因?yàn)闋顟B(tài)碼只是通用的描述錯(cuò)誤的類別才避，一般無法表示實(shí)際發(fā)生的具體錯(cuò)誤信息。

比如說400狀態(tài)碼氨距，只是知道前端請求發(fā)生了錯(cuò)誤桑逝，至于如何去修改，僅憑這個(gè)是沒有辦法找到bug的俏让。

通常來說：返回錯(cuò)誤信息的方法有兩種：

• 將信息放入HTTP響應(yīng)頭
• 將信息通過HTTP響應(yīng)體返回

1楞遏、通過自定義頭部茬暇，將詳細(xì)的錯(cuò)誤信息放入響應(yīng)頭中

X-ERROR-CODE: 2020
X-ERROR-MESSAGE: Bad authentication token
X-ERROR-INFO: http://api.example.com/v1/authentication

2、將錯(cuò)誤信息放入響應(yīng)體中

{
    "error": {
        "code": 2020,
        "message": "Bad authentication token",
        "info": "http://api.example.com/v1/authentication"
    }
}

從前端的角度來考慮寡喝，通過響應(yīng)體返回會(huì)更加容易處理而钞。

這里的錯(cuò)誤代碼的命名方式，按照后端自己的要求編寫即可拘荡。

通常情況下臼节，會(huì)要求接口的錯(cuò)誤信息越詳細(xì)越好，但這也不是一定的珊皿，也會(huì)有特殊情況网缝。
一般而言，前端會(huì)將后端接口的錯(cuò)誤信息原封不動(dòng)的顯示出來蟋定，因?yàn)榍岸撕茈y去判斷是否有涉密信息或者讓用戶難堪的信息粉臊。比如說A用戶屏蔽了B用戶，當(dāng)B用戶想看A用戶的詳情時(shí)驶兜，如果正確的返回：“A用戶已屏蔽B用戶扼仲，無法獲取”的話，會(huì)讓雙方都難堪抄淑。這時(shí)就需要返回模棱兩可的信息屠凶。這個(gè)就需要后端開發(fā)們自己去領(lǐng)悟。

針對默認(rèn)返回與API維護(hù)

某些接口在發(fā)生錯(cuò)誤時(shí)會(huì)將HTML返回肆资。特別是發(fā)生404矗愧、503等錯(cuò)誤時(shí)，這種情況就比較常見郑原。當(dāng)發(fā)生這些錯(cuò)誤時(shí)唉韭，用于構(gòu)建API的Web服務(wù)器或者app框架會(huì)直接返回出錯(cuò)信息，默認(rèn)情況下大都是HTML犯犁。

但雖說是發(fā)生了錯(cuò)誤属愤，前端依然在訪問中，所以仍然期待服務(wù)器返回約定好的格式酸役，比如JSON住诸。尤其在通過Accept請求頭部或擴(kuò)展名等指定了接收格式時(shí)。當(dāng)然可以讓前端去檢查Content_Type頭部簇捍，進(jìn)行相應(yīng)的處理只壳。但如果前端處理的不好或者沒有處理，可能會(huì)導(dǎo)致app崩潰暑塑。

尤其是公共api吼句，不能期望所有的使用者都嚴(yán)格遵循規(guī)范來處理好，這種api算不上了好的api事格。

關(guān)于API的維護(hù)惕艳，正常來說搞隐，要避免不得不停止API的發(fā)生。但特殊的時(shí)候也會(huì)不得不停止API進(jìn)行維護(hù)工作远搪，這種情況需要返回503狀態(tài)碼來告知前端當(dāng)前API已經(jīng)停止工作劣纲。另外，因?yàn)檫@種停止操作不是意外而是有計(jì)劃進(jìn)行的谁鳍，所以要有API何時(shí)重啟的時(shí)間信息癞季，將其發(fā)送給前端。

不僅要預(yù)備好用于定期維護(hù)的狀態(tài)碼和出錯(cuò)信息的返回倘潜，還要使用Retry-After頭部來告訴前端維護(hù)結(jié)束的時(shí)間绷柒。從SEO的角度來看，這個(gè)方式對普通的web站點(diǎn)的維護(hù)也同樣適用涮因，也是Google推薦的方法废睦。

Retry-After的值可以是某個(gè)具體的日期或從當(dāng)前時(shí)刻算起至可正常訪問為止所需的秒數(shù)。

503 Service Temporarily Unavailable
Retry-After: Mon, 9 Sep 2020 20:00:00 GMT 

從前端實(shí)現(xiàn)的角度來看养泡，在返回503錯(cuò)誤時(shí)嗜湃，是期待前端能識(shí)別出API地方Retry-After值指定的時(shí)間等待，然后在API重啟的時(shí)候再次訪問澜掩。

雖然這些處理都取決于前端的具體實(shí)現(xiàn)购披，后端無法對此進(jìn)行控制，但依然要盡可能地返回詳細(xì)的信息输硝，方便前端處理并提升用戶體驗(yàn)今瀑。

總結(jié)

主要是三個(gè)痛點(diǎn)：

• 必須選擇合適的HTTP狀態(tài)碼
• 向前端返回詳細(xì)的錯(cuò)誤信息
• 針對默認(rèn)返回與API維護(hù)

作者： zhangwinwin
鏈接：后端API接口的錯(cuò)誤信息返回規(guī)范
來源：github