反模式：在不當情況下使用 IncreaseFault 政策

您目前查看的是 Apigee 和 Apigee Hybrid 說明文件。
查看 Apigee Edge 說明文件。

API 開發人員可透過 RaiseFault 政策啟動錯誤流程、在回應主體訊息中設定錯誤變數，以及設定適當的回應狀態碼。您也可以使用 RaiseFault 政策設定與錯誤相關的流程變數，例如 fault.name、fault.type 和 fault.category。由於這些變數會顯示在用於偵錯的 Analytics 資料和路由器存取記錄中，因此請務必準確找出錯誤。

即使其他政策或 API Proxy 的後端伺服器未發生實際錯誤，您仍可使用 RaiseFault 政策將特定情況視為錯誤。舉例來說，如果想讓 Proxy 在後端回應主體包含字串 unavailable 時，傳送自訂錯誤訊息給用戶端應用程式，可以按照下列程式碼片段所示，叫用 RaiseFault 政策：

<!-- /antipatterns/examples/raise-fault-conditions-1.xml  -->
<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>RF-Service-Unavailable</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
   </Step>
  </Response>
...

在 API 監控中，RaiseFault 政策的名稱會顯示為 fault.name，在 Analytics 和 Router 存取記錄中則會顯示為 x_apigee_fault_policy。這有助於輕鬆診斷錯誤原因。

反模式

在其他政策已擲回錯誤後，於 FaultRules 中使用 RaiseFault 政策

請看以下範例，API Proxy 流程中的 OAuthV2 政策發生 InvalidAccessToken 錯誤。如果失敗，Apigee 會將 fault.name 設為 InvalidAccessToken，進入錯誤流程，並執行任何已定義的 FaultRules。在 FaultRule 中，有名為「RaiseFault」RaiseFault的政策，每當發生 InvalidAccessToken 錯誤時，就會傳送自訂錯誤回應。不過，在 FaultRule 中使用 RaiseFault 政策，表示 fault.name 變數會遭到覆寫，並遮蓋失敗的真正原因。

<!-- /antipatterns/examples/raise-fault-conditions-2.xml  -->
<FaultRules>
  <FaultRule name="generic_raisefault">
    <Step>
        <Name>RaiseFault</Name>
        <Condition>(fault.name equals "invalid_access_token") or (fault.name equals "InvalidAccessToken")</Condition>
    </Step>
  </FaultRule>
</FaultRules>

在所有情況下，於 FaultRule 中使用 RaiseFault 政策

在以下範例中，如果 fault.name 不是 RaiseFault，系統就會執行名為 RaiseFault 的 RaiseFault 政策：

<!-- /antipatterns/examples/raise-fault-conditions-3.xml  -->
<FaultRules>
    <FaultRule name="fault_rule">
        ....
        <Step>
            <Name>RaiseFault</Name>
            <Condition>!(fault.name equals "RaiseFault")</Condition>
        </Step>
    </FaultRule>
</FaultRules>

如同第一個情境，主要錯誤變數 fault.name、fault.code 和 fault.policy 會以 RaiseFault 政策的名稱覆寫。如果沒有顯示失敗的追蹤記錄檔或重現問題，幾乎無法判斷實際導致失敗的政策。

使用 RaiseFault 政策在錯誤流程外傳回 HTTP 2xx 回應。

在下列範例中，當要求動詞為 OPTIONS 時，系統會執行名為 HandleOptionsRequest 的 RaiseFault 政策：

<!-- /antipatterns/examples/raise-fault-conditions-4.xml  -->
<PreFlow name="PreFlow">
    <Request>
        …
        <Step>
            <Name>HandleOptionsRequest</Name>
            <Condition>(request.verb Equals "OPTIONS")</Condition>
        </Step>
        …
</PreFlow>

目的是立即將回應傳回 API 用戶端，而不處理其他政策。 不過，這樣會導致誤導性的 Analytics 資料，因為錯誤變數會包含 RaiseFault 政策的名稱，使 Proxy 更難偵錯。如要正確實作所需行為，請使用具有特殊條件的 Flow，詳情請參閱「新增 CORS 支援」。

影響

如上所述，使用 RaiseFault 政策會導致系統以 RaiseFault 政策的名稱覆寫主要錯誤變數，而非失敗政策的名稱。在 Analytics 和 NGINX 存取記錄檔中， x_apigee_fault_code和 x_apigee_fault_policy 變數會遭到覆寫。在 API 監控中，Fault Code 和 Fault Policy 會遭到覆寫。這種行為會導致難以進行疑難排解，也難以判斷哪個政策才是失敗的真正原因。

在下方的 API 監控螢幕截圖中，您可以看到錯誤代碼和錯誤政策已覆寫為一般 RaiseFault 值，因此無法從記錄檔判斷失敗的根本原因：

待定

最佳做法

如果 Apigee 政策拋出錯誤訊息，且您想自訂錯誤回應訊息，請使用 AssignMessage 或 JavaScript 政策，而非 RaiseFault 政策。

RaiseFault 政策應在非錯誤流程中使用。也就是說，即使 API Proxy 的政策或後端伺服器中未發生實際錯誤，您也只能使用 RaiseFault 將特定情況視為錯誤。舉例來說，您可以使用 RaiseFault 政策，指出缺少必要輸入參數或語法有誤。

如果想在處理錯誤時偵測錯誤，也可以在錯誤規則中使用 RaiseFault。舉例來說，錯誤處理常式本身可能會導致錯誤，而您想使用 RaiseFault 發出信號。

延伸閱讀