Gesaan dan skop
Ini menguji reka bentuk protokol pada sempadan API. Dokumen yang dirujuk ialah Internet-Draft aktif yang diterbitkan pada 23 Mei 2026, bukan RFC; nyatakan status tersebut sebelum menggunakannya. Reka bentuk mesti kekal selamat jika pelaksanaan hanya menerima pakai sebahagian daripada cadangan tersebut.
Perkara yang dinilai oleh penemu duga
- Perbezaan yang tepat antara metadata dasar dan kuota tersedia semasa.
- Penghuraian structured-field, berbilang tetingkap, unit kuota dan kunci pemetakan (partition keys).
- Interaksi dengan 429, Retry-After, gerbang, CDN dan respons cache lapuk.
- Risiko privasi dan penafian perkhidmatan (denial-of-service) akibat mendedahkan had.
- Pengunduran klien yang menganggap pembayang sebagai tidak mengikat dan bertoleransi terhadap medan yang tiada atau salah bentuk.
Struktur jawapan yang disyorkan
Tentukan dimensi kuota dan pemilikan terlebih dahulu. Tunjukkan satu respons yang mengandungi dasar dan had semasa, kemudian terangkan cara klien menjadualkan kerja. Tambahkan peraturan cache dan perantara, kekangan keselamatan, keterlihatan (observability) dan pelan pelancaran dengan feature flag supaya draf boleh berubah tanpa merosakkan klien.
Perbincangan mendalam: jadikan pengepala berguna tanpa menjanjikan kapasiti
Asingkan dasar daripada keadaan semasa
RateLimit-Policy menerangkan kuota yang dinamakan, seperti "tenant";q=1000;w=60. RateLimit melaporkan kuota yang tersedia dan tetingkap berkesan, contohnya "tenant";r=420;t=23. Sesuatu dasar boleh mengandungi berbilang item dan tetingkap pembolehubah. Pelayan kekal sebagai pihak berkuasa: nilai-nilai ini adalah pembayang (hints), bukan pajakan atau jaminan tahap perkhidmatan.
Tentukan semantik pemetakan dan unit
Dokumenkan sama ada satu unit kuota bermaksud permintaan, bait, token atau operasi berwajaran. Kunci pemetakan boleh membezakan penyewa atau sumber, tetapi jangan sekali-kali meletakkan e-mel, ID pengguna mentah atau rahsia ke dalam pengepala. Pastikan nama dasar stabil dan mempunyai versi; menukar unit tanpa menukar pengecam dasar menjadikan kawalan kadar klien (client pacing) tidak selamat.
Selaraskan 429 dan Retry-After
Kembalikan Retry-After apabila pelayan mengetahui bila permintaan yang ditolak boleh dicuba semula. Jika kedua-dua medan wujud, klien memberi keutamaan kepada Retry-After; RateLimit membantu mengawal kadar kerja masa hadapan. Draf tersebut tidak memerlukan algoritma pendikit (throttling) tertentu, jadi klien masih memerlukan pengunduran eksponen dihadkan, variasi masa (jitter), batas masa (deadlines) dan peraturan keidempotetan untuk operasi tulis.
Layan cache dan perantara sebagai peserta
Nilai RateLimit pada respons yang dicache mungkin lapuk dan harus diabaikan apabila respons mempunyai usia semasa yang positif. Perantara yang tidak menyedari semantik kuota tidak boleh menjadikan respons kelihatan lebih longgar. Gerbang yang menguatkuasakan had yang lebih ketat boleh menyampaikan dasar yang lebih ketat itu, manakala telemetri merekodkan keputusan asal (origin) dan gerbang secara berasingan.
Lindungi ketersediaan dan privasi
Jangan dedahkan tetingkap kuota yang besar yang mendedahkan volum trafik atau membenarkan penyerang menguatkan permintaan. Hadkan nisbah antara kuota yang tersedia dan tetingkap berkesan, sahkan medan berstruktur yang diterima dan abaikan nilai yang salah bentuk. Menurunkan nilai yang diiklankan semasa ketepuan adalah dibenarkan, tetapi klien masih mesti mengendalikan penolakan walaupun pembayang terakhir kelihatan sihat.
Contoh jawapan
“Saya akan membuat versi dasar bernama bagi setiap penyewa dan operasi, menentukan unit dan mengeluarkan metadata dasar secara berasingan daripada kuota baki semasa. Draf ini ialah Internet-Draft, jadi klien menganggap kedua-dua medan sebagai pembayang pilihan. Retry-After mengawal permintaan yang ditolak; RateLimit mengawal kadar kerja masa hadapan. CDN menandakan nilai yang dicache sebagai lapuk, gerbang tidak pernah menjadikan had asal kelihatan lebih longgar dan kunci pemetakan tidak mengandungi pengecam. SDK menghuraikan medan berstruktur secara defensif, menggunakan jitter dan baris gilir kongsi, serta mendedahkan metrik untuk had yang diiklankan berbanding yang dikuatkuasakan sebelum kami mendayakan kontrak secara beransur-ansur.”
Mod kegagalan biasa dan pembaikan
- Memanggil draf sebagai RFC → Rekodkan status Internet-Draft dan asingkannya di sebalik kontrak berversi.
- Menggunakan baki kuota sebagai kebenaran mutlak → Layan ia sebagai pembayang; pelayan masih boleh menolak di bawah ketepuan.
- Mengembalikan pengecam pengguna dalam kunci pemetakan → Gunakan nama legap berkardinaliti rendah dan semak pendedahan privasi.
- Mempercayai pengepala yang dicache → Abaikan nilai lapuk dan biarkan asal menguatkuasakan had.
- Mencuba semula setiap 429 serta-merta → Patuhi
Retry-After, tambah jitter dan kuat kuasakan keidempotetan khusus kaedah.
Rubrik pemarkahan dan semakan kendiri
Nilaikan pengasingan dasar/keadaan, unit dan pemetakan, interaksi 429, tingkah laku cache, privasi, kawalan kadar klien, keselamatan pelancaran dan metrik. Jawapan yang kukuh menerangkan maksud setiap pengepala, perkara yang tidak dapat dijaminnya dan cara klien bertindak apabila medan tiada, lapuk atau salah bentuk.
Soalan susulan dan lanjutan
Bagaimana jika respons mempunyai dua tetingkap?
Pilih kekangan yang akan habis dahulu untuk kawalan kadar, sambil mengekalkan semua item untuk keterlihatan. SDK tidak sepatutnya meruntuhkan (collapse) tetingkap dengan unit atau kunci pemetakan yang berbeza secara senyap.
Patutkah respons yang berjaya menyertakan RateLimit?
Ia boleh disertakan, tetapi klien tidak boleh menganggap setiap respons mengandunginya. Keluarkan hanya apabila berguna untuk produk dan pastikan cache tidak boleh menukar nilai lama menjadi janji semasa.
Bagaimanakah anda melancarkan draf yang sedang berubah?
Rundingkan profil pengepala atau versi dasar, log sandaran penghurai (parser fallbacks), lakukan pelancaran kenari mengikut versi SDK dan pastikan tingkah laku 429 serta Retry-After kekal stabil sementara medan baharu adalah pilihan.
Metrik manakah yang membuktikan kontrak berfungsi?
Jejaki had yang diiklankan dan dikuatkuasakan, keputusan pengepala lapuk, kadar 429, penguatan percubaan semula, kelewatan baris gilir, kejayaan akhirnya dan kardinaliti pemetakan yang selamat dari segi privasi mengikut gerbang dan versi SDK.