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

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

Он Политика 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 в журналах доступа Analytics и Router. Это помогает легко диагностировать причину ошибки.

Антипаттерн

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

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

Использование политики 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 вместо имени политики, вызвавшей ошибку. В журналах Analytics и NGINX Access отображаются переменные x_apigee_fault_code и x_apigee_fault_policy Переменные перезаписываются. В мониторинге API Fault Code и Fault Policy перезаписываются. Такое поведение затрудняет поиск и устранение неисправностей, а также определение истинной причины сбоя.

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

Передовая практика

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

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

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

Дополнительная информация