Anti-pola: Menggunakan Kebijakan RaiseFault dalam kondisi yang tidak pantas

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X. info

Kebijakan RaiseFault memungkinkan developer API memulai alur error, menetapkan variabel error dalam pesan isi respons, dan menetapkan kode status respons yang sesuai. Anda juga bisa menggunakan RaiseFault kebijakan untuk menyetel variabel alur yang terkait dengan kesalahan, seperti fault.name, fault.type, dan fault.category. Karena variabel ini terlihat dalam data analisis dan log Akses router digunakan untuk {i>debugging<i}, maka penting untuk mengidentifikasi kesalahan secara akurat.

Anda dapat menggunakan kebijakan RaiseFault untuk memperlakukan kondisi tertentu sebagai error, meskipun error yang sebenarnya telah tidak terjadi di kebijakan lain atau di server backend proxy API. Misalnya, jika Anda ingin proxy untuk mengirim pesan kesalahan khusus ke aplikasi klien setiap kali respons backend body berisi string unavailable, maka Anda dapat memanggil kebijakan RaiseFault sebagai yang ditampilkan 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 terlihat sebagai fault.name di Pemantauan API dan sebagai x_apigee_fault_policy di log akses Analytics dan Router. Hal ini akan membantu mendiagnosis penyebab error dengan mudah.

Anti-pola

Menggunakan kebijakan RaiseFault dalam FaultRules setelah kebijakan lain menampilkan error

Perhatikan contoh di bawah, saat kebijakan OAuthV2 dalam alur Proxy API gagal dengan InvalidAccessToken {i>error<i}. Jika gagal, Edge akan menyetel fault.name sebagai InvalidAccessToken, masuk ke alur error, dan mengeksekusi FaultRules yang ditentukan. Di FaultRule, ada kebijakan RaiseFault bernama RaiseFault yang mengirim respons error yang disesuaikan setiap kali InvalidAccessToken terjadi kesalahan. Namun, penggunaan kebijakan RaiseFault dalam FaultRule berarti bahwa fault.name variabel 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 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 adalah fault.name, fault.code, dan fault.policy akan ditimpa dengan nama kebijakan RaiseFault. Perilaku ini membuat hampir tidak mungkin untuk menentukan kebijakan mana yang benar-benar menyebabkan kegagalan tanpa mengakses jejak file yang menunjukkan kegagalan atau melakukan reka ulang masalah.

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

Pada contoh di bawah, kebijakan RaiseFault bernama HandleOptionsRequest dijalankan 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 menampilkan respons ke klien API secara langsung tanpa memproses kebijakan lainnya. Namun, hal ini akan menyebabkan data analitik yang menyesatkan karena variabel kesalahan akan berisi Nama kebijakan RaiseFault, membuat proxy lebih sulit untuk di-debug. Cara yang benar untuk menerapkan perilaku yang diinginkan adalah menggunakan Flow dengan kondisi khusus, seperti yang dijelaskan dalam Menambahkan dukungan CORS.

Dampak

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

Dalam screenshot di bawah dari Pemantauan API, Anda dapat melihat bahwa kebijakan Fault Code dan Fault ditimpa ke RaiseFault generik nilai, sehingga tidak mungkin untuk menentukan akar masalah kegagalan dari log:

Praktik Terbaik

Ketika kebijakan Edge menimbulkan kesalahan dan Anda ingin menyesuaikan pesan respons kesalahan, menggunakan kebijakan MenetapkanMessage atau JavaScript, bukan kebijakan RaiseFault.

Kebijakan RaiseFault harus digunakan dalam alur non-error. Artinya, hanya gunakan RaiseFault untuk menangani kondisi sebagai error, meskipun error yang sebenarnya tidak terjadi dalam kebijakan atau di server backend Proxy API. Misalnya, Anda dapat menggunakan kebijakan {i>RaiseFault<i} untuk memberi sinyal bahwa input wajib parameter hilang atau memiliki sintaksis yang salah.

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

Bacaan lebih lanjut