حاسبة token bucket
دلو سعته 10 رموز وفيه 5 ويُملأ بمعدل 2 في الثانية يصبح فيه 8 متاحة بعد 1.5 ثانية، فتمر دفعة من 3 ويبقى 5. أدخل أرقامك لتعرف هل تُقبل الدفعة أم تُرفض وكم تنتظر. مجانية في متصفحك.
- مجاني
- يعمل في متصفحك
- دون تسجيل
- بياناتك لا تغادر جهازك
شغّل الأداة مجانًا
مثال محلول
- السعة
- 10
- معدل التعبئة
- 2
- الرموز
- 5
- الوقت المنقضي
- 1.5
- عدد الطلبات
- 3
- الرموز المتاحة
- 8
- الرموز المتبقية
- 5
- الرموز المستهلكة
- 3
- العجز
- 0
تحتفظون بدلو من الرموز حتى سعة ثابتة، وتملأونه بمعدل ثابت مع الزمن، وتنفقون الرموز عند وصول طلب أو دفعة. تقبل حاسبة حد المعدل بأسلوب token bucket السعة ومعدل الملء بالرموز في الثانية وعدد الرموز الحالي والثواني المنقضية منذ آخر تحديث وعدد الرموز التي تحتاجها الدفعة التالية. تملأ الدلو مع سقف صارم عند السعة، وتقرر السماح أو الرفض، وتُبلغ عن الرموز المتبقية بعد القرار، وعند الرفض تحسب مدة الانتظار حتى تكفي الرموز—أو تُبيّن أن الطلب لا يمكن إرضاؤه أبدًا لأنه يتجاوز السعة أو أن الملء صفر.
كيف يقرر الدلو
يحتفظ دلو الرموز برصيد من الرموز لا يتجاوز أبدًا سعة ثابتة. ويضيف الوقت رموزًا بمعدل ملء ثابت، وتستهلك كل دفعة عددًا من الرموز يساوي كلفتها. ولكي تقرر، تبدأ الحاسبة بالملء: تضيف إلى الرصيد الحالي الثواني المنقضية مضروبة في المعدل، ثم تجعل السعة حدًا أقصى للنتيجة. وهذا ما يمكن إنفاقه في تلك اللحظة. فإذا غطّى الكلفة قُبلت الدفعة وخُصمت كلفتها. وفي المثال، 5 رموز زائد 1.5 ثانية بمعدل 2 في الثانية تساوي 8، فتمر دفعة من 3 ويبقى 5. وأنت من يحدد الوقت المنقضي، لذا تعطي الأرقام نفسها الجواب نفسه دائمًا.
فيمَ يفيد والأخطاء الشائعة
يفيد في مطابقة حصة بوابة أو محدِّد في شيفرتك مع مرجع ثابت، وفي شرح تصميم أثناء المراجعة، وفي التحضير لمحاكاة الأحمال. وهو مفيد خصوصًا في الحالات الحدية التي تخطئ فيها المحددات المكتوبة يدويًا: دلو ممتلئ أصلًا، وملء جزئي، ودفعة أكبر من السقف. ومن الأخطاء الشائعة نسيان السقف، فيكبر الرصيد بلا حد بعد توقف طويل ويسمح بدفعات أكبر بكثير من المقصود. وخطأ آخر هو اعتبار الدفعة الأكبر من السعة مسألة صبر فقط، إذ لن يجعلها أي انتظار تتسع، والحاسبة تقول ذلك.
أين تُثبت حاسبة token bucket قيمتها العملية
يستخدم مؤلفو الحافة والبوابات الحاسبة كمرجع أثناء تنفيذ دلاء Redis أو في الذاكرة، مقارنين آلة الحالة المحلية بهذا الناتج ذي الصيغة المغلقة لمدخلات متطابقة. يبيّن المعلّمون ومقابلات SRE أن token bucket ليس كـ leaky bucket صرف: تُسمح الدفعات حتى capacity ثم يعيد الملء السلس الهامش. تستفيد مواقع المحتوى التي تستهدف حاسبة حد المعدل بأسلوب token bucket من ودجت حيّ يتطابق مساره المجاني في المتصفح مع مسار الأتمتة المدفوع على نفس الوحدة.
التحقق الفاشل لا يستهلك الرصيد.
الأسئلة الشائعة
كم رمزًا يتوفر بعد فترة توقف؟
أضف إلى الرموز الحالية عدد الثواني المنقضية مضروبًا في معدل الملء، ثم اجعل السعة حدًا أقصى للنتيجة. مع 5 رموز ومعدل 2 في الثانية و1.5 ثانية منقضية يصبح لديك 8، ما دامت السعة تسمح بذلك.
كم أنتظر عندما تُرفض دفعة؟
تقسم الحاسبة العجز، أي الرموز الناقصة، على معدل الملء. والناتج هو عدد الثواني اللازمة حتى يحتوي الدلو ما يكفي لتلك الدفعة.
متى لا يمكن قبول الدفعة أبدًا؟
عندما تكلّف رموزًا أكثر مما يمكن أن يحمله الدلو، أو عندما يكون معدل الملء صفرًا ولا يحتوي الدلو ما يكفي بالفعل. وفي الحالتين تقول الحاسبة ذلك بوضوح بدل إعطاء وقت انتظار.
ماذا تعني السعة ومعدل الملء عمليًا؟
السعة هي أكبر دفعة يسمح بها الدلو في مرة واحدة، أي سقفه. أما معدل الملء، بالرموز في الثانية، فهو الإيقاع الثابت الذي يمكن الحفاظ عليه مع الوقت بعد استهلاك تلك الدفعة.
أدوات ذات صلة
للمطوّرين — الوصول عبر API
كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.
الـEndpoint
صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.
استدعِ الخدمة من بيئتك
curl -X POST https://api.kit.forhosting.com/dev/token-bucket \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"capacity":10,"refill_rate":2,"tokens":5,"elapsed":1.5,"request_count":3}'const res = await fetch("https://api.kit.forhosting.com/dev/token-bucket", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"capacity": 10,
"refill_rate": 2,
"tokens": 5,
"elapsed": 1.5,
"request_count": 3
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/dev/token-bucket",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"capacity": 10,
"refill_rate": 2,
"tokens": 5,
"elapsed": 1.5,
"request_count": 3
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/token-bucket", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"capacity":10,"refill_rate":2,"tokens":5,"elapsed":1.5,"request_count":3}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"capacity":10,"refill_rate":2,"tokens":5,"elapsed":1.5,"request_count":3}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/token-bucket", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)مثال على الطلب
{
"capacity": 10,
"refill_rate": 2,
"tokens": 5,
"elapsed": 1.5,
"request_count": 3
}مثال على الاستجابة
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "dev.token_bucket",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.
الأسعار
السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.
الأخطاء
| HTTP | الرمز | المعنى |
|---|---|---|
401 | unauthorized | مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك. |
402 | insufficient_balance | رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة. |
404 | unknown_type | نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب. |
429 | rate_limited | تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة. |
ملاحظات تقنية
محدد معدل token bucket هو النموذج المعياري خلف تقييد واجهات API وحصص البوابات والضغط العكسي لدى العميل. يشغّل نفس الوحدة النقية الحتمية الأداة المجانية في المتصفح ومسار API، فلا تختلف مراجعات التصميم وسكربتات اختبار الحمل ومحاكيات الإنتاج حول الحالات الحدّية مثل دلو ممتلئ أو ملء جزئي أو طلب أكبر من سقف الدفعة.
كيف يقرر خوارزمية token bucket السماح أو الرفض
يخزّن token bucket رصيدًا غير سالب من الرموز لا يتجاوز السعة أبدًا. يزوّد المستدعي بالزمن المنقضي لتبقى الرياضيات حتمية—دون قراءة ساعة حائط—فتُنتج نفس المدخلات دائمًا نفس قرار السماح والرصيد المتبقي وثواني الانتظار عبر بيئات التشغيل والاختبارات الذهبية. بين الفحوصات تتراكم الرموز بمعدل refill_rate رمزًا في الثانية طوال المدة elapsed، ثم يُحدَّ الرصيد بـ min(capacity, tokens + elapsed مضروبًا في refill_rate). تلك القيمة المحدودة هي tokens_available: ما يمكن إنفاقه الآن. تُسمح دفعة تكلف request_count من الرموز عندما يكون tokens_available على الأقل request_count؛ عند السماح يصبح tokens_remaining يساوي tokens_available ناقص request_count وtokens_consumed يساوي request_count. عند الرفض لا يُنفق أي رمز: يبقى tokens_remaining عند tokens_available، وtokens_consumed صفر، وdeficit يساوي request_count ناقص tokens_available. زمن الانتظار هو deficit مقسومًا على refill_rate عندما يكون الملء موجبًا والطلب لا يتجاوز السعة؛ وإلا فلا يمكن إرضاء الطلب لاحقًا أيضًا (can_satisfy يكون false)، وهذا يغطي تكلفة فوق سقف الدفعة ودلوًا متجمدًا بملء صفري. السعة هي هامش الدفعة: دلو ممتلئ بعشرة مع ملء بطيء ما زال يمرّر ذروة من عشرة رموز، ولذلك تختار البوابات capacity للقمم وrefill_rate لمتوسط الحركة المستدامة.
عقد الإدخال وحقول الاستجابة وأخطاء التحقق
يجب أن تكون capacity أكبر من صفر وهي أقصى رموز يمكن أن يحملها الدلو بعد الملء. أرسلوا جسم JSON بخمسة أعداد منتهية إلزامية. يجب أن تكون refill_rate أكبر من أو تساوي صفرًا وتُقاس بالرموز في الثانية؛ الصفر يعني أن الدلو لا يتعافى بعد فراغه. tokens هو الرصيد قبل تطبيق فترة elapsed هذه ويجب أن يكون غير سالب؛ تُقبل قيم فوق capacity وتُحدّ عند حساب tokens_available بعد الملء. elapsed هي الثواني منذ آخر تحديث ويجب أن تكون غير سالبة. request_count هو عدد الرموز التي تحتاجها هذه الدفعة ويجب أن يكون أكبر من صفر. الحقول الناقصة والسلاسل غير العددية وNaN وInfinity والإشارات خارج النطاق تفشل بـ invalid_input مع تسمية الحقل ولا تُحاسب. عند النجاح يعيد الجسم المدخلات الخمس ثم tokens_available بعد الملء وallowed كقيمة منطقية وtokens_remaining بعد قرار الإنفاق وtokens_consumed وdeficit وwait_seconds (صفر عند السماح أو عندما لا يمكن للطلب أن يمر أبدًا) وcan_satisfy وسلسلة formula قصيرة تعيد صياغة قاعدة التحديث. مثال: capacity عشرة، refill_rate اثنان في الثانية، tokens خمسة، elapsed ثانية ونصف، request_count ثلاثة ينتج tokens_available ثمانية (خمسة زائد ثلاثة من الملء دون تجاوز السعة)، allowed true، tokens_remaining خمسة، وwait_seconds صفر. استدعاء ثانٍ يطلب تسعة رموز مع ثمانية متاحة يُرفض بـ deficit واحد وwait_seconds نصف ثانية عند معدّلين في الثانية.
أين تُثبت حاسبة token bucket قيمتها العملية
تُحدّد فرق منتجات API السعة والملء قبل نشر حصة: يجرّبون أرقامًا مرشحة وأحجام دفعات نموذجية ليروا إن كانت الذروات المشروعة تمر بينما تنتظر الفيضانات المسيئة. تستدعي منصات اختبار الحمل وسكربتات الفوضى نفس نقطة النهاية النقية لتأكيد أن عميلاً اصطناعيًا يتبع wait_seconds لا يتجاوز الحد الموثّق. ولأن التنفيذ parse خالص من المستوى A، تكلف كل مكالمة ناجحة السعر الأساسي المنشور $0.002 بلا رموز نموذج وبلا شبكة صادرة. حافظوا على الطلبات صغيرة وثبّتوا الحقول العددية المقربة في الاختبارات لتحصلوا على إجابات سماح وانتظار قابلة للتكرار لوثائق التصميم وأمثلة SDK وتجارب الإنتاج دون إقامة خدمة حد معدل كاملة.
حالات التكامل
تحجيم حصة API والدفعة
اضبطوا capacity وrefill_rate أمام دفعات request_count واقعية حتى تسمح حدود المنتج بذروات مشروعة وتظل تقيّد الحركة المستدامة.
مراجع اختبار الحمل وتراجع العميل
شغّلوا عملاء اصطناعيين بـ wait_seconds المُرجع وتحققوا من أنهم لا يتجاوزون عقد token-bucket الموثّق في سيناريوهات متزامنة.
فحوصات متقاطعة لتنفيذ البوابة
قارنوا آلات حالة الدلو في Redis أو داخل العملية بهذه الحاسبة الحتمية لنفس مدخلات capacity والملء وtokens وelapsed والتكلفة.
أسئلة تقنية
كيف تعمل حاسبة حد المعدل بأسلوب token bucket؟
تحسب tokens_available = min(capacity, tokens + elapsed × refill_rate)، وتسمح بالدفعة عندما تكون تلك القيمة على الأقل request_count، وتطرح عند السماح، وإلا تُرجع deficit وwait_seconds = deficit / refill_rate عندما يستطيع الملء تغطية التكلفة لاحقًا.
ما الوحدات المناسبة لـ refill_rate وelapsed؟
استخدموا نفس وحدة الزمن للاثنين: refill_rate بالرموز في الثانية وelapsed بالثواني. تحويل الاثنين إلى ميلي ثانية ينجح فقط مع الاتساق؛ وواجهة API لا تحوّل الوحدات نيابةً عنكم.
ماذا لو كان request_count أكبر من capacity؟
تُرفض الدفعة مع can_satisfy false وwait_seconds صفر. طلب واحد يحتاج أكثر مما يمكن للدلو أن يحمل لن يمر أبدًا حتى مع ملء كامل.
هل يمكن أن يكون tokens أكبر من capacity في الإدخال؟
نعم. تقبل الحاسبة قيمة tokens غير سالبة فوق capacity ولا تحدّها إلا بعد تطبيق ملء elapsed، بما يوافق تنفيذات شائعة تخزّن عدّادًا غير محدود حتى التحديث التالي.
كم تكلفة حاسبة token bucket؟
أداة المتصفح مجانية. طلبات API تستخدم رصيد KIT المدفوع مسبقًا بسعر $0.002 لكل مكالمة ناجحة؛ الإدخال غير الصالح لا يُحاسب.