Bucket4j pour Java : Guide complet du Rate Limiting

Dans le développement logiciel moderne, en particulier lors de la création de services web et d'API à forte charge, il est crucial de contrôler l'intensité des requêtes entrantes. Sans ce contrôle, un utilisateur malveillant ou un bug système peut entraîner un déni de service (DoS) pour tous les autres clients. C'est là que le concept de Rate Limiting (limitation de débit) intervient, et la bibliothèque Bucket4j est l'un des outils les plus puissants et flexibles pour l'implémenter sur la plateforme Java.

Bucket4j est une bibliothèque Java thread-safe basée sur l'algorithme du Token Bucket (seau à jetons). Elle permet aux développeurs de limiter facilement et efficacement la fréquence d'exécution des opérations : nombre de requêtes HTTP vers une API, appels à une base de données, envoi de messages, etc. Contrairement aux compteurs simples, l'algorithme Token Bucket lisse la charge, autorisant des pics de trafic temporaires tout en respectant strictement la vitesse moyenne sur le long terme. Cela en fait le choix idéal pour la plupart des scénarios réels.

Pourquoi utiliser Bucket4j ? Premièrement, pour protéger votre backend contre les surcharges et les attaquants. Deuxièmement, pour mettre en œuvre des plans tarifaires à plusieurs niveaux (les utilisateurs premium obtiennent plus de requêtes par seconde). Troisièmement, la bibliothèque offre une API riche pour un réglage fin, incluant différentes stratégies de reconstitution des jetons, la prise en charge des systèmes distribués via Redis ou Hazelcast, et l'intégration avec des frameworks populaires comme Spring Boot. Bucket4j n'est pas une simple "solution de contournement", c'est un outil de production à part entière.

Installation

Bucket4j est distribué via le dépôt central Maven (Maven Central). Pour ajouter la bibliothèque à votre projet, vous devez ajouter la dépendance dans votre fichier pom.xml (pour Maven) ou build.gradle (pour 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'

Important : La version 8.x nécessite Java 11 ou supérieur. Si vous utilisez Java 8, vous aurez besoin de la version 7.x. Pour les caches distribués (Redis, Hazelcast), vous devez ajouter les modules correspondants, par exemple bucket4j-redis.

Démarrage rapide : Exemple minimal fonctionnel

Créons un limiteur simple qui autorise un maximum de 10 opérations par seconde.

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. Configuration : 10 jetons, reconstitution de 10 jetons chaque seconde
        Bandwidth limit = Bandwidth.classic(10, Refill.greedy(10, Duration.ofSeconds(1)));

        // 2. Création du seau
        Bucket bucket = Bucket.builder()
                .addLimit(limit)
                .build();

        // 3. Simulation de requêtes
        for (int i = 1; i <= 15; i++) {
            boolean consumed = bucket.tryConsume(1);
            if (consumed) {
                System.out.println("Requête " + i + " : Réussie (jeton obtenu)");
            } else {
                System.out.println("Requête " + i + " : REFUSÉE (limite dépassée)");
            }
        }
    }
}

Ce code crée un seau de 10 jetons. Chaque seconde, 10 nouveaux jetons y sont ajoutés (reconstitution greedy — les jetons sont ajoutés en continu, et non en bloc à la fin de l'intervalle). Les 10 premières requêtes seront exécutées instantanément.