Antypattern: stosowanie zasady GrowFault w nieodpowiednich warunkach

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Zasada RaiseFault umożliwia programistom interfejsów API inicjowanie przepływu błędów, ustawianie zmiennych błędów w treści odpowiedzi i ustawianie odpowiednich kodów stanu odpowiedzi. Możesz też użyć zasady RaiseFault, aby ustawić zmienne przepływu związane z błędem, takie jak fault.name, fault.type, i fault.category. Ponieważ te zmienne są widoczne w danych Analytics i logach dostępu do routera używanych do debugowania, ważne jest, aby dokładnie zidentyfikować błąd.

Za pomocą zasady RaiseFault możesz traktować określone warunki jako błędy, nawet jeśli w innej zasadzie lub na serwerze backendu serwera proxy interfejsu API nie wystąpił rzeczywisty błąd. Jeśli na przykład chcesz aby serwer proxy wysyłał do aplikacji klienckiej niestandardowy komunikat o błędzie, gdy treść odpowiedzi backendu zawiera ciąg znaków unavailable, możesz wywołać zasadę RaiseFault w sposób pokazany w poniższym fragmencie kodu: 

<!-- /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>
...

Nazwa zasady RaiseFault jest widoczna jako fault.name w monitorowaniu interfejsu API oraz jako x_apigee_fault_policy w logach dostępu do Analytics i routera. Ułatwia to diagnozowanie przyczyny błędu.

Antywzorzec

Używanie zasady RaiseFault w FaultRules po tym, jak inna zasada zgłosiła już błąd

Rozważmy przykład poniżej, w którym zasada OAuthV2 w przepływie serwera proxy interfejsu API nie powiodła się z powodu błędu InvalidAccessToken. W przypadku niepowodzenia Edge ustawi fault.name jako InvalidAccessToken, przejdzie do przepływu błędów i wykona wszystkie zdefiniowane FaultRules. W FaultRule znajduje się zasada RaiseFault o nazwie RaiseFault która wysyła dostosowaną odpowiedź o błędzie, gdy wystąpi błąd InvalidAccessToken. Użycie zasady RaiseFault w FaultRule oznacza jednak, że zmienna fault.name zostanie nadpisana i ukryje prawdziwą przyczynę niepowodzenia. 

<!-- /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>

Używanie zasady RaiseFault w FaultRule we wszystkich warunkach

W przykładzie poniżej zasada RaiseFault o nazwie RaiseFault jest wykonywana, jeśli fault.name nie jest równe 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>

Podobnie jak w pierwszym scenariuszu, kluczowe zmienne błędów fault.name, fault.code, i fault.policy są nadpisywane nazwą zasady RaiseFault. To zachowanie sprawia, że bez dostępu do pliku śledzenia pokazującego niepowodzenie lub bez odtworzenia problemu prawie niemożliwe jest ustalenie, która zasada faktycznie spowodowała niepowodzenie.

Używanie zasady RaiseFault do zwracania odpowiedzi HTTP 2xx poza przepływem błędów.

W przykładzie poniżej zasada RaiseFault o nazwie HandleOptionsRequest jest wykonywana, gdy czasownik żądania to OPTIONS: 

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

Celem jest natychmiastowe zwrócenie odpowiedzi do klienta interfejsu API bez przetwarzania innych zasad. Spowoduje to jednak wprowadzające w błąd dane Analytics, ponieważ zmienne błędów będą zawierać nazwę zasady RaiseFault, co utrudni debugowanie serwera proxy. Prawidłowym sposobem wdrożenia żądanego zachowania jest użycie przepływów ze specjalnymi warunkami, jak opisano w sekcji Dodawanie obsługi CORS.

Wpływ

Użycie zasady RaiseFault w sposób opisany powyżej powoduje nadpisanie kluczowych zmiennych błędów nazwą zasady RaiseFault zamiast nazwą zasady, która spowodowała błąd. W logach dostępu do Analytics i NGINX, zmienne x_apigee_fault_code i x_apigee_fault_policy są nadpisywane. W monitorowaniu interfejsu API nadpisywane są Fault Code i Fault Policy . To zachowanie utrudnia rozwiązywanie problemów i ustalenie, która zasada jest prawdziwą przyczyną niepowodzenia.

Na zrzucie ekranu poniżej z monitorowania interfejsu API, widać, że kod błędu i zasada błędu zostały nadpisane ogólnymi RaiseFault wartościami, co uniemożliwia ustalenie głównej przyczyny niepowodzenia na podstawie logów:

Sprawdzona metoda

Gdy zasada Edge zgłosi błąd i chcesz dostosować komunikat o błędzie, użyj zasad AssignMessage lub JavaScript zamiast zasady RaiseFault.

Zasada RaiseFault powinna być używana w przepływie bez błędów. Oznacza to, że zasady RaiseFault należy używać tylko do traktowania określonego warunku jako błędu, nawet jeśli w zasadzie lub na serwerze backendu serwera proxy interfejsu API nie wystąpił rzeczywisty błąd. Możesz na przykład użyć zasady RaiseFault, aby zasygnalizować, że brakuje obowiązkowych parametrów wejściowych lub mają one nieprawidłową składnię.

Możesz też użyć zasady RaiseFault w regule błędu, jeśli chcesz wykryć błąd podczas przetwarzania błędu. Na przykład sam moduł obsługi błędów może spowodować błąd, który chcesz zasygnalizować za pomocą zasady RaiseFault.

Więcej informacji