API Gateway：斷路器外掛程式（僅專享執行個體）

使用限制

• 僅專享執行個體生效。

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

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

1. 斷路器概述

斷路器在預設配置下，當某個API的後端在30秒鐘內出現1000次逾時，系統會觸發斷路器保護，斷路器進入開啟狀態，斷路時間為90秒，90秒內所有的請求均快速返回Status=503，X-Ca-Error-Code=D503CB錯誤碼，90秒後斷路器進入半開狀態，允許少量並發請求通過，如果後端恢複正常，則斷路器置為關閉狀態，請求恢複正常。

當您使用專享執行個體時，可以通過斷路器外掛程式來定製斷路器配置，可定製的配置如下：

• 斷路器觸發條件，可配置逾時模式或者錯誤碼模式。

• 配置逾時視窗。

• 配置斷路器開啟狀態的逾時時間。

• 配置斷路器開啟後的降級後端。

2. 配置規則

斷路器外掛程式配置僅在API運行在專享執行個體時生效，如果您使用的是共用執行個體/Serverless執行個體，則即使API綁定了斷路器外掛程式，也只會使用預設斷路器配置。

2.1 按後端逾時配置降級策略

可以按照後端逾時的方式配置降級策略。若API定義的後端逾時時間為10s，請求後端10s沒有應答就會計為後端逾時

timeoutThreshold: 15         # 逾時的閾值
windowInSeconds: 30          # 逾時時間視窗
openTimeoutSeconds: 15       # 斷路器開的時間
downgradeBackend:            # 降級後的後端配置
  type: mock
  statusCode: 418

配置欄位說明：

• timeoutThreshold: 逾時閾值，上限為5000，注意如果配置過低，可能導致幾次逾時就觸發斷路器。

• windowInSeconds: 判斷時間視窗，合法值為10~90秒。

• openTimeoutSeconds: 斷路器開的期間，合法值為15~300秒。

• downgradeBackend: （可選）當斷路器出現降級時，降級後端。

2.2 按後端回應時間配置降級策略

可以按照後端的回應時間配置降級策略。後端回應時間為網關給後端發送請求到收到後端應答的耗時。

errorThreshold: 10          # 錯誤出現的閾值
windowInSeconds: 60         # 判斷錯誤次數的時間視窗
openTimeoutSeconds: 120      # 斷路器開啟的期間
errorCondition: "$LatencyMilliSeconds > 500"     # 錯誤條件：後端回應時間大於500ms
downgradeBackend:               # 降級後的後端配置
  type: mock
  statusCode: 403

配置欄位說明：

• errorThreshold: 錯誤出現的閾值。

• windowsInSeconds: 判斷時間視窗，合法值為10~90秒。

• openTimeoutSeconds: 斷路器開的期間，合法值為15~300秒。

• errorCondition: 錯誤條件運算式，$LatencyMilliSeconds和$LatencySeconds兩個變數可以用於對後端耗時進行判斷。 $LatencyMilliSeconds的單位為毫秒（ms），$LatencySeconds的單位為秒（s）。

• downgradeBackend: （可選） 當斷路器出現降級時，降級後端。

2.3 按後端報錯配置降級策略

可以按照後端錯誤碼的方式配置降級策略。

errorCondition: "$StatusCode == 503"  # 錯誤條件
errorThreshold: 1000                  # 錯誤閾值
windowInSeconds: 30                   # 逾時視窗時間
openTimeoutSeconds: 15                # 斷路器開的時間
downgradeBackend:                     # 降級後端
  type: "HTTP"
  address: "http://api.foo.com"
  path: "/system-busy.json"
  method: GET

• errorCondition: 錯誤條件運算式，$StatusCode和$LatencySeconds兩個變數可以用於對後端的應答碼以及耗時（秒）進行判斷。

  • 如：$StatusCode = 503 or $StatusCode = 504，當後端應答為503或504。

  • 如：$LatencySeconds > 30，當逾時大於30秒時。

• errorThreshold: 錯誤出現的閾值。

• windowsInSeconds: 判斷時間視窗，合法值為10~90秒。

• openTimeoutSeconds: 斷路器開的期間，合法值為15~300秒。

• downgradeBackend: （可選） 當斷路器出現降級時，降級後端。

2.4 精準狀態控制

為了保證高可用性和高效能，API Gateway採用叢集模式將應用服務部署在多個節點上，屬於分布式架構。預設情況下，不同的服務節點會獨立計算並儲存斷路器的狀態，因此從全域角度來看，斷路器可能出現狀態不準確的情況。如果您對斷路器的精度有較高的要求，那麼可以在外掛程式配置資訊中添加useGlobalState欄位，樣本如下：

---
timeoutThreshold: 15 # 逾時出現的閾值
windowInSeconds: 30 # 判斷逾時的時間視窗
openTimeoutSeconds: 15 # 斷路器開啟的逾時時間
useGlobalState: true # 開啟精準狀態控制
downgradeBackend: # 降級後的後端配置
 type: mock
 statusCode: 302
 body: |
 <result>
 <errorCode>I's a teapot</errorCode>
 </result>

useGlobalState預設為false，開啟後斷路器可實現精準狀態控制，此時網關服務會有一定的效能損耗，但仍然能夠滿足當前執行個體所承諾的QPS和SLA指標。

2.5 按百分比來配置降級策略

目前支援根據以下四個條件判斷，無論哪個條件觸發，降級策略都會生效，沒有優先順序。

• errorThreshold：錯誤閾值，需配合錯誤條件使用。

• timeoutThreshold：後端逾時的閾值。

• errorThresholdByPercent：錯誤閾值的百分比，是根據上一個時間視窗的錯誤百分比來判斷的。

• timeoutThresholdByPercent：後端逾時的百分比，是根據上一個時間視窗的後端逾時百分比來判斷的。

樣本如下：

---
windowInSeconds: 3  # 判斷時間視窗，合法值為10~90秒
openTimeoutSeconds: 3
errorThreshold: 90  # 錯誤閾值
timeoutThreshold: 90   # 後端逾時閾值
errorThresholdByPercent: 20    # 用於控制錯誤閾值的百分比
timeoutThresholdByPercent: 20   # 用於控制後端逾時請求的百分比
errorCondition: "$StatusCode = 500"   # 錯誤條件
downgradeBackend:
  type: mock
  statusCode: 418
  body: |
    <result>
      <errorCode>I's a teapot</errorCode>
    </result>

2.6 斷路器增加流控策略

一旦觸發斷路器條件，會在API上增加一個臨時流控，在半開狀態和全開狀態所有流量全部走這個流控：

---
windowInSeconds: 1             # 判斷逾時次數的時間視窗
openTimeoutSeconds: 15          # 斷路器開啟的逾時時間
errorThreshold: 3
errorCondition: "$LatencyMilliSeconds > 1"
downgradeTrafficLimit:               # 降級後的後端配置
  limit: 2
  period: MINUTE

3. 降級後端配置

當斷路器開啟時，可以通過配置downgradeBackend來設定斷路器開啟後的返回，返回的結構與API Gateway的Swagger結構一致，請參考文檔通過匯入Swagger建立API，目前支援的後端類型及配置範例如下：

• HTTP後端

---
backend:
  type: HTTP
  address: "http://10.10.100.2:8000"
  path: "/users/{userId}"
  method: GET
  timeout: 7000        

• HTTP後端（VPC）

---
backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  path: "/users/{userId}"
  method: GET
  timeout: 10000        

• Function Compute

---
backend:
  type: FC
  fcRegion: cn-shanghai
  serviceName: fcService
  functionName: fcFunction
  arn: "acs:ram::111111111:role/aliyunapigatewayaccessingfcrole"        

• MOCK

---
backend:
  type: MOCK
  mockResult: "mock result sample"
  mockStatusCode: 200
  mockHeaders:
    - name: Content-Type
      value: text-plain
    - name: Content-Language
      value: zhCN

4. 相關錯誤碼