الگوی بد: استفاده از «خط‌مشی 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 و به‌عنوان x_apigee_fault_policy در گزارش‌های دسترسی Analytics و Router قابل‌مشاهده است. این کار به تشخیص آسان‌تر علت خطا کمک می‌کند.

الگوی بد

استفاده از خط‌مشی 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 تحت همه شرایط

در مثال زیر، اگر 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 به‌نام 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»، متغیرهای x_apigee_fault_code و x_apigee_fault_policy جای‌نویسی می‌شوند. در پایش میانای برنامه‌سازی کاربردی، Fault Code و Fault Policy بازنویسی می‌شوند. این رفتار عیب‌یابی و تعیین اینکه کدام خط‌مشی دلیل واقعی عدم موفقیت است را دشوار می‌کند.

در نماگرفت زیر از پایش API، می‌بینید که «کد خطا» و «خط‌مشی خطا» با مقادیر عمومی RaiseFault رونویسی شده‌اند، که تعیین علت اصلی خرابی از گزارش‌های ثبت‌شده را غیرممکن می‌کند:

روال مطلوب

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

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

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

مطالعه بیشتر

• کاربری خطاها
• خط‌مشی RaiseFault
• بحث انجمن درباره الگوهای مدیریت خطا