Antipattern: ใช้นโยบาย RaiseFault ภายใต้เงื่อนไขที่ไม่เหมาะสม

คุณกำลังดูเอกสารประกอบ Apigee Edge
ไปที่ เอกสารประกอบเกี่ยวกับ Apigee X. ข้อมูล

นโยบาย RaiseFault ช่วยให้นักพัฒนาซอฟต์แวร์ API เริ่มขั้นตอนข้อผิดพลาด ตั้งค่าตัวแปรข้อผิดพลาด ในข้อความเนื้อหาการตอบกลับ และตั้งค่ารหัสสถานะการตอบกลับที่เหมาะสม นอกจากนี้คุณยังใช้ RaiseFault นโยบายเพื่อกำหนดตัวแปรโฟลว์ที่เกี่ยวข้องกับความผิดพลาด เช่น fault.name, fault.type และ fault.category เนื่องจากตัวแปรเหล่านี้แสดงในข้อมูล Analytics และบันทึกการเข้าถึงเราเตอร์ ซึ่งใช้สำหรับการแก้ไขข้อบกพร่อง สิ่งสำคัญคือการระบุข้อผิดพลาดอย่างถูกต้อง

คุณสามารถใช้นโยบาย RaiseFault เพื่อพิจารณาเงื่อนไขที่เฉพาะเจาะจงเป็นข้อผิดพลาด แม้ว่าข้อผิดพลาดจริงจะเกิดขึ้น ไม่ได้เกิดขึ้นในนโยบายอื่นหรือในเซิร์ฟเวอร์แบ็กเอนด์ของพร็อกซี API ตัวอย่างเช่น ถ้าคุณต้องการ พร็อกซีเพื่อส่งข้อความแสดงข้อผิดพลาดที่กำหนดเองไปยังแอปไคลเอ็นต์เมื่อใดก็ตามที่มีการตอบสนองของแบ็กเอนด์ body มีสตริง 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 และเราเตอร์ ซึ่งจะช่วยให้วิเคราะห์สาเหตุของข้อผิดพลาดได้อย่างง่ายดาย

ลาย Antipattern

การใช้นโยบาย 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 ภายใต้เงื่อนไขทั้งหมด

ในตัวอย่างด้านล่าง นโยบาย 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 ทำให้พร็อกซีแก้ไขข้อบกพร่องได้ยากขึ้น วิธีใช้งานที่ถูกต้อง ลักษณะการทำงานที่ต้องการคือการใช้โฟลว์ที่มีเงื่อนไขพิเศษ ตามที่อธิบายไว้ใน การเพิ่มการรองรับ CORS

ผลกระทบ

การใช้นโยบาย RaiseFault ตามที่อธิบายไว้ข้างต้นจะทำให้เกิดการเขียนทับตัวแปรความผิดพลาดของคีย์ด้วย ชื่อนโยบาย RaiseFault แทนชื่อนโยบายที่ไม่สำเร็จ ในบันทึกของการเข้าถึง Analytics และ NGINX ตัวแปร x_apigee_fault_code และ x_apigee_fault_policy ถูกเขียนทับ ในการตรวจสอบ API การตั้งค่า Fault Code และ Fault Policy ถูกเขียนทับ การทำงานลักษณะนี้ทำให้แก้ปัญหาได้ยาก แล้วระบุว่านโยบายใดเป็นสาเหตุที่แท้จริงของความล้มเหลว

ในภาพหน้าจอด้านล่างจากการตรวจสอบ API คุณจะเห็นว่านโยบาย Fault Code และ Fault ถูกเขียนทับเป็น RaiseFault ทั่วไป ซึ่งทำให้ไม่สามารถระบุสาเหตุหลักของความล้มเหลวจากบันทึกได้

แนวทางปฏิบัติแนะนำ

เมื่อนโยบาย Edge ทำให้เกิดข้อผิดพลาดและคุณต้องการปรับแต่งข้อความตอบกลับข้อผิดพลาด ใช้นโยบาย AssignMessage หรือ JavaScript แทนนโยบาย RaiseFault

ควรใช้นโยบาย RaiseFault ในขั้นตอนที่ไม่ใช่ข้อผิดพลาด กล่าวคือ ใช้ RaiseFault เพื่อจัดการเฉพาะ เป็นข้อผิดพลาด แม้ว่าข้อผิดพลาดจริงจะไม่เกิดขึ้นในนโยบายหรือในเซิร์ฟเวอร์แบ็กเอนด์ก็ตาม ของพร็อกซี API เช่น คุณอาจใช้นโยบาย RaiseFault เพื่อส่งสัญญาณแจ้งว่าจำเป็นต้องป้อนข้อมูล ไม่มีพารามิเตอร์หรือมีไวยากรณ์ไม่ถูกต้อง

นอกจากนี้ คุณยังสามารถใช้ RaiseFault ในกฎข้อผิดพลาดหากต้องการตรวจหาข้อผิดพลาดระหว่างการประมวลผล ความผิดพลาด ตัวอย่างเช่น ตัวแฮนเดิลข้อผิดพลาดเองอาจทำให้เกิดข้อผิดพลาดที่คุณต้องการส่งสัญญาณโดยใช้ RaiseFault

อ่านเพิ่มเติม

• การจัดการข้อผิดพลาด
• นโยบายของ RaiseFault
• การพูดคุยกันในชุมชนเกี่ยวกับรูปแบบการจัดการข้อบกพร่อง