公開 API
每個 API 金鑰依方案取得一項限制，對行為良好的用戶端容許突發，對其餘的則給出精確的 Retry-After。
核心資料API
速率限制
原子的伺服器端速率限制。一個指令即可使用 GCRA，或使用具名限制器搭配滑動視窗、權杖桶或漏桶。不需要 Lua。
- 個原子指令，每個請求
- 1
- 種演算法
- 4
- 個 Lua 腳本
- 0
步驟 1 ／ 5
允許
使用者 42 每分鐘 10 個請求。回覆內容包含允許、上限與剩餘數量。
範例工作階段playing
# 允許
hotkv> GCRA.LIMIT ratelimit:user:42 60000 10
1) (integer) 0
2) (integer) 10
3) (integer) 9
4) (integer) -1
5) (integer) 6000
以真實 HotKV 指令與範例回覆呈現的動畫導覽。點擊任一步驟即可跳到該步驟。 指令與回覆維持英文，與您在 HotKV 中輸入及看到的完全一致。
問題
沒有限制的 API，離中斷只差一個行為不當的用戶端。在應用程式程式碼中做檢查，意味著一次讀取、一次計算與一次寫入，而並行的請求會從它們之間的縫隙溜過去。許多團隊最後只為了讓它具備原子性，而得維護一個 Lua 腳本。
HotKV 如何處理
GCRA.LIMIT 在同一步中完成判斷與記錄，因此並行的用戶端不可能依據同一個狀態同時通過，額度也會平順地回補，而不是在視窗邊界重置。對於您依名稱管理的限制，RATELIMIT.CREATE 會設定滑動視窗、權杖桶或漏桶限制器，並附帶允許與拒絕數量的統計。
逐步說明
逐個指令看看發生了什麼事
- 01
允許
使用者 42 每分鐘 10 個請求。回覆內容包含允許、上限與剩餘數量。
GCRA.LIMIT ratelimit:user:42 60000 10 - 02
來自機器人的突發流量
爬蟲用完它的突發額度後，會被告知需要等待多久。被拒絕的請求不會改變任何狀態。
GCRA.LIMIT ratelimit:bot:7 60000 10 - 03
為方案設定具名限制器
免費方案的客戶在滑動視窗上每分鐘可有 100 個請求。
RATELIMIT.CREATE free_plan 100 60000 ALGO sliding_window - 04
加權的請求
匯出端點的成本是 20 個單位，因此會消耗更多額度。
RATELIMIT.CHECK free_plan customer:881 COST 20 - 05
查看限制器做了什麼
設定、被追蹤的鍵，以及允許與拒絕請求的總數。
RATELIMIT.STATS free_plan
適用之處
真實世界的情境
登入與註冊表單
依 IP 與依帳戶限制嘗試次數，以減緩撞庫攻擊。
對外呼叫
讓呼叫夥伴 API 或 LLM 供應商的次數，在整個叢集的所有工作者之間維持在其配額之下。
內建
您能獲得什麼
一個指令即可使用 GCRA
平順回補並容許突發、原子的檢查與更新，被拒絕時提供重試時間。
GCRA.LIMITGCRA.RESET具名限制器
滑動視窗、權杖桶或漏桶，建立一次後依鍵檢查。
RATELIMIT.CREATERATELIMIT.CHECK加權請求
昂貴的呼叫可以算作多個請求。GCRA.LIMIT 接受計數，RATELIMIT.CHECK 則接受 COST。
COST統計
依限制器提供允許與拒絕的總數。
RATELIMIT.STATS常見問題
速率限制需要 Lua 腳本嗎？
不需要。GCRA.LIMIT 與 RATELIMIT.CHECK 都以單一原子指令完成整個檢查。
我該用哪一個？
GCRA.LIMIT 不需要任何設定，在每個方案上都能使用。RATELIMIT.* 具名限制器則多了演算法選擇與統計，屬於 Performance 與 Scale 方案。
被拒絕的請求要付出什麼代價？
沒有。被拒絕的 GCRA 呼叫不會改變限制器，因此重試的用戶端不會受到進一步的懲罰。