אנטי-תבנית: שימוש במדיניות RaiseFault בתנאים לא מתאימים

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

המדיניות RaiseFault מאפשרת למפתחי API ליזום זרימת שגיאות, להגדיר משתני שגיאה בהודעת גוף התגובה ולהגדיר קודי סטטוס מתאימים לתגובה. אפשר גם להשתמש במדיניות RaiseFault כדי להגדיר משתני זרימה שקשורים לשגיאה, כמו fault.name, fault.type ו-fault.category. המשתנים האלה גלויים בנתוני הניתוח וביומני הגישה של הנתב שמשמשים לניפוי באגים, ולכן חשוב לזהות את התקלה בצורה מדויקת.

אפשר להשתמש במדיניות RaiseFault כדי להתייחס לתנאים ספציפיים כשגיאות, גם אם לא התרחשה שגיאה בפועל במדיניות אחרת או בשרת הבק-אנד של proxy ל-API. לדוגמה, אם רוצים שה-proxy ישלח הודעת שגיאה מותאמת אישית לאפליקציית הלקוח בכל פעם שגוף התגובה של ה-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 מוצג כ-fault.name ב API Monitoring וכ-x_apigee_fault_policy ביומני הגישה של Analytics ושל Router. כך קל יותר לאבחן את הגורם לשגיאה.

תבנית אנטי

שימוש במדיניות RaiseFault בתוך FaultRules אחרי שמדיניות אחרת כבר הציגה שגיאה

בדוגמה שלמטה, מדיניות OAuthV2 בתהליך של API Proxy נכשלה עם שגיאה InvalidAccessToken. אם הפעולה תיכשל, Edge יגדיר את fault.name כ-InvalidAccessToken, יעבור לזרימת השגיאות ויבצע את כללי השגיאה שהוגדרו. ב-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, ולכן יהיה קשה יותר לנפות באגים בשרת ה-proxy. הדרך הנכונה להטמיע את ההתנהגות הרצויה היא להשתמש בתכונה 'זרימות' עם תנאים מיוחדים, כפי שמתואר במאמר הוספת תמיכה ב-CORS.

השפעה

השימוש במדיניות RaiseFault כמו שמתואר למעלה גורם להחלפת משתני השגיאה של המפתח בשם של מדיניות RaiseFault במקום בשם של המדיניות שנכשלה. ב-Analytics וביומני הגישה של NGINX, המשתנים x_apigee_fault_code ו-x_apigee_fault_policy נדרסים. ב-API Monitoring, הערכים של Fault Code ושל Fault Policy נמחקים. ההתנהגות הזו מקשה על פתרון בעיות ועל קביעה איזו מדיניות היא הסיבה האמיתית לכישלון.

בצילום המסך שלמטה ממעקב אחר API, אפשר לראות שקוד השגיאה ומדיניות השגיאה הוחלפו בערכים כלליים של RaiseFault, ולכן אי אפשר לקבוע את שורש הבעיה של הכשל מתוך היומנים:

שיטה מומלצת

אם מדיניות Edge מעלה תקלה ואתם רוצים להתאים אישית את הודעת התגובה לשגיאה, השתמשו במדיניות AssignMessage או JavaScript במקום במדיניות RaiseFault.

צריך להשתמש במדיניות RaiseFault בזרימת נתונים שאינה שגיאה. כלומר, משתמשים ב-RaiseFault רק כדי להתייחס לתנאי ספציפי כשגיאה, גם אם לא התרחשה שגיאה בפועל במדיניות או בשרת העורפי של ה-API Proxy. לדוגמה, אפשר להשתמש במדיניות RaiseFault כדי לציין שחסרים פרמטרים של קלט חובה או שהתחביר שלהם שגוי.

אפשר גם להשתמש ב-RaiseFault בכלל שגיאה אם רוצים לזהות שגיאה במהלך העיבוד של שגיאה. לדוגמה, יכול להיות שמטפל השגיאות עצמו יגרום לשגיאה שתרצו לסמן באמצעות RaiseFault.

קריאה נוספת