حد معدل الطلبات في الـ API: الدليل الكامل للحدود والدفعات والتمهل

تعمل الـ API بلا حد للمعدل عملاً رائعاً حتى اللحظة التي يكتب فيها أحد العملاء حلقة بلا أي توقف. حينئذ يستهلك متصل واحد الطاقة التي يتشاركها الجميع، ويرتفع زمن الاستجابة لكل مستخدم آخر، ويبدو الفشل كانقطاع للخدمة لا كبرنامج نصي واحد سيئ التصرف. وحد المعدل هو الآلية التي تحوِّل هذا المشهد إلى خطأ صغير محصور موسوم بوضوح، ولعميل واحد فقط.

ضبط الحدود على نحو صحيح مسألة وضوح في الأساس: أن تقرر ماذا تعد، وعلى أي فترة، ولمن، وماذا تقول لعميل تجاوز الحد. يغطي هذا الدليل الخوارزميات، واختيار أرقام يمكن الدفاع عنها، والترويسات التي تُبقي عميلاً مكتوباً جيداً داخل حدودك، وكيف تتمهل حين تكون أنت العميل.

لماذا يهم حد المعدل

يُدخَل حد المعدل عادة بعد عُطل، لكنه يحل أربع مشكلات مستقلة في الوقت نفسه:

• حماية الطاقة. لخدمتك حد أقصى من المعالجة يمكن إدامته. والحد يُبقي الطلب تحته بالتصميم لا بالحظ.
• الإنصاف. بغير حد لكل عميل، ينال أكثر المتصلين ضجيجاً أكبر قدر من الموارد. وبالحد ينال كل عميل نصيباً متوقعاً.
• ضبط التكلفة. إذا كان كل طلب يستدعي استعلاماً لقاعدة البيانات أو نداءً لطرف ثالث أو تشغيل نموذج، فإن API بلا حد تعني فاتورة بلا حد.
• مقاومة الإساءة. حشو بيانات الاعتماد والكشط والتعداد جميعها تعتمد على الحجم. والحد يجعلها أبطأ من أن تكون عملية وأظهر من أن تمر دون تنبيه.

وهناك فائدة خامسة أهدأ: الحد الموثَّق عقد. فيمكن بناء العملاء على احترامه، وهذا أفضل بكثير من أن تكتشف سقفك عند الاصطدام به.

الخوارزميات التي يجدر معرفتها

كل مُحدِّد معدل يجيب على السؤال نفسه: هل هذا الطلب مسموح الآن؟ لكنها تختلف في معاملة الدفعات، وهذا الاختلاف هو ما تحسّه فعلاً كعميل.

دلو الرموز

تخيّل دلواً يحمل عدداً ثابتاً من الرموز ويُعاد تعبئته بمعدل ثابت. كل طلب يأخذ رمزاً واحداً. وإذا كان الدلو فارغاً رُفض الطلب. ويصفه رقمان وصفاً كاملاً: معدل التعبئة، وهو معالجتك المستمرة، وحجم الدلو، وهو أكبر دفعة تتحملها.

دلو من 100 رمز يُعاد تعبئته بعشرة في الثانية يسمح لعميل خامل بإطلاق 100 طلب فوراً، ثم يستقر به على عشرة في الثانية. وهذا ما تريده عادة: فالعملاء الحقيقيون يأتون على دفعات، لذا فالارتفاع القصير حركة طبيعية لا إساءة، في حين يبقى المتوسط على المدى الطويل محدوداً. ودلو الرموز هو الافتراضي لأسباب وجيهة: تنفيذه رخيص، ولا يحتاج إلا عدّ رموز وطابعاً زمنياً لكل عميل، وسلوكه سهل الشرح في الوثائق.

الدلو المثقوب

الدلو المثقوب هو الصورة المعاكسة. تدخل الطلبات في طابور وتخرج بمعدل ثابت، كالماء من ثقب. وإذا امتلأ الطابور رُفضت الطلبات الجديدة. المخرَج منتظم تماماً، وهذا بالضبط ما تحتاجه أمام خلفية لا تحتمل أي ارتفاع، كنظام قديم أو API لطرف ثالث تعيد بيعها.

والمقابل هو زمن الاستجابة. فالطلب الذي يصل إلى طابور يكاد يمتلئ ينتظر بدلاً من أن يفشل سريعاً، ولا يستطيع العميل التمييز بين خادم بطيء وطلب في الطابور. استخدمه لتشكيل الحركة الداخلة إلى شيء هش، وفضّل دلو الرموز حين تحمي خدمتك المرنة.

النوافذ الثابتة والمنزلقة

تعد النافذة الثابتة الطلبات لكل فترة تقويمية: 1000 في الساعة، تُصفَّر عند رأس الساعة. تنفيذها بسيط جداً بعدّاد ومفتاح، ولها عيب معروف: دفعة الحدود. فالعميل الذي يرسل 1000 طلب عند 10:59:59 وألفاً آخر عند 11:00:01 بقي داخل السياسة وسلّم 2000 طلب في ثانيتين، أي ضعف الذروة التي قصدتها.

وتُصلح النافذة المنزلقة ذلك بالعد على الفترة السابقة لا على الكتلة التقويمية الحالية. فعند 11:00:01 لا تزال ترى طلبات 10:59:59 وترفض الزائد. النسخة الدقيقة تحفظ طابعاً زمنياً لكل طلب، وهذا يكلف ذاكرة؛ وهناك حل وسط شائع يرجّح عدّ النافذة السابقة بمقدار ما لا يزال متراكباً منها، وهو دقيق بما يكفي لأي API تقريباً بجزء بسيط من الحالة.

كيف تختار حدودك

اختر الأرقام من القياسات لا من رقم مستدير يبدو كريماً. وهذا تسلسل ناجع:

1. قِس سقفك. اختبر الحمل حتى يتدهور زمن الاستجابة. تلك المعالجة، ناقص هامش، هي طاقتك الحقيقية.
2. اقسم على العملاء المتزامنين المتوقعين. هذه نقطة بداية لحد لكل عميل، وليست الجواب النهائي.
3. انظر في حركتك الحالية. اعرف المئين 95 والمئين 99 لمعدل الطلبات لكل عميل. والحد الواقع تحت المئين 99 سيستدعيك بسبب مستخدمين شرعيين.
4. أضف هامشاً للدفعات. نحو 10 إلى 20 مِثل معدل الثانية حجمٌ شائع للدلو؛ يستوعب تحميلات الصفحات العادية دون أن يسمح بإساءة مستمرة.
5. اجعلها على مستويات. لا ينبغي للعملاء المجهولين والموثَّقين والمدفوعين أن يتشاركوا حداً واحداً. وتسعير سقف أعلى هو أيضاً أنظف طريقة لتسعير الـ API.
6. راقب قبل أن تُطبِّق. سجّل أسبوعاً ما كان سيُرفض قبل أن تبدأ برفضه فعلاً.

ما تعتمده مفتاحاً يهم بقدر ما يهم الرقم. فالاعتماد على الـ IP هو الخيار الوحيد للحركة المجهولة لكنه يعاقب الشبكات المشتركة وNAT؛ والاعتماد على مفتاح الـ API عادل وهو الافتراضي الصحيح للنداءات الموثَّقة؛ والاعتماد على الحساب يمنع عميلاً من شراء طاقة إضافية بإنشاء مفاتيح. وكثير من الـ API تطبّق الثلاثة معاً: حد عام، وحد لكل مفتاح، وحد لكل نقطة وصول على المسارات المكلفة.

وبعد أن يكون الرقم بين يديك، يسهل أن يختل الحساب الذي يحوّله إلى فاصل بين الطلبات اختلالاً بسيطاً. وتحوّل حاسبة حد المعدل الحد والنافذة إلى أدنى تأخير بين الطلبات، والمعدل المستمر الآمن، وقيمة Retry-After قابلة للنشر.

الترويسات التي يحتاجها العملاء

الحد الذي لا يراه العميل هو حد سيصطدم به العميل. أرسل حالتك في كل استجابة لا في الرفض وحده:

• RateLimit-Limit — سقف النافذة الحالية.
• RateLimit-Remaining — عدد الطلبات المتبقية فيها.
• RateLimit-Reset — متى يتجدد المخصص، بالثواني من الآن.
• Retry-After — عند الرمز 429 أو 503، مدة الانتظار. عدد ثوان أو تاريخ HTTP.

وما زالت صيغة X-RateLimit-* واسعة الانتشار وتعمل جيداً؛ والأسماء بلا بادئة أعلاه هي الصيغة المعيارية، وإرسال الاثنتين أثناء الانتقال لا يكلف شيئاً. والمهم أن تكون القيم موجودة ودقيقة، لأنها تتيح لعميل جيد أن ينظّم وتيرته فلا يرى الرمز 429 أبداً.

وعندما ترفض، أعِد 429 Too Many Requests، ولا تعِد 403 ولا 500 عاماً. فالرمز 429 هو الوحيد الذي يخبر العميل بأن الطلب كان سليماً وسينجح لاحقاً، وهو الإشارة الوحيدة التي تنتج إعادة محاولة صحيحة. ويغطي مرجع رموز حالة HTTP الرموز ذات الصلة وما يوجبه كل منها على العميل.

كيف تتعامل مع 429 كعميل

من الجهة الأخرى للاتصال، القواعد قصيرة وغالباً ما تُنفَّذ تنفيذاً ناقصاً:

1. احترم Retry-After. إذا أخبرك الخادم بمدة الانتظار فانتظرها. ولا شيء آخر تفعله يكون أحسن علماً منها.
2. وإلا فتمهّل تمهلاً تضاعفياً. انتظر ثانية، ثم ثانيتين، ثم أربعاً، ثم ثماني، حتى سقف. فإعادة المحاولة فوراً تحوّل حملاً زائداً إلى تدافع من صنع يديك.
3. أضف تبايناً عشوائياً. غيِّر كل مدة انتظار عشوائياً بمئات قليلة من المللي ثانية. فبغير ذلك يعيد كل العملاء الذين فشلوا معاً المحاولة معاً، فتُعيد خطة التمهل إنتاج الذروة التي كان عليها أن توزعها.
4. حدِّد عدد المحاولات. ثلاث إلى خمس محاولات ثم أعلِن الفشل. فالمحاولات اللانهائية تخفي عُطلاً حقيقياً.
5. نظّم وتيرتك من الترويسات. اقرأ RateLimit-Remaining وتمهّل قبل أن تُرفض. وهذا هو الفرق بين عميل يعمل وعميل يعمل في معظم الأوقات.
6. لا تعِد أبداً طلباً من فئة 4xx غير 429. فالرمز 400 أو 422 سيفشل على النحو نفسه كل مرة، لأن المشكلة في الطلب ذاته.

أخطاء شائعة يجب تجنبها

• إعادة 403 بدل 429. يقرأ العملاء 403 كأنه دائم فيتوقفون، أو يعيدون المحاولة بلا تفكير؛ وكلا السلوكين غير مرغوب.
• إغفال Retry-After. طلبتَ من العميل أن يخمّن، والتخمين المعتاد هو «فوراً».
• الاعتماد على الـ IP وحده. يصبح مكتب كامل خلف عنوان NAT واحد عميلاً واحداً، ويصبح كاشط موزَّع ألف عميل.
• عدّ كل نقاط الوصول بالتساوي. لا ينبغي أن تكلف قراءة من الذاكرة المؤقتة وتقرير يستغرق ثماني ثوان رمزاً واحداً لكل منهما؛ رجّح المسارات المكلفة أو أعطها حداً خاصاً.
• نافذة ثابتة مع حد ضيق. دفعة الحدود تعني أن ذروتك الحقيقية ضعف الرقم المنشور.
• عدم وجود هامش للدفعات. الحد المنتظم تماماً يرفض حركة طبيعية، لأن العملاء الحقيقيين يأتون على شكل تجمعات.
• حدود غير موثَّقة. إن لم يكن الرقم في وثائقك وفي ترويساتك، فسيكتشفه كل مطور دمج في بيئة الإنتاج.
• إعادة المحاولة بلا تباين عشوائي. المحاولات المتزامنة هي الطريق لتحويل ارتفاع قصير إلى ارتفاع مستمر.

احسب حدودك

حد المعدل الجيد ممل: ينظّم العملاء وتيرتهم من ترويساتك، وتُستوعب الدفعات، وتُكبَح الإساءة، ولا يلاحظ أحد شيئاً. والوصول إلى ذلك حسابٌ في معظمه وصدقٌ بشأن طاقتك الحقيقية. ابدأ من حد ونافذة تستطيع إدامتهما فعلاً، وحوّلهما إلى الفاصل وقيمة Retry-After التي يحتاجها عملاؤك، وانشر كليهما، وسجّل الحالات التي كادت تتجاوز الحد لتفرّق بين حد ضيق أكثر من اللازم وعميل سيئ التصرف.

أدوات وأدلة ذات صلة:

• حاسبة حد المعدل — تحويل الحد والنافذة إلى فواصل وأحجام دفعات وقيمة Retry-After.
• رموز حالة HTTP — ما يوجبه 429 و503 وغيرهما على العميل.
• رموز حالة HTTP: الدليل الكامل — شرح كل فئات الاستجابة.
• استعلام DNS — تأكد من المضيف الذي تصله حركة الـ API فعلاً.

الأسئلة الشائعة