Token-Bucket-Rechner

Ein Token-Bucket-Ratenbegrenzer ist das Standardmodell hinter API-Throttling, Gateway-Kontingenten und clientseitigem Backpressure. Dasselbe reine, deterministische Modul speist das kostenlose Browser-Werkzeug und den API-Pfad, sodass Entwurfsreviews, Lasttestskripte und Produktionssimulatoren bei Grenzfällen wie vollem Eimer, teilweiser Auffüllung oder Anfragen über der Burst-Obergrenze nie auseinanderlaufen.

Wie der Token-Bucket-Algorithmus Erlauben oder Ablehnen entscheidet

Der Token Bucket speichert einen nichtnegativen Token-Saldo, der die Kapazität nie überschreitet. Die verstrichene Zeit liefert der Aufrufer, damit die Mathematik deterministisch bleibt—es wird keine Wanduhr gelesen—, sodass dieselben Eingaben über Runtimes und Goldens hinweg stets dieselbe Entscheidung, denselben Restsaldo und dieselben Warte-Sekunden ergeben. Zwischen Prüfungen sammeln sich Tokens mit refill_rate Tokens pro Sekunde über die Dauer elapsed, danach wird der Saldo mit min(capacity, tokens + elapsed mal refill_rate) begrenzt. Dieser begrenzte Wert ist tokens_available—was Sie jetzt ausgeben können. Ein Burst, der request_count Tokens kostet, wird erlaubt, wenn tokens_available mindestens request_count beträgt; bei Erlauben wird tokens_remaining zu tokens_available minus request_count und tokens_consumed entspricht request_count. Bei Ablehnen werden keine Tokens verbraucht: tokens_remaining bleibt bei tokens_available, tokens_consumed ist null und deficit ist request_count minus tokens_available. Die Wartezeit ist deficit geteilt durch refill_rate, wenn die Auffüllung positiv ist und die Anfrage die Kapazität nicht übersteigt; sonst ist die Anfrage auch später nicht erfüllbar (can_satisfy ist false)—das deckt sowohl Kosten über der Burst-Obergrenze als auch einen eingefrorenen Eimer mit Auffüllrate null ab. Die Kapazität ist der Burst-Spielraum: ein voller Eimer mit zehn und langsamer Auffüllung lässt trotzdem einen einzelnen Zehn-Token-Spike durch, weshalb Gateways capacity für Spitzen und refill_rate für den anhaltenden Durchschnitt wählen.

Eingabevertrag, Antwortfelder und Validierungsfehler

Senden Sie einen JSON-Body mit fünf erforderlichen endlichen Zahlen. capacity muss größer als null sein und ist die maximale Token-Menge, die der Eimer nach dem Auffüllen halten kann. refill_rate muss größer oder gleich null sein und wird in Tokens pro Sekunde gemessen; null bedeutet, dass der Eimer sich nach dem Leeren nie erholt. tokens ist der Saldo vor Anwendung dieses elapsed-Intervalls und muss nichtnegativ sein; Werte über capacity werden akzeptiert und beim Berechnen von tokens_available nach dem Auffüllen gekappt. elapsed sind Sekunden seit der letzten Aktualisierung und muss nichtnegativ sein. request_count ist der Token-Bedarf dieses Bursts und muss größer als null sein. Fehlende Felder, nichtnumerische Zeichenketten, NaN, Infinity und unzulässige Vorzeichen scheitern mit invalid_input unter Angabe des Feldes und werden nicht berechnet. Bei Erfolg spiegelt der Body die fünf Eingaben wider und liefert tokens_available nach dem Auffüllen, allowed als Booleschen Wert, tokens_remaining nach der Ausgabenentscheidung, tokens_consumed, deficit, wait_seconds (null wenn erlaubt oder wenn die Anfrage nie durchkommt), can_satisfy und eine kurze formula-Zeichenkette mit der Aktualisierungsregel. Beispiel: capacity zehn, refill_rate zwei pro Sekunde, tokens fünf, elapsed eineinhalb, request_count drei ergibt tokens_available acht (fünf plus drei aus Auffüllung, noch unter Kapazität), allowed true, tokens_remaining fünf und wait_seconds null. Ein zweiter Aufruf mit neun Tokens bei denselben acht verfügbaren wird mit deficit eins und wait_seconds von einer halben Sekunde bei zwei Tokens pro Sekunde abgelehnt.

Wo ein Token-Bucket-Rechner echten Nutzen stiftet

Edge- und Gateway-Autoren nutzen den Rechner als Orakel beim Implementieren von Redis- oder In-Memory-Buckets und vergleichen ihre lokale Zustandsmaschine mit diesem geschlossenen Ergebnis für identische Eingaben. Lehrende und SRE-Interviews zeigen damit, dass Token Bucket nicht dasselbe ist wie ein reiner Leaky Bucket: Bursts sind bis zur Kapazität erlaubt, danach stellt die gleichmäßige Auffüllung Spielraum wieder her. Fehlgeschlagene Validierung wird nicht berechnet. API-Produktteams dimensionieren capacity und Auffüllung, bevor sie ein Kontingent freigeben: Sie setzen Kandidatenzahlen und Beispiel-Burstgrößen ein, um zu sehen, ob legitime Spitzen durchkommen, während missbräuchliche Fluten warten. Lasttest-Harnesses und Chaos-Skripte rufen denselben reinen Endpunkt auf, um zu prüfen, dass ein synthetischer Client, der wait_seconds folgt, nie über das dokumentierte Limit hinaus ausgibt. Weil die Implementierung reines Parse-Tier-A ist, kostet jeder erfolgreiche Aufruf den veröffentlichten Basispreis $0.002 ohne Modell-Tokens und ohne ausgehendes Netzwerk. Halten Sie Anfragen klein, pinnen Sie gerundete Zahlenfelder in Tests und erhalten Sie reproduzierbare Erlaubnis- und Warteantworten für Design-Dokumente, SDK-Beispiele und Produktions-Trockenläufe, ohne einen vollständigen Ratenlimit-Dienst aufzusetzen.