API Gateway：錯誤碼映射外掛程式

1. 概述

錯誤碼映射外掛程式用於將後端應答中返回的非正常請求，映射為用戶端期望的錯誤應答的情境。

2. 快速開始

請先參考下面的例子，某後端的返回中，HTTP應答碼為200，但錯誤資訊包含在包體中JSON欄位中。

HTTP 200 OK
Content-Type:application/json

{"req_msg_id":"d02afa56394f4588832bed46614e1772","result_code":"ROLE_NOT_EXISTS"}

• 在這個情境中，用戶端期望得到非200的應答，但希望通過不修改後端的方式實現。

HTTP 404 
X-Ca-Error-Message: Role Not Exists, ResultId=d02afa56394f4588832bed46614e1772

針對描述的中的情境，我們可以按照如下方式配置錯誤碼映射外掛程式。

---
# 參與映射的欄位
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# 映射條件
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# 錯誤碼欄位
errorCode: "resultCode"
# 映射項
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# 預設映射（可選）
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

在這個例子中，我們將後端應答碼以及後端應答JSON包體中的result_code欄位設定為了應答條件，如果後端應答碼為200，但result_code欄位不等於'OK'時，開始執行錯誤碼映射，這個例子中，我們使用result_code作為錯誤碼欄位執行映射，配置了兩個錯誤碼：當ROLE_NOT_EXISTS會返回給用戶端404應答，而INVALID_PARAMETER會返回給用戶端400應答，其他錯誤碼返回500應答。

3. 外掛程式配置與映射規則

3.1. 外掛程式配置

錯誤映射外掛程式使用json或yaml格式配置，各個欄位的詳細說明如下：

• parameters（必選）: 下面配置參與映射的欄位，以map方式配置，參考文檔參數與條件運算式的使用。

• errorCondition（必選）: 應答是否屬於錯誤應答的條件運算式，當執行結果為true時，執行映射。

• errorCode（可選）: 用於指定錯誤碼欄位，用於匹配mappings映射列表中的code欄位。

• mappings（必選）: 用於指定映射記錄列表，網關將會用符合錯誤碼或錯誤條件記錄重新構造返回應答，詳細欄位為：

  • code（可選）: 唯一，設定這個欄位是codeParameter欄位為必選，當錯誤碼與code欄位一致時，執行當前映射記錄。

  • condition（可選）: 錯誤條件運算式，當運算式演算為true時，執行當前映射記錄。

  • statusCode（必選）: 用於指定當前映射記錄的HTTP返回碼。

  • errorMessage（可選）: 用於指定當前映射記錄的錯誤資訊，體現在應答的X-Ca-Error-Message頭及日誌的errorMessage欄位中。

  • responseHeaders（可選）: 以Map方式配置，用於設定當前映射記錄的應答頭。

  • responseBody（可選）: 用於覆寫當前映射記錄的應答包體。

• defaultMapping（可選）: 預設映射記錄，如果mappings中的所有記錄均未命中，則使用本條記錄作為應答。

  • statusCode（必選）: 用於指定當前映射記錄的HTTP返回碼。

  • errorMessage（可選）: 用於指定當前映射記錄的錯誤資訊，體現在應答的X-Ca-Error-Message頭及日誌的errorMessage欄位中。

  • responseHeaders（可選）: 以Map方式配置，用於設定當前映射記錄的應答頭。

  • responseBody（可選）: 用於覆寫當前映射記錄的應答包體。

配置規則：

• mappingCondition, mappings[].condition中的條件運算式使用的參數，與parameters欄位中定義的欄位必須對應，否則會報錯，關於參數定義與條件運算式，參考參數與條件運算式的使用文檔。

• errorCode欄位中使用的參數必須為parameters中定義的欄位。

• mappings列表記錄中的code與condition必須配置其中的一個，當配置code時，值必須唯一。當配置condition時，將按照配置順序執行，越靠前的優先順序越高。

• errorMessage、responseBody可以使用類似"${Code}: ${Message}"的格式對訊息進行模板替換，欄位取值來自parameters中提取到的值。

• responseHeaders的值，也可以使用${Message}的方式執行模板替換。

• responseBody不配置時，透傳後端應答。

• responseHeaders不配置時，透傳後端應答的Headers，否則使用配置索引值對覆蓋後端應答的Header，當值配置為''時，刪除對應的Header。

• defaultMapping沒有配置時，錯誤碼映射不生效，透傳後端應答。

3.2. 映射參數

映射參數可通過如下的方式在parameters參數中配置為索引值對，其中鍵作為變數名定義，值可以使用Location:Name的方式配置，表示從當前應答或系統內容相關的特定位置中讀取。

---
# 參與映射的欄位
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"

錯誤碼映射目前支援以下位置的參數，具體參數描述請參考參數與條件運算式的使用文檔。

• ErrorCode和ErrorMessage會返回API Gateway的系統錯誤碼與系統錯誤資訊，請參考錯誤碼表文檔。

• 使用BodyJsonField可以使用JSONPath來提取後端返回JSON的值，但如果後端應答的包體大小超過15360 Bytes則這個欄位將無法提取到值，得到的是空值null。

3.3. 執行規則

錯誤碼映射外掛程式會按照如下的順序執行：

1. 根據parameters中配置的參數列表，從應答及系統上下文中擷取當前的參數表。

2. 依據步驟1得到的參數表，執行errorCondition中配置的條件運算式，為true則繼續執行，false不生效。

3. 如果配置了errorCode欄位，則擷取errorCode欄位的值，並尋找與mappings中code匹配的映射記錄。

4. 如果步驟3沒有匹配到映射記錄，則依次執行mappings欄位配置了condition的映射記錄。

5. 如果步驟3或4中匹配到了映射記錄，根據對應的配置構造應答，否則構造預設應答。

3.4. 系統錯誤的映射及日誌

• API Gateway系統錯誤碼出現在網關的檢查、校正、流控、外掛程式處理等場合，參考錯誤碼表文檔，使用ErrorCode作為映射參數，可以支援對系統錯誤碼的映射，可用於諸如：用戶端僅支援200應答，但希望將被限流的429應答映射為200應答的情境。

• 當出現系統錯誤時，位置為StatusCode、Header、BodyJsonField等來自應答的欄位取值都將為null，在寫條件運算式時需要注意，未出現系統錯誤時ErrorCode位置的取值為OK。

• API Gateway的系統錯誤碼會出現在X-Ca-Error-Code應答頭及日誌的errorCode欄位中，這個值不會被錯誤碼映射外掛程式改寫。

• 日誌中的statusCode欄位記錄的是網關遞送給用戶端的應答碼的值，會被錯誤碼映射外掛程式改寫。

4. 配置樣本

4.1. 映射包體錯誤碼

映射

---
# 參與映射的欄位
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# 映射條件
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# 錯誤碼欄位
errorCode: "resultCode"
# 映射項
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# 預設映射（可選）
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

4.2 應答body映射

#
# 這個例子用於給前端返回定製的json錯誤body
---
# 指定映射參數
parameters:
  statusCode: "StatusCode"
  resultCode: "Header:X-Ca-Error-Code"
  requestId: "Header:X-Ca-Request-Id"
  errorMessage: "Header:X-Ca-Error-Message"

# 映射條件
errorCondition: "$statusCode != 200"
# 錯誤碼欄位
errorCode: "resultCode"
# 映射項
mappings:
  - code: "I400MH"
    statusCode: 200
    responseHeaders:
        Content-Type: "application/xml"
        X-Ca-Error-Message: ""
        X-Ca-Error-Code: ""
    responseBody: |
        {
            "code":"89",
            "message":"${errorMessage}",
            "resultCode":"${resultCode}"
            
        }

5. 使用限制

• 參數定義個數不超過16個。

• 單個運算式的字元數不超過512個字元。

• BodyJsonField位置的欄位對應答包體的限制為16380 Bytes，超過後直接返回空值。

• 外掛程式配置大小限制為50KB。

• mappings中以condition方式配置映射記錄不超過20條。