REST API出錯響應的設計（轉）

REST API應用很多，一方面提供公共API的平台越來越多，比如微網誌、微信等；一方面移動應用盛行，為Web端、Android端、IOS端、PC端，搭建一個統一的背景，以REST API的形式提供服務，也成為常見的開發模式。隻是一個服務做得久了，就發現API的接口設計，如果能在一開始就好好設計一下，實在是功德無量的事。讨論API接口設計的文章已有不少，本文重點談一談當請求處理出現異常的時候，出錯響應的内容和格式的設計。

比較自然的想法是，當有錯誤發生時，在響應中設定恰當的HTTP Status Code來指明這次請求是因為什麼出錯的。因為HTTP協定的标準性，絕大多數用戶端可以了解收到的HTTP狀态碼，進而帶來一緻的體驗。

但是，HTTP協定不可能定義出所有的出錯可能，滿足各種各樣的服務的需求。事實上，用來表示請求出錯的HTTP狀态碼隻有24個，其中有18個4xx狀态碼用來表示用戶端錯誤，6個5xx妝台碼用來表示服務端錯誤。作為API的提供者，我們當然希望能夠盡可能的規範我們的出錯資訊，提供更多的資訊給調用者。因為API使用起來越是友善簡單，客戶就越有可能繼續使用我們提供的服務，同時，當出現問題需要排查的時候，我們的工作也更加容易。

下面這個出錯傳回，列出了我認為錯誤資訊裡應當包含的内容。

{
    "status": 404,
    "code": 40483,
    "message": "Oops! It looks like that file does not exist.",
    "developerMessage": "File resource for path /uploads/foobar.txt does not exist.  Please wait 10 minutes until the upload batch completes before checking again.",
    "moreInfo": "http://www.mycompany.com/errors/40483",
    "requestId": "x3kdsa32k23ds32e"
}      

status

Status的内容與HTTP狀态碼内容相同，這個字段的存在，使得錯誤資訊自包含，用戶端隻需要解析HTTP響應的body部分，就可以擷取所有跟這次出錯相關的資訊。

code

自定義錯誤碼。自定義錯誤碼的長度和個數都可以自己定義，這樣就突破了HTTP狀态碼的個數限制。例子中的錯誤碼是40483，其中404代表了請求的資源不存在，而83則制定了這次出錯，具體是哪一種資源不存在。

message

使用者可了解的錯誤資訊，應當根據使用者的locale資訊傳回對應語言的版本。這個錯誤資訊意在傳回給使用用戶端的使用者閱讀，不應該包含任何技術資訊。有了這個字段，用戶端的開發者在出錯時，能夠展示恰當的資訊給最終使用者。

developerMessage

該出錯的詳細技術資訊，提供給用戶端的開發者閱讀。可以包含Exception的資訊、StackTrace，或者其它有用的技術資訊。

moreInfo

給出一個URL，用戶端開發站通路這個URL可以看到更詳細的關于該種出錯資訊的描述。在該URL展示的網頁中，可以包含該出錯資訊的定義，産生原因，解決辦法等等。

requestId

請求ID，服務為每一個請求唯一生成一個請求ID，當用戶端開發者無法自助解決問題時，可以聯絡服務開發者，同時提供該請求ID。一個好的服務，服務開發者應當可以根據此ID，定位到該次請求的所有相關log，進而定位問題，解決問題。

Reference

​​https://stormpath.com/blog/spring-mvc-rest-exception-handling-best-practices-part-1/​​