Bilakah HTTP 424 Failed Dependency patut digunakan, dan bagaimanakah anda mereka bentuk kontrak API yang selamat untuk percubaan semula (retry-safe)?

Senario

Satu API kelompok mengesahkan pesanan, merizab inventori dan mencipta pesanan. Jika perizaban inventori gagal, penciptaan pesanan tidak akan dijalankan. Penemu duga meminta anda mereka bentuk respons ralat dan mewajarkan sama ada HTTP 424 adalah wajar.

Perkara yang diuji

Membezakan semantik HTTP yang dipiawaikan daripada konvensyen khusus pasukan.
Mewakili penyelesaian separa, kerja yang dilangkau dan hasil yang tidak diketahui dalam graf kebergantungan.
Mereka bentuk kedap kuasa (idempotency), syarat percubaan semula dan butiran ralat sebagai satu kontrak.

Jawapan model

Sempadan 424

424 (Failed Dependency) ditakrifkan oleh RFC 4918 WebDAV: kaedah tidak dapat diselesaikan kerana operasi lain gagal. Ia bukan alias generik untuk setiap ralat perkhidmatan hiliran (downstream). API bukan WebDAV boleh menggunakan 424, tetapi kontrak awamnya mesti mentakrifkan maksud, tingkah laku klien dan jangkaan keserasian.

Memilih kod status

412 Precondition Failed: prasyarat permintaan seperti If-Match tidak dipenuhi.
409 Conflict: permintaan bercanggah dengan keadaan sumber semasa, seperti perubahan versi inventori.
424 Failed Dependency: langkah ini secara jelas bergantung pada langkah yang gagal dalam permintaan atau aliran kerja yang sama dan oleh itu tidak dilaksanakan.
5xx: pelayan tidak dapat menyelesaikan permintaan disebabkan oleh kegagalan perkhidmatan, bukan kerana hubungan permintaan menjelaskan langkah yang disekat.

Jangan memetakan 500 daripada kebergantungan secara mekanikal kepada 424. Mula-mula tentukan sama ada langkah dalam aliran kerja ini telah disekat dan sama ada klien boleh mengambil tindakan berbeza disebabkan oleh fakta tersebut.

Badan respons dan mesin keadaan

Gunakan RFC 9457 Problem Details dengan type, title, status dan detail yang stabil, serta sambungan seperti blockedBy, operationId, retryable dan completedSteps. Sambungan perniagaan adalah sebahagian daripada kontrak dan memerlukan pemversian.

json

{
  "type": "https://api.example.com/problems/failed-dependency",
  "title": "Order creation was blocked",
  "status": 424,
  "detail": "Inventory reservation failed",
  "blockedBy": "reserve-inventory",
  "operationId": "op_123",
  "retryable": true,
  "completedSteps": ["validate-order"]
}

Percubaan semula dan hasil yang tidak diketahui

Cuba semula secara automatik hanya apabila retryable=true dan kunci kedap kuasa yang sama digunakan. Jika sambungan terputus selepas perizaban inventori dikomit, klien tidak boleh memanggil tamat masa itu sebagai 424 kerana hasil pelayan tidak diketahui; ia harus membuat pertanyaan melalui operationId. Kesan sampingan yang telah selesai tidak boleh diundur dengan berpura-pura bahawa permintaan kedua adalah baharu; sediakan pampasan apabila perniagaan memerlukannya.

Kesilapan lazim

Menganggap 424 sebagai status universal untuk semua ralat perkhidmatan mikro.
Hanya mengembalikan prosa tanpa jenis ralat atau ID operasi yang stabil.
Mencuba semula setiap 424 dan mencipta perizaban atau pesanan pendua.
Menyembunyikan gangguan perkhidmatan di sebalik 424 sehingga pemantauan tidak dapat memisahkan sekatan aliran kerja daripada kegagalan platform.

Soalan susulan

Bolehkah permintaan kelompok berjaya secara separa?

Ya, tetapi kembalikan status bagi setiap item, maklumat kedap kuasa dan butiran kebergantungan. Status HTTP kelompok menerangkan hasil agregat; ia tidak boleh menggantikan hasil item. Jika perniagaan memerlukan keatoman (atomicity), nyatakan sama ada semua perubahan diundur atau tiada yang dikomit.

Bilakah 409 lebih baik daripada 424?

Percanggahan versi sumber dan keadaan inventori ialah masalah sumber semasa dan biasanya sesuai dengan 409. Gunakan 424 apabila langkah semasa dilangkau kerana langkah lain dalam aliran kerja yang sama gagal.

Bagaimana jika kebergantungan mengembalikan 503?

Jika langkah semasa disekat dan kontrak menganggapnya sebagai kegagalan kebergantungan aliran kerja, 424 boleh membawa punca utama dalam butirannya. Jika perkhidmatan secara keseluruhannya tidak tersedia, kembalikan 503 dan gunakan isyarat peringkat perkhidmatan seperti Retry-After. Pemantauan dan dasar klien mesti membezakan kes-kes tersebut.

Bagaimanakah anda menguji kontrak tersebut?

Liputi kejayaan kebergantungan, penolakan, tamat masa, kehilangan sambungan selepas komit, kunci kedap kuasa pendua, penyelesaian separa dan pertanyaan pemulihan. Pastikan status, medan Problem Details, keadaan terminal dan bilangan kesan sampingan disahkan (assert) berbanding hanya nombor HTTP.

Rubrik pemarkahan

Lulus

Menerangkan asal usul WebDAV bagi 424 dengan tepat, menetapkan sempadan untuk 409, 412 dan 5xx, serta mencadangkan kunci kedap kuasa berserta pertanyaan hasil tidak diketahui.

Kuat

Mereka bentuk sambungan Problem Details, keadaan penyelesaian separa, kategori pemantauan dan syarat percubaan semula automatik yang selamat.

Cemerlang

Mewajarkan setiap pilihan menggunakan keatoman perniagaan, graf kebergantungan, pampasan dan kontrak berversi, sambil menyatakan risiko keserasian apabila 424 digunakan di luar WebDAV.

Strategi jawapan

Mula-mula tetapkan asal piawai kod status, kemudian tentukan keadaan langkah dan sempadan kesan sampingan; akhirnya jadikan keputusan itu konkrit dengan kontrak ralat yang boleh ditanya dan selamat untuk percubaan semula.

Sumber

Piawaian kod status

RFC 4918: WebDAV (IETF)

Semantik HTTP

RFC 9110: HTTP Semantics (IETF)

Format ralat

RFC 9457: Problem Details for HTTP APIs (IETF)