Antipattern: Menggunakan Kebijakan RaiseFault dalam kondisi yang tidak sesuai

Anda sedang melihat dokumentasi Apigee dan Apigee Hybrid.
Lihat dokumentasi Apigee Edge.

Kebijakan RaiseFault memungkinkan developer API memulai alur error, menetapkan variabel error dalam pesan isi respons, dan menetapkan kode status respons yang sesuai. Anda juga dapat menggunakan kebijakan RaiseFault untuk menetapkan variabel alur yang berkaitan dengan kesalahan, seperti fault.name, fault.type, dan fault.category. Karena variabel ini terlihat dalam data analisis dan log akses Router yang digunakan untuk proses debug, penting untuk mengidentifikasi kesalahan secara akurat.

Anda dapat menggunakan kebijakan RaiseFault untuk memperlakukan kondisi tertentu sebagai error, meskipun error yang sebenarnya tidak terjadi di kebijakan lain atau di server backend proxy API. Misalnya, jika Anda ingin proxy mengirim pesan error kustom ke aplikasi klien setiap kali isi respons backend berisi string unavailable, Anda dapat memanggil kebijakan RaiseFault seperti yang ditunjukkan dalam cuplikan kode di bawah ini:

<!-- /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>
...

Nama kebijakan RaiseFault dapat dilihat sebagai fault.name di API Monitoring dan sebagai x_apigee_fault_policy di log akses Analytics dan Router. Hal ini membantu mendiagnosis penyebab kesalahan dengan mudah.

Antipola

Menggunakan kebijakan RaiseFault dalam FaultRules setelah kebijakan lain memunculkan error

Perhatikan contoh di bawah, tempat kebijakan OAuthV2 di alur Proxy API gagal dengan error InvalidAccessToken. Jika gagal, Apigee akan menyetel fault.name sebagai InvalidAccessToken, masuk ke dalam alur error, dan mengeksekusi FaultRules apa pun yang ditentukan. Di FaultRule, ada kebijakan RaiseFault bernama RaiseFault yang mengirimkan respons error yang disesuaikan setiap kali error InvalidAccessToken terjadi. Namun, penggunaan kebijakan RaiseFault dalam FaultRule berarti bahwa variabel fault.name akan ditimpa dan menyamarkan penyebab sebenarnya dari kegagalan.

<!-- /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>

Menggunakan kebijakan RaiseFault di FaultRule dalam semua kondisi

Pada contoh di bawah, kebijakan RaiseFault yang bernama RaiseFault dijalankan jika fault.name bukan 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>

Seperti dalam skenario pertama, variabel kesalahan utama fault.name, fault.code, dan fault.policy akan ditimpa dengan nama kebijakan RaiseFault. Perilaku ini membuat hampir tidak mungkin untuk menentukan kebijakan mana yang sebenarnya menyebabkan kegagalan tanpa mengakses file rekaman aktivitas yang menunjukkan kegagalan atau mereproduksi masalah.

Menggunakan kebijakan RaiseFault untuk menampilkan respons HTTP 2xx di luar alur error.

Pada contoh di bawah, kebijakan RaiseFault yang bernama HandleOptionsRequest dieksekusi saat kata kerja permintaan adalah OPTIONS:

<!-- /antipatterns/examples/raise-fault-conditions-4.xml  -->
<PreFlow name="PreFlow">
    <Request>
        …
        <Step>
            <Name>HandleOptionsRequest</Name>
            <Condition>(request.verb Equals "OPTIONS")</Condition>
        </Step>
        …
</PreFlow>

Tujuannya adalah untuk segera menampilkan respons ke klien API tanpa memproses kebijakan lain. Namun, hal ini akan menyebabkan data analisis yang menyesatkan karena variabel kesalahan akan berisi nama kebijakan RaiseFault, sehingga proxy lebih sulit untuk di-debug. Cara yang benar untuk mengimplementasikan perilaku yang diinginkan adalah menggunakan Flow dengan kondisi khusus, seperti dijelaskan dalam Menambahkan dukungan CORS.

Dampak

Penggunaan kebijakan RaiseFault seperti yang dijelaskan di atas menyebabkan variabel kesalahan utama ditimpa dengan nama kebijakan RaiseFault, bukan nama kebijakan yang gagal. Di log Analytics dan Akses NGINX, variabel x_apigee_fault_code dan x_apigee_fault_policy akan ditimpa. Dalam API Monitoring, Fault Code dan Fault Policy akan ditimpa. Perilaku ini mempersulit pemecahan masalah dan menentukan kebijakan mana yang merupakan penyebab kegagalan sebenarnya.

Pada screenshot dari API Monitoring di bawah, Anda dapat melihat bahwa kebijakan Fault Code dan Fault ditimpa ke nilai RaiseFault generik, sehingga mustahil untuk menentukan akar masalah dari log:

Ditentukan Nanti

Praktik Terbaik

Saat kebijakan Apigee memunculkan kesalahan dan Anda ingin menyesuaikan pesan respons error, gunakan kebijakan ProvideMessage atau JavaScript, bukan kebijakan RaiseFault.

Kebijakan RaiseFault harus digunakan dalam alur non-error. Artinya, hanya gunakan RaiseFault untuk memperlakukan kondisi tertentu sebagai error, meskipun error yang sebenarnya tidak terjadi dalam kebijakan atau server backend Proxy API. Misalnya, Anda dapat menggunakan kebijakan RaiseFault untuk memberikan sinyal bahwa parameter input wajib tidak ada atau memiliki sintaksis yang salah.

Anda juga dapat menggunakan RaiseFault dalam aturan fault jika ingin mendeteksi error selama pemrosesan kesalahan. Misalnya, pengendali fault Anda sendiri dapat menyebabkan error yang ingin Anda beri sinyal menggunakan RaiseFault.

Bacaan lebih lanjut