1. Gesaan dan senario
Satu API pesanan menerima permintaan JSON. Klien mungkin menghantar data yang sah dari segi sintaks tetapi mempunyai hubungan medan yang tidak sah, mengemas kini pesanan daripada versi lama, atau cuba mencipta nama pengguna yang sudah wujud. Tentukan sempadan antara 409 dan 422 supaya klien tahu sama ada perlu mengedit permintaan, membaca semula sumber, atau berhenti mencuba lagi.
2. Perkara yang sedang diuji oleh penemu duga
- Sama ada anda memisahkan semantik permintaan yang tidak boleh diproses daripada konflik dengan keadaan semasa sumber.
- Sama ada anda tahu bahawa mengulangi permintaan 422 yang tidak diubah biasanya menghasilkan keputusan yang sama.
- Sama ada anda menghubungkan kawalan keserantakan, percubaan semula idempoten, dan kontrak ralat.
- Sama ada anda boleh meletakkan respons 400 dan 412 yang bersebelahan serta mengekalkan dasar yang konsisten.
3. Soalan penjelasan untuk ditanya
- Adakah API menggunakan ETag, nombor versi, atau mekanisme keserantakan optimistik yang lain?
- Adakah "nama sudah wujud" dimodelkan sebagai peraturan medan atau sebagai keadaan semasa sesuatu koleksi?
- Bolehkah klien membaca semula sumber dan menunjukkan perbezaan (diff) kepada pengguna?
- Adakah pasukan sudah menyeragamkan kod ralat, laluan medan (field path), dan tingkah laku percubaan semula?
4. Kerangka jawapan 30 saat
Kelaskan puncanya terlebih dahulu. Kembalikan 422 apabila pelayan memahami jenis media dan sintaks tetapi tidak dapat memproses semantik permintaan. Kembalikan 409 apabila permintaan yang difahami berkonflik dengan keadaan semasa sumber sasaran. Gunakan 400 untuk permintaan yang tidak dapat dihurai dan 412 untuk prasyarat permintaan bersyarat yang gagal apabila itu merupakan kontrak yang tepat. Akhiri dengan kod yang boleh dibaca mesin, panduan pembaikan, dan maklumat versi.
5. Penyelesaian langkah demi langkah
Langkah satu: Tentukan sempadan 422
422 bermaksud jenis kandungan dan sintaks difahami, tetapi arahan yang terkandung tidak dapat diproses. Contohnya termasuk tarikh tamat sebelum tarikh mula, nilai enum yang tidak dibenarkan, atau gabungan medan yang tidak sah. Kegagalan ini biasanya tidak bergantung pada siapa yang kali terakhir mengubah sumber, jadi klien perlu mengubah suai muatan sebelum menghantarnya semula.
Langkah dua: Tentukan sempadan 409
409 bermaksud permintaan berkonflik dengan keadaan semasa sumber sasaran. Kes biasa termasuk versi lapuk, membatalkan pesanan yang telah dihantar, atau mencipta sumber yang bertembung dengan sumber unik sedia ada. Sertakan versi semasa, jenis konflik, dan langkah praktikal seterusnya apabila selamat berbuat demikian.
Langkah tiga: Posisikan kod-kod bersebelahan
Gunakan 400 untuk JSON yang rosak atau sintaks yang hilang yang diperlukan untuk menghurai permintaan. Permintaan dengan If-Match yang gagal memenuhi syarat yang dinyatakan boleh menggunakan 412; ini lebih tepat daripada memanggil setiap kegagalan bersyarat sebagai 409. Dokumentasikan dasar yang dipilih supaya titik akhir tidak mencipta maksud yang tidak serasi.
Langkah empat: Reka bentuk percubaan semula dan badan ralat
Jangan cuba semula muatan 422 yang tidak diubah secara automatik kerana ia dijangka gagal lagi. Respons 409 mungkin boleh dibaiki: baca semula, gabungkan (merge), dan cuba lagi apabila jenis konflik membenarkannya, tetapi jangan sekali-kali mengulang tanpa henti. Kembalikan code yang stabil, laluan medan atau pengecam sumber, versi semasa, dan panduan pembaikan; pastikan kelayakan dan rahsia lain tidak dimasukkan ke dalam respons dan log.
6. Jawapan model
Saya mengelaskan kegagalan sebagai masalah semantik muatan atau perlumbaan keadaan sumber (state race). Julat tarikh yang terbalik, enum yang tidak sah, dan gabungan medan yang mustahil ialah 422. Pelayan yang memahami permintaan tetapi melihat pesanan yang telah dihantar, versi lapuk, atau sumber unik sedia ada boleh mengembalikan 409. JSON yang tidak terbentuk dengan betul ialah 400, dan syarat If-Match yang tidak dipenuhi boleh menjadi 412.
>
Untuk 422, saya mengembalikan kod perniagaan dan laluan medan yang stabil supaya klien mengedit data. Untuk 409, saya mengembalikan jenis konflik dan versi atau keadaan pelayan supaya klien boleh membaca semula dan memilih untuk menggabungkan, membatalkan, atau mencuba semula. Kedua-dua status tidak sepatutnya mencetuskan percubaan semula tanpa syarat; kunci keidempotanan menghalang pelaksanaan pendua tetapi tidak menghapuskan konflik keserantakan. Saya mendokumentasikan satu dasar untuk semua titik akhir dan memantau cara setiap ralat dibaiki.
7. Kesilapan lazim
- Mengembalikan 409 untuk setiap kegagalan pengesahan perniagaan, yang membayangkan bahawa membaca semula sumber akan membaikinya.
- Mengembalikan 422 untuk konflik versi dan menyembunyikan isyarat bahawa keadaan telah berubah.
- Menambah percubaan semula automatik tanpa had untuk mana-mana status dan mencetuskan ribut permintaan (request storm).
- Hanya mengembalikan mesej bacaan manusia tanpa kod yang stabil, laluan medan, atau arahan pembaikan.
- Memilih satu kod untuk setiap "pendua" tanpa mentakrifkan sama ada ia peraturan muatan atau konflik keadaan sumber.
8. Soalan susulan dan jawapan
Soalan susulan satu: Patutkah nama pengguna pendua menjadi 409 atau 422?
Jika keunikan dimodelkan sebagai keadaan semasa sesuatu koleksi, 409 menyampaikan konflik keadaan. Jika pasukan memodelkannya sebagai pengesahan semantik medan, 422 boleh menjadi konsisten. Kontrak yang stabil dan tingkah laku klien yang boleh diramal lebih penting daripada label sejagat.
Soalan susulan dua: Adakah setiap 409 boleh dicuba semula?
Tidak. Konflik versi mungkin boleh dicuba semula selepas penggabungan, manakala pembatalan pesanan yang telah dihantar harus dihentikan dan menunjukkan keadaan semasa. Respons harus menyampaikan sama ada konflik tersebut boleh dibaiki.
Soalan susulan tiga: Bolehkah 422 mewakili kegagalan kebenaran?
Ia tidak sepatutnya menggantikan semantik pengesahan (authentication) dan kebenaran (authorization). Pengesahan yang tiada biasanya 401, dan pemanggil yang disahkan tanpa kebenaran biasanya 403. Khaskan 422 untuk kandungan yang semantiknya tidak dapat diproses.