안티패턴: 부적절한 조건에서 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 정책의 이름은 API Monitoring에는 fault.name으로, 애널리틱스 및 라우터 액세스 로그에는 x_apigee_fault_policy로 표시됩니다. 따라서 오류의 원인을 쉽게 진단할 수 있습니다.

안티패턴

다른 정책에서 이미 오류가 발생한 후 FaultRules 내에서 RaiseFault 정책 사용

API 프록시 흐름의 OAuthV2 정책이 InvalidAccessToken 오류와 함께 실패한 아래 예시를 살펴보세요. 실패하면 Edge가 fault.name를 InvalidAccessToken로 설정하고 오류 흐름을 시작한 다음 정의된 FaultRules를 실행합니다. FaultRule에는 InvalidAccessToken 오류가 발생할 때마다 맞춤설정된 오류 응답을 보내는 RaiseFault라는 RaiseFault 정책이 있습니다. 그러나 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 정책의 이름으로 덮어써집니다. 이 동작으로 인해 오류를 보여주거나 문제를 재현하는 추적 파일에 액세스하지 않고서는 실제로 어떤 정책이 오류를 유발했는지 파악하기가 거의 불가능합니다.

오류 흐름 외부에서 HTTP 2xx 응답을 반환하는 RaiseFault 정책 사용

아래 예에서는 요청 동사가 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 클라이언트에 즉시 응답을 반환하는 것입니다. 그러나 이로 인해 오류 변수에 RaiseFault 정책의 이름이 포함되어 프록시를 디버깅하기가 더 어려워지므로 분석 데이터를 오해할 수 있습니다. 본래의 동작을 구현하는 올바른 방법은 CORS 지원 추가에 설명된 대로 특수한 조건에서 흐름을 사용하는 것입니다.

영향

위에서 설명한 것처럼 RaiseFault 정책을 사용하면 주요 오류 변수가 오류가 발생한 정책의 이름 대신 RaiseFault 정책의 이름으로 덮어써집니다. 애널리틱스 및 NGINX 액세스 로그에서는 x_apigee_fault_code 및 x_apigee_fault_policy 변수가 덮어써집니다. API Monitoring에서는 Fault Code 및 Fault Policy 가 덮어써집니다. 이러한 동작으로 인해 문제를 해결하기가 어려워지고, 어떤 정책이 실제로 오류를 유발했는지 파악하기가 어려워집니다.

아래의 API 모니터링 스크린샷에서 오류 코드 및 오류 정책을 일반 RaiseFault 값으로 덮어써서 로그에서 오류의 근본 원인을 파악할 수 없음을 확인할 수 있습니다.

권장사항

Edge 정책에서 오류가 발생하고 오류 응답 메시지를 맞춤설정하려는 경우 RaiseFault 정책 대신AssignMessage 또는 자바스크립트 정책을 사용하세요.

RaiseFault 정책은 비오류 흐름에서 사용해야 합니다. 즉, 정책이나 API 프록시의 백엔드 서버에서 실제 오류가 발생하지 않은 경우에도 특정 조건을 오류로 처리할 때만 RaiseFault를 사용합니다. 예를 들어 RaiseFault 정책을 사용하여 필수 입력 매개변수가 누락되었거나 잘못된 구문이 있음을 알릴 수 있습니다.

결함 처리 중에 오류를 감지하려는 경우 잘못된 규칙에서 RaiseFault를 사용할 수도 있습니다. 예를 들어 오류 핸들러 자체에서 RaiseFault를 사용하여 신호를 보내고자 하는 오류를 발생시킬 수 있습니다.

추가 자료