Bucket4j في Java: الدليل الشامل لتحديد معدل الطلبات (Rate Limiting)

في تطوير البرمجيات الحديثة، خاصة عند بناء خدمات الويب وواجهات API عالية التحميل، من الضروري جداً التحكم في كثافة الطلبات الواردة. بدون هذا التحكم، يمكن لمستخدم ضار أو خطأ في النظام أن يتسبب في رفض الخدمة (DoS) لجميع المستخدمين الآخرين. هنا يأتي دور مفهوم تحديد معدل الطلبات (Rate Limiting)، وتعتبر مكتبة Bucket4j واحدة من أقوى وأكثر الأدوات مرونة لتطبيقه على منصة Java.

Bucket4j هي مكتبة Java آمنة للاستخدام في بيئات متعددة الخيوط (thread-safe)، مبنية على خوارزمية Token Bucket (سلة الرموز). تتيح للمطورين تحديد معدل تنفيذ العمليات بسهولة وفعالية: عدد طلبات HTTP لواجهة API، استدعاءات قاعدة البيانات، إرسال الرسائل، وغيرها. على عكس العدادات البسيطة، تعمل خوارزمية Token Bucket على توزيع الحمل بسلاسة، مما يسمح باندفاعات مؤقتة من الحركة مع الالتزام الصارم بمتوسط السرعة على المدى الطويل. هذا يجعلها الخيار الأمثل لمعظم السيناريوهات الواقعية.

لماذا تستخدم Bucket4j؟ أولاً، لحماية الواجهة الخلفية (Backend) من التحميل الزائد والمهاجمين. ثانياً، لإمكانية تطبيق خطط أسعار متعددة المستويات (مثل منح المستخدمين المميزين عدداً أكبر من الطلبات في الثانية). ثالثاً، توفر المكتبة واجهة برمجة تطبيقات (API) غنية للتخصيص الدقيق، بما في ذلك استراتيجيات مختلفة لتجديد الرموز، والعمل مع الأنظمة الموزعة عبر Redis أو Hazelcast، والتكامل مع الأطر الشائعة مثل Spring Boot. Bucket4j ليست مجرد "حل مؤقت"، بل هي أداة إنتاجية متكاملة.

التثبيت

يتم توزيع Bucket4j عبر مستودع Maven المركزي (Maven Central). لإضافة المكتبة إلى مشروعك، يجب إضافة التبعية (dependency) إلى ملف pom.xml (لمشاريع Maven) أو build.gradle (لمشاريع Gradle).

Maven (pom.xml):

<dependency>
    <groupId>com.github.vladimir-bukhtoyarov</groupId>
    <artifactId>bucket4j-core</artifactId>
    <version>8.7.0</version>
</dependency>

Gradle (build.gradle):

implementation 'com.github.vladimir-bukhtoyarov:bucket4j-core:8.7.0'

ملاحظة مهمة: الإصدار 8.x يتطلب Java 11 أو أحدث. إذا كنت تستخدم Java 8، فستحتاج إلى الإصدار 7.x. للعمل مع ذاكرات التخزين المؤقت الموزعة (Redis, Hazelcast)، يجب إضافة الوحدات النمطية المناسبة، مثل bucket4j-redis.

بداية سريعة: مثال عملي بسيط

لنقم بإنشاء محدد بسيط يسمح بتنفيذ 10 عمليات كحد أقصى في الثانية.

import io.github.bucket4j.Bandwidth;
import io.github.bucket4j.Bucket;
import io.github.bucket4j.Refill;

import java.time.Duration;

public class QuickStartExample {

    public static void main(String[] args) {
        // 1. الإعدادات: 10 رموز، يتم تجديد 10 رموز كل ثانية
        Bandwidth limit = Bandwidth.classic(10, Refill.greedy(10, Duration.ofSeconds(1)));

        // 2. إنشاء السلة
        Bucket bucket = Bucket.builder()
                .addLimit(limit)
                .build();

        // 3. محاكاة الطلبات
        for (int i = 1; i <= 15; i++) {
            boolean consumed = bucket.tryConsume(1);
            if (consumed) {
                System.out.println("الطلب " + i + ": ناجح (تم الحصول على رمز)");
            } else {
                System.out.println("الطلب " + i + ": مرفوض (تجاوز الحد المسموح)");
            }
        }
    }
}

يقوم هذا الكود بإنشاء سلة تحتوي على 10 رموز. كل ثانية، يتم إضافة 10 رموز جديدة إليها (إعادة تعبئة جشعة - greedy refill، حيث تتم إضافة الرموز بشكل مستمر وليس دفعة واحدة في نهاية الفاصل الزمني). سيتم تنفيذ أول 10 طلبات فوراً.