Gesaan dan skop
API awam memerlukan medan respons Features yang mengandungi nama keupayaan, keutamaan, dan parameter eksperimen. Klien, CDN, get laluan, dan SDK dalam beberapa bahasa akan membacanya; klien legasi hanya boleh mengabaikan medan yang tidak diketahui. Reka bentuk format medan, peraturan pensirilan dan penghuraian, dasar keserasian, dan pelan pengesahan.
Ini adalah soalan kontrak API backend. Kuncinya adalah menukar "pengepala seperti rentetan" menjadi protokol yang boleh saling kendali. RFC 8941 mentakrifkan model Item, List, Dictionary, dan parameter yang biasa, dan RFC 9651 adalah semakannya. RFC 9110 memerlukan medan baharu untuk menyatakan tatabahasanya dan menolak aksara kawalan yang berbahaya. Anda tidak perlu melaksanakan setiap algoritma RFC, tetapi anda mesti mentakrifkan sempadannya.
Perkara yang diuji oleh penemu duga
Penemu duga ingin melihat sama ada anda mentakrifkan semantik sebelum memilih List, Dictionary, atau Item dan bukannya menggabungkan teks yang dipisahkan koma. Jawapan yang kukuh merangkumi pensirilan penghantar, penghuraian penerima, ahli yang tidak diketahui, gabungan medan pendua, had saiz, dan telemetri.
Jawapan yang lemah menunjukkan satu nilai sampel. Jawapan yang kukuh menjelaskan sebab set keupayaan ialah Dictionary, sebab kunci parameter menggunakan huruf kecil, sebab teks bukan ASCII sewenang-wenangnya tidak boleh disembunyikan dalam String, dan cara kegagalan penghuraian mengelakkan pengaktifan ciri secara tidak sengaja. Panduan temu duga API backend semasa juga menekankan kontrak yang stabil, keserasian ke belakang, dan mod kegagalan.
Soalan untuk dijelaskan terlebih dahulu
Semantik medan dan sempadan kepercayaan
Sahkan sama ada ini adalah petunjuk (hint), keputusan kebenaran, atau fakta perniagaan. Jika ia mempengaruhi kebenaran, pengebilan, atau keselamatan, pelayan kekal sebagai pihak berkuasa dan tidak boleh mempercayai gemaan (echo) klien. Tanya sama ada medan itu boleh dicache dan sama ada nilainya berbeza mengikut pengguna.
Jenis dan sampul keserasian
Tanya sama ada nilai tersebut adalah set keupayaan tanpa tertib, senarai keutamaan yang tertib, atau satu pengecam versi. Sahkan sama ada klien lama mesti terus berfungsi, sama ada parameter baharu mungkin muncul, dan sama ada get laluan menggabungkan baris medan pendua. Jawapan tersebut menentukan jenis bekas dan dasar ahli yang tidak diketahui.
Belanjawan kegagalan dan sumber
Tentukan sama ada input tidak sah menyebabkan keseluruhan medan, satu ahli, atau respons diabaikan. Tetapkan had bait, ahli, penyarangan (nesting), dan masa penghuraian; pilihan ini menjadi sebahagian daripada sempadan DoS.
Rangka kerja jawapan 30 saat
"Saya akan mentakrifkan ini sebagai kontrak mesin yang boleh diberi versi, bukan JSON yang tersembunyi dalam rentetan. Set keupayaan menggunakan Dictionary, dengan setiap kunci membawa Item boolean atau berparameter; kunci dan parameter mengikut peraturan pensirilan RFC, dan ahli yang tidak diketahui diabaikan. Pelayan mengeluarkan ASCII terhad dan menguatkuasakan had jumlah saiz dan ahli. Penerima menggunakan tatabahasa yang sama, menganggap sintaks tidak sah sebagai ketiadaan medan, dan tidak pernah membuat kesimpulan bahawa sesuatu ciri diaktifkan. Saya akan menguji gabungan medan pendua dan variasi cache di get laluan, melakukan penghuraian bayangan (shadow-parse) terlebih dahulu, dan membandingkan kegagalan penghuraian, saiz medan, dan pengaktifan ciri yang tidak disengajakan sebelum pelancaran."
Penyelesaian langkah demi langkah
Langkah 1: Modelkan nilai sebelum memilih bekas
Gunakan Dictionary untuk suis keupayaan, seperti search;v=2, upload=?1. Gunakan List apabila setiap ahli mempunyai susunan atau parameter yang bermakna. Gunakan Item untuk satu versi atau nama dasar. Jangan letakkan JSON di dalam pengepala semata-mata untuk kemudahan: perantara dan SDK masih memerlukan penghurai tersuai.
Langkah 2: Takrifkan medan yang boleh diperluas
Takrifkan kunci seperti search dan upload; parameter seperti v=2 dan tier="pro" hanya menggunakan jenis yang dibenarkan oleh tatabahasa medan berstruktur. Kunci parameter menggunakan huruf kecil. Simpan teks paparan di luar medan, atau gunakan sambungan Display String yang disokong secara jelas selepas memeriksa setiap perantara. Dokumentasikan semantik setiap ahli, lalai, dan akibat nilai tidak sah.
Features: search;v=2, upload=?1Pensirilan mestilah bersifat deterministik supaya nilai yang setara tidak menghasilkan perbezaan kunci cache atau tandatangan yang tidak perlu. Penerima tidak boleh menggantikan penghurai peka tatabahasa dengan split(','); koma, tanda kurung, tanda petik, dan parameter mempunyai sempadan yang ditakrifkan.
Langkah 3: Nyatakan medan pendua dan ahli yang tidak diketahui
Mula-mula nyatakan sama ada baris berulang dibenarkan. Jika medan tersebut ialah Dictionary, perisian tengah boleh menggabungkan baris, jadi kontrak mesti mentakrifkan makna gabungan dan peraturan konflik untuk kunci pendua. Abaikan kunci yang tidak diketahui dan parameter pilihan secara lalai. Untuk kunci yang diketahui dengan jenis yang tidak sah, gugurkan ahli tersebut atau medan lengkap, tetapi jadikan pilihan itu normatif. Suis keselamatan tidak boleh diaktifkan semata-mata kerana penghuraian gagal.
Langkah 4: Bina sempadan penghuraian yang ketat tetapi boleh digunakan
Hadkan jumlah bait, ahli, kedalaman penyarangan, dan masa CPU sebelum penghuraian mendalam. Tolak CR, LF, NUL, dan aksara lain di luar tatabahasa medan. Input luaran tidak memerlukan penghuraian masa malar, tetapi laluan pengecualian tidak boleh menghuraikan nilai yang besar secara berulang kali. Rekodkan kegagalan yang dikategorikan tanpa melog keseluruhan medan yang berpotensi sensitif.
Langkah 5: Kendalikan cache, tandatangan, dan evolusi
Jika medan berbeza mengikut pengguna atau kohort eksperimen, gunakan tingkah laku respons Vary yang betul atau cache peribadi; jika tidak, CDN boleh mendedahkan keupayaan seorang pengguna kepada pengguna lain. Jika medan dilindungi oleh HTTP Message Signatures, penandatangan dan pengesah memerlukan nilai berstruktur kanonikal yang sama. Kunci tambahan dan parameter pilihan harus kekal boleh diabaikan oleh klien lama; mengalih keluar atau menukar semantik memerlukan versi atau tempoh migrasi.
Langkah 6: Buktikan reka bentuk dengan pelancaran dan contoh kontra
Lakukan penghuraian bayangan terlebih dahulu tanpa mengubah tingkah laku, kemudian dayakan kohort dalaman yang kecil. Uji kunci pendua, senarai kosong, tanda petik rosak, parameter tidak diketahui, medan bersaiz lebih, gabungan proksi, dan ketidakpadanan cache. Bandingkan kejayaan penghuraian, pengaktifan tidak sengaja, bait respons, CPU, capaian cache, dan versi SDK dengan dan tanpa medan tersebut. Setiap kegagalan penghuraian kembali kepada lalai yang selamat.
Contoh jawapan berkualiti tinggi
Saya akan menganggap ini sebagai masalah reka bentuk protokol. Mula-mula saya akan mengesahkan sama ada medan itu hanyalah petunjuk keupayaan; jika ia mengawal kebenaran, pelayan kekal berwibawa. Untuk set keupayaan, saya akan memilih Structured Field Dictionary dan mentakrifkan setiap kunci sebagai Item boolean atau berparameter. Saya tidak akan menggunakan List untuk keupayaan tanpa tertib. Kontrak akan menetapkan pensirilan, jenis parameter, baris pendua, ahli yang tidak diketahui, dan akibat nilai tidak sah.
Penghantar mengeluarkan ASCII terhad dan menguatkuasakan had saiz medan dan ahli. Penerima menggunakan penghurai serasi RFC dan bukannya memisahkan rentetan pada koma, menolak aksara kawalan, mengabaikan kunci yang tidak diketahui, dan menganggap kunci yang diketahui dengan jenis yang salah sebagai tiada. Get laluan mempunyai satu peraturan gabungan pendua yang tetap, tidak pernah secara tidak sengaja membiarkan "nilai terakhir menang."
Saya juga akan menyemak tingkah laku cache dan tandatangan: keupayaan khusus pengguna memerlukan Vary, cache peribadi, atau tanpa cache, dan kedua-dua belah tandatangan mesti menormalkan nilai secara serupa. Saya akan melakukan penghuraian bayangan, kemudian melancarkan secara kenari (canary) medan tersebut sambil memantau kegagalan penghuraian, pengaktifan tidak sengaja, saiz, dan CPU. Klien lama terus mengabaikan medan tersebut; hanya klien yang menyokong versi tersebut secara eksplisit mendayakan tingkah laku baharu.
Kesilapan biasa
- Meletakkan JSON dalam pengepala rentetan → Proksi dan SDK masih memerlukan penghuraian tersuai, dengan pelepasan aksara (escaping) dan semantik pendua yang tidak konsisten → Gunakan model RFC Item, List, atau Dictionary dan dokumentasikan maksud ahli.
- Menghuraikan dengan
split(',')→ Tanda petik, senarai dalaman, dan pembatas parameter dipotong secara salah → Gunakan penghurai peka tatabahasa dan ujian sintaks tidak sah. - Gagal pada setiap parameter yang tidak diketahui → Penghantar baharu tidak boleh saling kendali dengan klien lama → Abaikan parameter sambungan melainkan kekangan keselamatan yang diketahui gagal.
- Mendayakan ciri selepas kegagalan penghuraian → Pemotongan atau manipulasi perantara boleh bertukar menjadi eksperimen atau keistimewaan yang tidak disengajakan → Kembali kepada lalai yang selamat dan rekodkan kegagalan yang dikategorikan.
- Mengabaikan variasi cache → CDN boleh menggunakan semula keupayaan diperibadikan untuk pengguna lain → Tetapkan
Vary, gunakan cache peribadi, atau jangan gunakan cache.
Soalan susulan dan jawapan
Soalan susulan 1: Mengapa tidak meletakkan ini dalam JSON respons?
JSON mungkin lebih baik apabila keupayaan hanyalah data perniagaan dalam badan respons. Structured Fields berguna apabila metadata HTTP, get laluan, dan dasar cache perlu memeriksa nilai sebelum menggunakan badan respons. Jangan berikan autoriti bebas kepada kedua-dua perwakilan; jika kedua-duanya wujud, tentukan keutamaan dan kesan percanggahan.
Soalan susulan 2: Bagaimana jika beberapa proksi menggabungkan medan tersebut?
Nyatakan sama ada baris berulang adalah sah dan normalkannya menjadi satu input penghurai pada sempadan yang dipercayai. Untuk Dictionary, tolak kunci pendua atau tentukan peraturan konflik yang jelas; jangan bergantung pada mana-mana nilai yang kebetulan berada di kedudukan terakhir. Ujian integrasi harus merangkumi baris berulang HTTP/1.1, perwakilan medan HTTP/2, dan laluan CDN sebenar.
Soalan susulan 3: Bagaimana jika parameter baharu memerlukan teks bukan ASCII?
Jangan letakkan UTF-8 secara terus dalam jenis String yang dihadkan oleh tatabahasa yang dipilih. Takrifkan dan sahkan sambungan Display String yang disokong, atau simpan teks paparan dalam badan respons dan bawa pengecam stabil dalam medan. Dayakannya hanya selepas setiap perantara dan SDK menyokong jenis tersebut.
Soalan susulan 4: Penghurai menyebabkan lonjakan CPU. Apakah yang anda lakukan?
Perketatkan serta-merta had bait, ahli, penyarangan, dan bilangan parameter serta anggap medan yang melebihi had sebagai tiada. Simpan cincangan (hash) input dan kategori kegagalan untuk diagnosis, bukan nilai lengkap. Memindahkan penghuraian kepada pekerja yang dihadkan boleh mengurangkan radius kesan (blast radius), tetapi ia tidak boleh menggantikan had tatabahasa dan pengembalian semula (rollback) kenari.