Антипаттерн: использование правила RaiseFault в неподходящих условиях

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Правило RaiseFault позволяет разработчикам API запускать процесс обработки ошибок, задавать переменные ошибок в теле ответа и устанавливать подходящие коды статуса ответа. Вы также можете использовать правило RaiseFault, чтобы задать переменные потока, относящиеся к ошибке, например fault.name, fault.type и fault.category. Поскольку эти переменные видны в данных аналитики и журналах доступа к маршрутизатору, используемых для отладки, важно точно определить ошибку.

Правило RaiseFault позволяет рассматривать определенные условия как ошибки, даже если в другом правиле или на бэкенд-сервере прокси-сервера API фактическая ошибка не возникла. Например, если вы хотите, чтобы прокси-сервер отправлял клиентскому приложению специальное сообщение об ошибке, когда тело ответа от внутреннего сервиса содержит строку 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>
...

Название правила RaiseFault отображается как fault.name в API Monitoring и как x_apigee_fault_policy в журналах доступа к Аналитике и маршрутизатору. Это поможет вам легко определить причину ошибки.

Антипаттерн

Использование правила RaiseFault в FaultRules после того, как другое правило уже вызвало ошибку.

Рассмотрим пример ниже, в котором политика OAuthV2 в потоке прокси API не выполнена из-за ошибки InvalidAccessToken. В случае сбоя Edge установит для переменной fault.name значение InvalidAccessToken, перейдет к обработке ошибок и выполнит все определенные правила FaultRules. В FaultRule есть правило RaiseFault с именем RaiseFault, которое отправляет настраиваемый ответ об ошибке при возникновении ошибки InvalidAccessToken. Однако использование правила RaiseFault в FaultRule означает, что переменная 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>

Использование правила RaiseFault в FaultRule при любых условиях

В примере ниже политика RaiseFault с названием RaiseFault выполняется, если fault.name не равно 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 вне потока ошибок.

В примере ниже политика RaiseFault с именем HandleOptionsRequest выполняется, когда глагол запроса – OPTIONS: 

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

Цель – немедленно вернуть ответ API-клиенту, не обрабатывая другие правила. Однако это приведет к искажению данных аналитики, поскольку переменные ошибки будут содержать название правила RaiseFault, что затруднит отладку прокси. Чтобы реализовать нужное поведение, используйте потоки со специальными условиями, как описано в разделе Добавление поддержки CORS.

Результат

При использовании политики RaiseFault, как описано выше, ключевые переменные ошибки перезаписываются именем политики RaiseFault, а не именем политики, которая не сработала. В Аналитике и журналах доступа NGINX переменные x_apigee_fault_code и x_apigee_fault_policy перезаписываются. В API Monitoring значения Fault Code и Fault Policy перезаписываются. Из-за этого сложно устранять неполадки и определять, какое правило стало причиной ошибки.

На скриншоте ниже из API Monitoring видно, что код ошибки и правило ошибки были перезаписаны общими значениями RaiseFault, поэтому по журналам невозможно определить первопричину сбоя:

Рекомендации

Если правило Edge вызывает ошибку и вы хотите настроить сообщение об ошибке, используйте правила AssignMessage или JavaScript вместо правила RaiseFault.

Правило RaiseFault следует использовать в потоке без ошибок. То есть используйте RaiseFault, чтобы рассматривать определенное условие как ошибку, даже если в правиле или на внутреннем сервере прокси API фактическая ошибка не возникла. Например, с помощью правила RaiseFault можно указать, что обязательные входные параметры отсутствуют или имеют неверный синтаксис.

Вы также можете использовать RaiseFault в правиле обработки ошибок, если хотите обнаружить ошибку во время обработки ошибки. Например, обработчик ошибок может вызвать ошибку, о которой вы хотите сообщить с помощью RaiseFault.

Дополнительные материалы