Restful API 中的錯誤處理

alterem發表於2019-08-01
RESTAPI

簡介

隨著移動開發和前端開發的崛起，越來越多的 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

相關文章