Gesaan dan skop
Soalan backend ini menguji kontrak API dan sempadan kegagalan. Matlamatnya bukan untuk membungkus setiap pengecualian (exception) ke dalam satu objek JSON, tetapi untuk membolehkan klien mengambil tindakan yang stabil sementara log, penjejakan, kebenaran, dan teks paparan pengguna kekal sebagai lapisan berasingan.
Perkara yang dinilai oleh penemu duga
- Sama ada anda memahami hubungan antara
application/problem+jsondan kod status HTTP. - Sama ada pengesahan, pengesahan identiti (authentication), kebenaran (authorization), konflik, had kadar (rate limits), kegagalan sementara, dan ralat yang tidak diketahui dibezakan.
- Sama ada anda mereka bentuk ralat peringkat medan, tika (instance) yang boleh dijejaki, dan ahli sambungan yang terkawal.
- Sama ada anda mengelak daripada mendedahkan tindanan (stacks), ID dalaman, data peribadi, dan pengecualian mentah yang tidak dipercayai.
Soalan penjelasan untuk ditanya terlebih dahulu
Sahkan sama ada klien memerlukan keputusan mesin atau hanya teks paparan, sama ada penyetempatan, pengesahan kelompok (batch), dan kerja tak segerak (asynchronous) wujud, sama ada jenis dikongsi merentasi perkhidmatan, keadaan mana yang boleh dicuba semula, dan perkara yang dicatat dalam log, dipaparkan, serta digunakan untuk korelasi permintaan oleh get laluan (gateway), perkhidmatan, dan klien.
Struktur jawapan 30 saat
Gunakan application/problem+json dengan type, title, status, detail, dan instance sebagai asas yang stabil. Tambah sambungan terkawal untuk kod, laluan medan, masa cuba semula, dan versi dokumentasi. Status HTTP membawa semantik umum dan type membawa kategori yang boleh diprogramkan; punca dalaman kekal dalam log sementara respons mengandungi maklumat yang selamat dan boleh diambil tindakan.
Jawapan mendalam
1. Menetapkan sempadan status dan jenis
Gunakan 400 untuk kegagalan sintaks atau permintaan umum, 401 untuk pengesahan identiti yang hilang, 403 untuk permintaan yang dikenali tetapi tidak dibenarkan, 404 untuk sumber yang hilang, 409 untuk konflik keadaan semasa, 429 untuk pengehadan kadar (rate limiting), dan 5xx untuk kegagalan pelayan atau kebergantungan. Jadikan type sebagai URI yang stabil dan didokumentasikan; klien tidak seharusnya menghuraikan teks title atau detail yang mudah berubah.
2. Mereka bentuk medan Problem Details
type mengklasifikasikan masalah, title ialah ringkasan manusia yang stabil, status mencerminkan respons, detail menerangkan permintaan ini, dan instance mengenal pasti kejadian ini. Sambungan boleh merangkumi kod, laluan medan, nama parameter, masa cuba semula, atau versi dokumentasi, dengan kosa kata dan panjang yang terhad. Pengesahan kelompok boleh mengembalikan tatasusunan di mana setiap item menunjuk kepada lokasi input.
3. Mengendalikan pengesahan, konflik, dan percubaan semula
Kegagalan pengesahan harus memberitahu klien cara membetulkan medan dan tidak seharusnya meminta percubaan semula. Konflik memerlukan bacaan semula atau tindakan perniagaan yang berbeza. 429 atau kegagalan kebergantungan sementara boleh menyertakan Retry-After, tetapi klien masih memerlukan penundaan (backoff) dan had percubaan. Jadikan kebolehan cuba semula eksplisit dan bukannya meminta klien menyimpulkannya daripada lambakan respons 200.
4. Melindungi sempadan keselamatan dan privasi
Jangan sekali-kali menyertakan tindanan (stacks), SQL, kunci, nama hos dalaman, butiran rentas penyewa (cross-tenant), atau rekod peribadi yang lengkap. Detail hanya perlu menyatakan fakta yang boleh diambil tindakan; instance harus menjadi rujukan yang tidak dapat diramalkan atau terkawal. Hubung kaitkan pengecualian mentah dalam log dalaman dengan ID permintaan. Elakkan kebocoran penghitungan akaun dalam ralat pengesahan identiti dan tapis ralat medan mengikut kebenaran.
5. Berkembang merentasi perkhidmatan dan versi
Letakkan jenis, status, dan sambungan yang dikongsi dalam dokumentasi berversi dan ujian kontrak; get laluan tidak seharusnya menulis semula semantik perkhidmatan. Tambah medan secara serasi dan sediakan tempoh penghijrahan untuk jenis yang ditamatkan. Klien harus berbalik (fallback) kepada status dan butiran yang selamat untuk jenis yang tidak diketahui. Pantau pengagihan jenis, kejayaan percubaan semula, kawasan kerap berlaku ralat medan, dan kebolehjejakan ID permintaan.
Contoh jawapan yang kukuh
Saya akan mengisytiharkan setiap ralat sebagai application/problem+json dengan type URI, title, status, detail, dan instance yang stabil. Bezakan 400/401/403/404/409/429 dan 5xx melalui semantik HTTP; tambah laluan medan dan kod yang selamat untuk pengesahan, serta Retry-After untuk pengehadan kadar atau kegagalan kebergantungan sementara. Klien menggunakan type untuk memutuskan sama ada mahu membetulkan, mengambil semula, melakukan backoff, atau menghubungi sokongan daripada menghuraikan butiran yang tidak menentu. Log dalaman mengekalkan tindanan, keadaan kebergantungan, dan ID permintaan, sementara respons mengecualikan SQL, kunci, data penyewa, dan rekod peribadi. Jenis berversi dan ujian kontrak melindungi evolusi rentas perkhidmatan; jenis yang tidak diketahui berbalik kepada status. Pantau jenis ralat, hasil percubaan semula, dan kawasan kerap berlaku ralat medan selepas pelancaran.
Kesilapan biasa
- Mengembalikan 200 dan satu ayat untuk setiap ralat, menyebabkan klien tidak dapat membuat keputusan secara berprogram.
- Menjadikan klien bergantung pada perkataan harfiah title atau detail, sehingga terjemahan merosakkan kelakuan sistem.
- Melabelkan pengesahan, konflik, had kadar, dan kegagalan sementara sebagai 500.
- Mengembalikan tindanan (stacks), SQL, nama hos dalaman, atau data pengguna yang lengkap dalam detail.
- Mendedahkan nama kelas pengecualian dalaman sebagai jenis awam dan membekukan butiran pelaksanaan ke dalam kontrak.
- Tidak mempunyai sandaran (fallback) untuk jenis yang tidak diketahui atau tiada ujian kontrak rentas perkhidmatan.
Soalan susulan
Adakah type mesti merupakan URL yang boleh dicapai?
Ia harus menjadi URI yang stabil dan boleh menunjuk kepada dokumentasi penerangan, tetapi klien tidak seharusnya memerlukan permintaan rangkaian untuk pengendalian. Ciri-ciri yang penting ialah identiti semantik, pemversian, dan panduan penghijrahan.
Patutkah detail disetempatkan?
Pastikan medan mesin dan type kekal stabil dan paparkan teks pengguna pada klien untuk bahasa dan konteksnya. Jika pelayan mesti mengembalikan detail, gunakan templat yang selamat dan rundingan bahasa; jangan sekali-kali mendedahkan pengecualian dalaman yang tidak diterjemahkan.
Patutkah get laluan menulis semula setiap ralat?
Ia boleh menambah ID permintaan, ralat tamat masa (timeout), dan kegagalan peringkat protokol, tetapi harus mengekalkan jenis perniagaan. Penulisan semula memerlukan peraturan berversi dan kebolehcerapan atau klien akan melihat semantik yang tidak lagi sepadan dengan punca sebenar.
Bagaimanakah anda mengendalikan kejayaan separa dalam permintaan kelompok?
Tentukan hasil kelompok dengan status setiap item, lokasi input, dan kebolehan cuba semula, serta nyatakan maksud status HTTP keseluruhan. Butiran yang samar-samar tidak dapat menyatakan kejayaan separa, dan klien tidak boleh menghantar semula item yang telah berjaya.