Prompt dan skop
Satu API menerima JSON dan CBOR untuk POST serta JSON Patch untuk PATCH. Klien menerima 415 selepas menghantar Content-Type, pengekodan kandungan, atau format dokumen patch yang salah. Reka bentuk pengelasan pelayan, pengepala respons, badan ralat, pemulihan klien, dan evolusi versi.
Ini adalah soalan kontrak API backend. Jenis media dan format merupakan andaian, bukan tuntutan kekerapan.
Perkara yang diuji oleh penemu bual
- Sama ada anda memisahkan Content-Type dan Content-Encoding permintaan daripada Accept respons.
- Sama ada anda menggunakan 415 secara khusus dan bukannya melabelkan setiap ralat penghuraian (parsing) dengan cara itu.
- Sama ada anda mendedahkan keupayaan PATCH dengan Accept-Patch sambil mengekalkan keserasian.
- Sama ada ralat tersebut boleh diambil tindakan tanpa fungsi main semula (replay) automatik yang tidak selamat.
Soalan penjelasan untuk ditanya
- Adakah 415 disebabkan oleh jenis media, pengekodan kandungan, atau keupayaan kaedah?
- Bolehkah klien mengekod semula badan permintaan, dan adakah terdapat ID permintaan yang stabil?
- Format patch dan syarat versi sumber yang manakah disokong?
- Bolehkah get laluan (gateway) menulis semula Content-Type, pengekodan, atau badan ralat?
- Bagaimanakah jenis media baharu akan dilancarkan tanpa menjejaskan klien lama?
Jawapan 30 saat
“415 bermaksud kaedah sasaran menolak format perwakilan permintaan. Pelayan menghuraikan Content-Type, parameter, dan Content-Encoding, kemudian memilih penghurai berdasarkan keupayaan kaedah dan sumber. Accept menerangkan format respons yang dikehendaki oleh klien; ia tidak menerangkan dokumen patch yang dihantar. Sumber PATCH boleh mengiklankan jenis dokumen yang disokong dengan Accept-Patch. Ralat mengembalikan kod yang stabil, nilai yang diterima dan dibenarkan, serta ID permintaan. Cuba semula hanya selepas pengekodan semula yang selamat dan analisis main semula.”
Reka bentuk langkah demi langkah
1. Pisahkan semantik ketiga-tiga pengepala
Content-Type menerangkan jenis media badan permintaan, Content-Encoding menerangkan pengekodan pemindahan, dan Accept menerangkan perwakilan respons yang boleh diterima oleh klien. Pelayan tidak boleh menggunakan Accept untuk mengelaskan dokumen PATCH atau menggabungkan penyahpemampatan, kerosakan data, dan media yang tidak disokong ke dalam satu punca.
2. Petakan keupayaan kaedah dan sumber
Setiap kaedah dan sumber mengisytiharkan jenis media dan parameter yang disokong. Contohnya, POST menerima application/json dan application/cbor, manakala PATCH menerima jenis dokumen JSON Patch yang berdaftar. Periksa jenis dan pengekodan sebelum menghurai; selepas menghurai, teruskan menjalankan pengesahan skema, kebenaran, dan logik perniagaan.
PATCH /documents/42 HTTP/1.1
Content-Type: application/json-patch+json
Accept: application/json
Content-Length: 1283. Kembalikan respons 415 yang tepat
Kembalikan 415 dengan kod ralat yang stabil apabila jenis media atau pengekodan kandungan tidak disokong. Gunakan ralat pengesahan domain untuk sintaks yang sah dengan medan yang tidak sah, dan ralat penghuraian yang jelas untuk kandungan yang tidak terbentuk dengan betul (malformed). Pengepala respons Accept boleh menerangkan perwakilan yang boleh dikembalikan oleh pelayan; ia bukan senarai jenis media permintaan.
4. Iklankan keupayaan PATCH
RFC 5789 mentakrifkan Accept-Patch; sumber boleh mengisytiharkan jenis media dokumen patch yang disokong dalam OPTIONS atau respons yang berjaya. Klien kemudian boleh memilih JSON Patch atau format lain, sementara pelayan masih memeriksa versi sumber, laluan, dan kebenaran. Pengiklanan mesti sepadan dengan set penghurai sebenar.
5. Jadikan pemulihan klien selamat
Selepas menerima 415, klien membaca kod yang stabil dan jenis yang dibenarkan, mengekod semula badan, atau memilih titik akhir yang serasi. Percubaan semula automatik memerlukan badan yang boleh dibina semula, tiada kesan sampingan yang tidak boleh diubah, dan kunci kedap pemulangan (idempotency key) yang sama. Jangan hantar semula PATCH yang mungkin telah berjaya, dan jangan anggap 415 sebagai ketiadaan perkhidmatan sementara.
6. Lancarkan dan pantau perubahan
Laksanakan pelancaran kanari (canary) untuk jenis media baharu melalui get laluan, pelayan, dan SDK, sambil mengekalkan tempoh keserasian untuk jenis lama. Bahagikan metrik mengikut sumber, kaedah, jenis yang diterima, pengekodan, versi klien, dan sebab penolakan. Log ID permintaan dan versi penghurai, jangan sekali-kali mencatat badan yang sensitif. Bandingkan pengepala pinggir (edge) dan aplikasi apabila get laluan menulis semula pengepala tersebut.
Contoh jawapan berkualiti tinggi
“Saya memisahkan format permintaan dan respons. Pelayan memeriksa Content-Type dan Content-Encoding mengikut kaedah dan sumber, hanya menghuraikan perwakilan yang disokong, kemudian menjalankan pengesahan skema dan perniagaan; Accept adalah untuk rundingan respons. Sumber PATCH mengiklankan jenis dokumen dengan Accept-Patch, tetapi setiap permintaan masih memeriksa versi dan kebenaran. Badan 415 memberikan kod yang stabil, nilai yang diterima dan dibenarkan, serta ID permintaan. Klien mencuba semula hanya selepas pengekodan semula yang selamat. Jenis baharu dilancarkan melalui matriks keserasian dan metrik supaya get laluan atau SDK lama tidak mengubah semantik secara senyap.”
Kesilapan lazim
- Menggunakan Accept untuk mengelaskan badan permintaan → rundingan permintaan dan respons bercampur aduk → periksa Content-Type dan Content-Encoding.
- Mengembalikan 415 untuk setiap kegagalan penghuraian → klien tidak dapat memilih kaedah pembaikan → pisahkan ralat media, sintaks, dan domain.
- Mengiklankan Accept-Patch tanpa penghurai → kontrak keupayaan adalah palsu → sahkan pengisytiharan terhadap pelaksanaan sebenar.
- Mencuba semula badan yang sama selepas 415 → ia akan gagal atau menduplikasi kesan sampingan → ubah pengekodan dan sahkan keselamatan main semula.
- Mencatat jenis hanya dalam aplikasi → penulisan semula oleh get laluan menjadi tidak kelihatan → bandingkan pengepala dan ID permintaan bagi setiap lompatan (hop).
Soalan susulan dan respons
Jika Content-Type sah tetapi Content-Encoding tidak disokong, adakah 415 masih betul?
RFC 9110 memasukkan pengekodan kandungan permintaan yang tidak boleh diterima ke dalam skop 415. Terangkan pengekodan tersebut dalam ralat, kemudian nyahpampat atau pilih pengekodan yang disokong sebelum memutuskan sama ada badan dan operasi boleh dicuba semula dengan selamat.
Mengapakah tidak hanya mengembalikan senarai jenis yang dibenarkan?
Senarai semata-mata mengabaikan kekangan kaedah, parameter, dan versi. Kod yang stabil, nilai yang diterima, skop yang dibenarkan, ID permintaan, dan pautan dokumentasi menjadikan pembaikan boleh diambil tindakan tanpa mendedahkan butiran dalaman.
Bagaimanakah anda menambah CBOR dengan selamat?
Dayakannya dahulu pada sumber yang tidak kritikal, sahkan laluan get laluan (gateway pass-through), had sumber penghurai, kesetaraan skema, dan penyuntingan (redaction) log. Kekalkan sandaran (fallback) JSON dan bandingkan 415, kegagalan penghuraian, serta hasil perniagaan mengikut versi klien.