Temu Duga Backend: Bagaimanakah Anda Menstandardkan Ralat HTTP API dengan RFC 9457?

Perkara yang dinilai oleh penemu duga

API berbilang penyewa mengeluarkan ralat daripada get laluan, aplikasi, dan kerja tak segerak, menyebabkan klien tidak dapat menghuraikan kegagalan dengan pasti. Menggunakan RFC 9457, reka bentuk kontrak ralat yang dikongsi dan terangkan kod status, jenis media, URI jenis, pengesahan kelompok, percubaan semula, penyuntingan data sensitif, dan keserasian versi.

Konteks dan kekangan

• Sesuatu permintaan boleh merentasi CDN, API gateway, perkhidmatan perniagaan, dan baris gilir (queue).
• Klien mesti membezakan ralat input yang boleh diperbetulkan, kegagalan kebenaran, pengehadan kadar (throttling), dan kegagalan sementara (transient faults).
• Butiran tidak boleh mendedahkan surihan tindanan (stack traces), kunci, data pengasingan penyewa, atau nama hos dalaman.
• Klien sedia ada menghuraikan medan legasi, jadi migrasi mesti kekal serasi ke belakang (backward compatible).

Asingkan semantik HTTP daripada butiran perniagaan

Status HTTP menyatakan hasil pada peringkat protokol; badan Problem Details menerangkan puncanya. Pilih 400, 401, 403, 404, 409, 429, dan 5xx mengikut semantiknya daripada mengembalikan 200 untuk setiap kegagalan. Gunakan URI yang stabil dalam type untuk pengelasan mesin, title untuk persembahan, dan detail khusus bagi permintaan tersebut.

Tentukan kontrak boleh diperluas yang minimum

Ahli teras ialah type, title, status, detail, dan instance. Namakan sambungan secara eksplisit, seperti errors untuk masalah medan dan retryAfter untuk petunjuk masa menunggu klien. Dokumentasi bagi setiap jenis hendaklah menyatakan maksudnya, kod status yang dibenarkan, dan tindakan klien; klien tidak boleh membuat cawangan logik berdasarkan tajuk bahasa semula jadi.

Kongsi sempadan ralat merentas lapisan

Ralat tamat masa, pengesahan, dan throttling yang dijana oleh get laluan menggunakan jenis media yang sama tetapi tidak boleh menyamar sebagai jenis perniagaan aplikasi. Perkhidmatan menyimpan kod ralat dalaman untuk telemetri sambil hanya mendedahkan jenis yang diluluskan. Sebarkan ID korelasi merentas perkhidmatan tanpa menyalin teks butiran yang sensitif.

Soalan penjelasan sebelum menjawab

• Adakah klien membuat cawangan berdasarkan status, type, atau code legasi? Ini menentukan penyesuai migrasi.
• Bolehkah satu respons mengandungi pelbagai kegagalan pengesahan medan? Ini menentukan bentuk dan jaminan susunan errors.
• Adakah get laluan boleh memahami ralat perniagaan, atau hanya memindah dan mencipta ralat infrastruktur? Ini menentukan pemilikan jenis.

Kerangka jawapan 30 saat

"Saya akan mengekalkan status HTTP yang betul dan mengembalikan application/problem+json dengan type, title, status, detail yang stabil, dan instance pilihan. Klien membuat cawangan berdasarkan status dan type, tidak sekali-kali berdasarkan prosa; get laluan hanya memiliki jenis ralatnya sendiri. Pengesahan, petunjuk percubaan semula, ID korelasi, dan peraturan penyuntingan data sensitif menjadi kontrak berversi yang disahkan melalui matriks keserasian dan laluan permintaan sebenar."

Penyelaman mendalam langkah demi langkah

Mulakan dengan pendaftaran jenis ralat (type registry). Setiap jenis mempunyai URI, ahli awam, status yang dibenarkan, tindakan klien, dan tahap keselamatan. Kegagalan pengesahan menggunakan 400 dengan masalah medan di bawah errors; identiti yang hilang dan kebenaran yang tidak mencukupi kekal sebagai 401 dan 403; konflik concurrency optimistik menggunakan 409; throttling menggunakan 429 dengan petunjuk menunggu yang boleh diambil tindakan; kegagalan yang tidak diketahui menggunakan 500 atau 503 dan jenis awam generik.

Pastikan Content-Type konsisten dengan representasi. Nilai instance boleh mengenal pasti satu permintaan untuk sokongan, tetapi detail tidak boleh mengandungi URL penuh, SQL, surihan tindanan, atau pengenal pasti penyewa. Log menyimpan punca dalaman, ID korelasi, dan medan audit keselamatan; klien hanya menerima kandungan yang ditapis mengikut dasar.

Untuk pengesahan kelompok, tentukan sama ada pelbagai isu dibenarkan, bagaimana laluan medan ditulis, dan bilangan maksimum entri. Klien mengabaikan ahli sambungan yang tidak dikenali. Ahli baharu bersifat aditif; menukar maksud type sedia ada memerlukan URI baharu. Kerja tak segerak mendedahkan kegagalannya melalui sumber kerja dan bukannya membocorkan butiran dalaman baris gilir secara segerak.

Model jawapan berkualiti tinggi

"Saya akan mengekalkan pendaftaran jenis dan memastikan get laluan, perkhidmatan segerak, dan kerja tak segerak mengeluarkan application/problem+json yang serasi dengan RFC 9457. Status menyampaikan semantik protokol, type menyampaikan kategori yang stabil, dan detail hanya menerangkan permintaan ini. Pengesahan medan menggunakan sambungan errors yang dihadkan; 429 mempunyai petunjuk menunggu yang boleh dihuraikan; 500 dan 503 menggunakan jenis awam generik manakala tindanan kekal dalam log. Semasa migrasi, saya mengekalkan code legasi, kemudian menukar klien melalui ujian kontrak, matriks keserasian, dan audit penyuntingan data sensitif."

Kesilapan lazim

• Mengembalikan 200 dengan medan kegagalan perniagaan, menyebabkan cache, pemantau, dan pencuba semula menganggapnya berjaya.
• Membuat cawangan pada title atau detail, menyebabkan terjemahan atau perubahan perkataan merosakkan klien.
• Membiarkan setiap perkhidmatan mencipta URI type sendiri, menghalang pengagregatan yang konsisten.
• Mengembalikan surihan tindanan, SQL, domain dalaman, atau pengenal pasti penuh penyewa dalam detail.
• Menukar tamat masa get laluan menjadi ralat perniagaan, menyebabkan percubaan semula yang salah atau panduan pengguna yang silap.

Gejala kegagalan dan penyelesaian

Apabila klien tidak dapat memutuskan sama ada hendak mencuba semula, status, jenis, dan panduan percubaan semula biasanya tidak selaras. Bina pendaftaran terlebih dahulu, petakan setiap lapisan kepada set awam yang kecil, tentukan lalai selamat untuk jenis yang tidak diketahui, dan jejak punca dalaman dengan ID korelasi.

Pelaksanaan pengeluaran

Pusatkan penyirikan (serialization) dalam pustaka dikongsi atau penyesuai pinggir (edge adapter) sambil mengekalkan pemilihan status pada sempadan perkhidmatan. Pengesahan skema mengehadkan panjang sambungan, kiraan tatasusunan, dan format URI; sunting data sensitif sebelum penyirikan daripada hanya mempercayai get laluan. Tentukan undur eksponen (exponential backoff), jitter, dan syarat keidempotanan secara berasingan untuk 429, 503, dan tamat masa rangkaian bagi mengelakkan ribut percubaan semula (retry storms).

Senarai semak pengesahan

Ujian kontrak meliputi status setiap jenis awam, jenis media, ahli yang diperlukan, dan sambungan. Ujian integrasi merentasi get laluan, perkhidmatan, dan baris gilir serta mengesahkan ID korelasi dan penyuntingan data. Ujian keserasian menggunakan klien legasi untuk mengesahkan toleransi terhadap ahli yang tidak diketahui dan code yang dikekalkan. Ujian beban mengukur kependaman penyirikan, persampelan log, dan penguatan percubaan semula di bawah throttling.

Soalan susulan dan jawapan

Mengapa tidak menentukan satu kod ralat perniagaan sahaja?

Satu kod tunggal tidak dapat menyatakan semantik caching HTTP, pengesahan, throttling, dan percubaan semula. Status membolehkan infrastruktur generik berfungsi dengan betul; type membawa kategori perniagaan yang stabil. Kedua-duanya mempunyai tanggungjawab yang berbeza.

Adakah URI type mesti boleh dicapai (reachable)?

Spesifikasi membenarkan URI relatif atau mutlak. Pilih bentuk yang stabil dan boleh didokumenkan, tetapi jangan jadikan ketersediaan halaman dokumentasi sebagai prasyarat untuk pengendalian klien.

Bagaimanakah anda menghalang badan ralat daripada membocorkan data?

Gunakan senarai dibenarkan (allowlist) bagi ahli awam, had panjang, dan pengimbasan corak sensitif. Petakan pengecualian dalaman kepada jenis generik dan simpan hanya ID korelasi untuk sokongan. Ujian keselamatan meliputi pertanyaan merentas penyewa, kegagalan kebenaran, dan laluan pengecualian.

Rubrik pemarkahan

• Ketepatan semantik: membezakan maksud status HTTP daripada ahli Problem Details.
• Reka bentuk kontrak: mencadangkan jenis yang stabil, sambungan, dan pemversian.
• Kesedaran sempadan: meliputi get laluan, kerja, penyuntingan data sensitif, dan ribut percubaan semula.
• Kebolehlaksanaan: merangkumi pendaftaran, sempadan penyirikan, matriks keserasian, dan ujian.
• Kawalan risiko: mengelakkan kebocoran dan tidak menganggap jenis yang tidak diketahui sebagai boleh dicuba semula secara lalai.

Pemeriksaan pematuhan

Sahkan bahawa kod status, medan jenis, penyuntingan data sensitif, dan sempadan percubaan semula kekal konsisten.

Senarai semak jawapan temu duga

Mulakan dengan semantik status, kemudian terangkan bahawa type ialah pengenal pasti stabil untuk mesin dan detail bukan kunci kontrak. Tambahkan bukti pemilikan get laluan, pengesahan, percubaan semula, penyuntingan data, dan keserasian.

Rumusan satu ayat

Standardkan ralat dengan menjadikan status menyatakan semantik protokol, type menyatakan pengelasan yang stabil, dan sambungan menyatakan butiran yang boleh diambil tindakan, dengan ujian keselamatan dan keserasian melindungi sempadan sistem.