Antipattern: از خط مشی RaiseFault در شرایط نامناسب استفاده کنید

شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات

سیاست RaiseFault به توسعه‌دهندگان API اجازه می‌دهد تا یک جریان خطا را آغاز کنند، متغیرهای خطا را در یک پیام بدنه پاسخ تنظیم کنند و کدهای وضعیت پاسخ مناسب را تنظیم کنند. همچنین می‌توانید از سیاست RaiseFault برای تنظیم متغیرهای جریان مربوط به خطا، مانند fault.name ، fault.type و fault.category استفاده کنید. از آنجا که این متغیرها در داده‌های تحلیلی و گزارش‌های دسترسی روتر که برای اشکال‌زدایی استفاده می‌شوند، قابل مشاهده هستند، شناسایی دقیق خطا بسیار مهم است.

شما می‌توانید از سیاست RaiseFault برای در نظر گرفتن شرایط خاص به عنوان خطا استفاده کنید، حتی اگر خطای واقعی در سیاست دیگری یا در سرور backend پروکسی API رخ نداده باشد. به عنوان مثال، اگر می‌خواهید پروکسی هر زمان که بدنه پاسخ backend حاوی رشته 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 و در Analytics و Router access logs با نام x_apigee_fault_policy قابل مشاهده است. این امر به تشخیص آسان علت خطا کمک می‌کند.

ضدالگو

استفاده از سیاست RaiseFault در FaultRules پس از اینکه سیاست دیگری قبلاً خطایی ایجاد کرده است

مثال زیر را در نظر بگیرید، که در آن یک سیاست OAuthV2 در جریان API Proxy با خطای 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 هستند و اشکال‌زدایی پروکسی را دشوارتر می‌کنند. روش صحیح برای پیاده‌سازی رفتار مورد نظر، استفاده از Flowها با شرایط خاص است، همانطور که در افزودن پشتیبانی CORS توضیح داده شده است.

تأثیر

استفاده از سیاست RaiseFault همانطور که در بالا توضیح داده شد، منجر به بازنویسی متغیرهای کلیدی خطا با نام سیاست RaiseFault به جای نام سیاست ناموفق می‌شود. در گزارش‌های Analytics و NGINX Access، x_apigee_fault_code و x_apigee_fault_policy متغیرها رونویسی می‌شوند. در مانیتورینگ API ، Fault Code و Fault Policy رونویسی می‌شوند. این رفتار، عیب‌یابی و تعیین اینکه کدام خط‌مشی علت واقعی خرابی است را دشوار می‌کند.

در تصویر زیر از API Monitoring ، می‌توانید ببینید که Fault Code و Fault policy با مقادیر عمومی RaiseFault بازنویسی شده‌اند و تشخیص علت اصلی خرابی از روی لاگ‌ها را غیرممکن می‌کنند:

بهترین روش

وقتی یک خط‌مشی Edge خطایی را مطرح می‌کند و می‌خواهید پیام پاسخ خطا را سفارشی کنید، به جای خط‌مشی RaiseFault از خط‌مشی‌های AssignMessage یا JavaScript استفاده کنید.

سیاست RaiseFault باید در یک جریان بدون خطا استفاده شود. یعنی، فقط از RaiseFault برای برخورد با یک وضعیت خاص به عنوان خطا استفاده کنید، حتی اگر خطای واقعی در یک سیاست یا در سرور backend پروکسی API رخ نداده باشد. به عنوان مثال، می‌توانید از سیاست RaiseFault برای اعلام اینکه پارامترهای ورودی اجباری وجود ندارند یا نحو نادرستی دارند، استفاده کنید.

همچنین اگر می‌خواهید خطایی را در حین پردازش یک خطا تشخیص دهید، می‌توانید از RaiseFault در یک قانون خطا استفاده کنید. به عنوان مثال، خودِ مدیریت‌کننده‌ی خطا می‌تواند باعث خطایی شود که می‌خواهید با استفاده از RaiseFault آن را گزارش دهید.

مطالعه بیشتر