簡介
隨著移動開發和前端開發的崛起，越來越多的 Web 後端應用都傾向於實現 Restful API。
Restful API 是一個簡單易用的前後端分離方案，它只需要對客戶端請求進行處理，然後返回結果即可， 無需考慮頁面渲染，一定程度上減輕了後端開發人員的負擔。
然而，正是由於 Restful API 不需要考慮頁面渲染，導致它不能在頁面上展示錯誤資訊。
那就意著當出現錯誤的時候，它只能通過返回一個錯誤的響應，來告訴使用者和開發者相應的錯誤資訊，提示他們接下來應該怎麼辦。
本文將討論 Restful API 中的錯誤處理方案。
設計錯誤資訊
當 Restful API 需要丟擲錯誤的時候，我們要考慮的是：這個錯誤應該包含哪些資訊。
我們先看看 Github, Google, Facebook, Twitter, Twilio 的錯誤資訊是怎樣的。
Github (use http status)
{
"message": "Validation Failed",
"errors": [
{
"resource": "Issue",
"field": "title",
"code": "missing_field"
}
]
}Google (use http status)
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientFilePermissions",
"message": "The user does not have sufficient permissions for file {fileId}."
}
],
"code": 403,
"message": "The user does not have sufficient permissions for file {fileId}."
}
}Facebook (use http status)
{
"error": {
"message": "Message describing the error",
"type": "OAuthException",
"code": 190,
"error_subcode": 460,
"error_user_title": "A title",
"error_user_msg": "A message",
"fbtrace_id": "EJplcsCHuLu"
}
}Twitter (use http status)
{
"errors": [
{
"message": "Sorry, that page does not exist",
"code": 34
}
]
}Twilio (use http status)
{
"code": 21211,
"message": "The 'To' number 5551234567 is not a valid phone number.",
"more_info": "https://www.twilio.com/docs/errors/21211",
"status": 400
}觀察這些結構可以發現它們都有一些共同的地方：
- 都利用了 Http 狀態碼
- 有些返回了業務錯誤碼
- 都提供了給使用者看的錯誤提示資訊
- 有些提供了給開發者看的錯誤資訊
Http 狀態碼
在 Restful API 中利用 Http 狀態碼來表明錯誤型別再合適不過了，因為 Http 狀態碼定義了很多抽象的錯誤型別。
雖然 Http 狀態碼定義了非常多的錯誤型別，但實際應用中，我們常用的狀態碼並不多，通常都是下面這幾方面：
- API 正常工作 (200, 201)
- 客戶端錯誤 (400, 401, 403, 404)
- 服務端錯誤 (500, 503)
業務錯誤碼
很多時候，我們根據業務型別來自定義錯誤碼。
這些業務錯誤碼與 Http 狀態碼並不重疊，這時候我們可以返回業務錯誤碼，用來提示使用者/開發者錯誤型別。
給使用者看的錯誤資訊
當出現錯誤的時候，我們需要提示使用者如何處理這種情況，通常這種錯誤資訊都是必須的。
可以看到上面幾個例子中都有返回給使用者看的錯誤資訊。
給開發者看的錯誤資訊
若我們的 API 需要開放給第三方開發者，那麼我們就需要考慮返回一些給開發者看的錯誤資訊。
設計錯誤型別
我們剛才提到過，可以利用 Http 狀態碼來為錯誤型別進行分類。
通常我們所說的分類通常是對客戶端錯誤進行分類， 即 4xx 型別的錯誤。
而這些錯誤型別中，我們最常用的是：
- 400 Bad Request
由於包含語法錯誤，當前請求無法被伺服器理解。除非進行修改，否則客戶端不應該重複提交這個請求。
通常在請求引數不合法或格式錯誤的時候可以返回這個狀態碼。
- 401 Unauthorized
當前請求需要使用者驗證。
通常在沒有登入的狀態下訪問一些受保護的 API 時會用到這個狀態碼。
- 403 Forbidden
伺服器已經理解請求，但是拒絕執行它。與401響應不同的是，身份驗證並不能提供任何幫助。
通常在沒有許可權操作資源時(如修改/刪除一個不屬於該使用者的資源時)會用到這個狀態碼。
- 404 Not Found
請求失敗，請求所希望得到的資源未被在伺服器上發現。
通常在找不到資源時返回這個狀態碼。
儘管我們可以通過 Http 狀態碼來表示錯誤的型別，
但在實際應用中，如果僅僅使用 Http 狀態碼的話，我們的程式碼中就遍佈 Http 狀態碼：
// Node.js
if (!res.body.title) {
res.statusCode = 400
}
if (!user) {
res.statusCode = 401
}
if (!post) {
res.statusCode = 404
}上面的實現方式在小專案中還可以接受，當專案變大、需求變多的時候，維護起來就變得很麻煩了。
為了提高錯誤的可讀性和可維護性，我們需要對各種錯誤進行分類。
我個人習慣把錯誤分成以下幾種型別：
- 格式錯誤 (FORMAT_INVALID)
- 資料不存在 (DATA_NOT_FOUND)
- 資料已存在 (DATA_EXISTED)
- 資料無效 (DATA_INVALID)
- 登入錯誤 (LOGIN_REQUIRED)
- 許可權不足 (PERMISSION_DENIED)
錯誤分類之後，我們拋錯誤的時候就變得更加直觀了：
if (!res.body.title) {
throw new Error(ERROR.FORMAT_INVALID)
}
if (!user) {
throw new Error(ERROR.LOGIN_REQUIRED)
}
if (!post) {
throw new Error(ERROR.DATA_NOT_FOUND)
}
if (post.creator.id !== user.id) {
throw new Error(ERROR.PERMISSION_DENIED)
}這種形式比上面的寫死狀態碼的方式方便很多，而且維護起來也更加簡單。
但有一個問題，就是不能根據錯誤型別來返回指定的錯誤資訊。
自定義錯誤型別
要實現根據錯誤型別來返回指定的錯誤資訊，我們可以通過自定義錯誤的方式來實現。
假設我們自定義錯誤的結構如下：
{
"type": "",
"code": 0,
"message": "",
"detail": ""
}我們需要做到如下幾點：
- 根據錯誤型別來自動設定
type,code,message
detail為可選項，用來描述該錯誤的具體原因
const ERROR = {
FORMAT_INVALID: 'FORMAT_INVALID',
DATA_NOT_FOUND: 'DATA_NOT_FOUND',
DATA_EXISTED: 'DATA_EXISTED',
DATA_INVALID: 'DATA_INVALID',
LOGIN_REQUIRED: 'LOGIN_REQUIRED',
PERMISSION_DENIED: 'PERMISSION_DENIED'
}
const ERROR_MAP = {
FORMAT_INVALID: {
code: 1,
message: 'The request format is invalid'
},
DATA_NOT_FOUND: {
code: 2,
message: 'The data is not found in database'
},
DATA_EXISTED: {
code: 3,
message: 'The data has exist in database'
},
DATA_INVALID: {
code: 4,
message: 'The data is invalid'
},
LOGIN_REQUIRED: {
code 5,
message: 'Please login first'
},
PERMISSION_DENIED: {
code: 6,
message: 'You have no permission to operate'
}
}
class CError extends Error {
constructor(type, detail) {
super()
Error.captureStackTrace(this, this.constructor)
let error = ERROR_MAP[type]
if (!error) {
error = {
code: 999,
message: 'Unknow error type'
}
}
this.name = 'CError'
this.type = error.code !== 999 ? type : 'UNDEFINED'
this.code = error.code
this.message = error.message
this.detail = detail
}
}自定義好錯誤之後，我們呼叫起來就更加簡單了：
// in controller
if (!user) {
throw new CError(ERROR.LOGIN_REQUIRED, 'You should login first')
}
if (!req.body.title) {
throw new CError(ERROR.FORMAT_INVALID, 'Title is required')
}
if (!post) {
throw new CError(ERROR.DATA_NOT_FOUND, 'The post you required is not found')
}最後，還剩下一個問題，根據錯誤型別來設定狀態碼，然後返回錯誤資訊給客戶端。
捕獲錯誤資訊
在 Controller 中丟擲自定義錯誤後，我們需要捕獲該錯誤，才能返回給客戶端。
假設我們使用 koa 2 作為 web 框架來開發 restful api，那麼我們要做的是新增錯誤處理的中介軟體:
module.exports = async function errorHandler (ctx, next) {
try {
await next()
} catch (err) {
let status
switch (err.type) {
case ERROR.FORMAT_INVALID:
case ERROR.DATA_EXISTED:
case ERROR.DATA_INVALID:
status = 400
break
case ERROR.LOGIN_REQUIRED:
status = 401
case ERROR.PERMISSION_DENIED:
status = 403
case ERROR.DATA_NOT_FOUND:
status = 404
break
default:
status = 500
}
ctx.status = status
ctx.body = err
}
}
// in app.js
app.use(errorHandler)
app.use(router.routes())通過這種方式，我們就能優雅地處理 Restful API 中的錯誤資訊了。
參考資料
https://zh.wikipedia.org/zh-hans/HTTP%E7%8A%B6%E6%80%81%E7%A0%81
https://www.loggly.com/blog/node-js-error-handling/
http://blog.restcase.com/rest-api-error-codes-101/
https://apigee.com/about/blg/technology/restful-api-design-what-about-errors
http://stackoverflow.com/questions/942951/rest-api-error-return-good-practices
http://goldbergyoni.com/checklist-best-practices-of-node-js-error-handling/
http://blogs.mulesoft.com/dev/api-dev/api-best-practices-response-handling/
https://developers.facebook.com/docs/graph-api/using-graph-api/#errors
https://developers.google.com/drive/v3/web/handle-errors
https://developer.github.com/v3/#client-errors
https://dev.twitter.com/overview/api/response-codes
https://www.twilio.com/docs/api/errors