Bucket4j para Java: Guia Completo de Rate Limiting

No desenvolvimento de software moderno, especialmente ao criar serviços web e APIs de alta carga, é fundamental controlar a intensidade das requisições recebidas. Sem esse controle, um único usuário mal-intencionado ou um bug no sistema pode causar uma negação de serviço (DoS) para todos os outros clientes. É aqui que entra o conceito de Rate Limiting (limitação de taxa), e a biblioteca Bucket4j é uma das ferramentas mais poderosas e flexíveis para implementá-lo na plataforma Java.

Bucket4j é uma biblioteca thread-safe para Java, baseada no algoritmo Token Bucket (balde de fichas). Ela permite que desenvolvedores limitem de forma fácil e eficiente a frequência de operações: número de requisições HTTP a uma API, chamadas ao banco de dados, envio de mensagens, etc. Diferente de contadores simples, o algoritmo Token Bucket suaviza a carga, permitindo picos temporários de tráfego, mas respeitando rigorosamente a taxa média a longo prazo. Isso o torna a escolha ideal para a maioria dos cenários reais.

Por que usar Bucket4j? Primeiro, para proteger seu backend contra sobrecargas e ataques. Segundo, para implementar planos de preços em múltiplos níveis (usuários premium recebem mais requisições por segundo). Terceiro, a biblioteca oferece uma API rica para ajustes finos, incluindo diferentes estratégias de reabastecimento de tokens, suporte a sistemas distribuídos via Redis ou Hazelcast, e integração com frameworks populares como Spring Boot. Bucket4j não é um "paliativo", mas sim uma ferramenta de produção completa.

Instalação

O Bucket4j é distribuído através do repositório central Maven (Maven Central). Para adicionar a biblioteca ao seu projeto, você precisa incluir a dependência no arquivo pom.xml (para Maven) ou build.gradle (para 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'

Importante: A versão 8.x requer Java 11 ou superior. Se você estiver usando Java 8, precisará da versão 7.x. Para trabalhar com caches distribuídos (Redis, Hazelcast), é necessário adicionar os módulos correspondentes, como bucket4j-redis.

Início Rápido: Exemplo Mínimo Funcional

Vamos criar um limitador simples que permite no máximo 10 operações por segundo.

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. Configuração: 10 tokens, reabastecimento de 10 tokens a cada segundo
        Bandwidth limit = Bandwidth.classic(10, Refill.greedy(10, Duration.ofSeconds(1)));

        // 2. Criação do balde
        Bucket bucket = Bucket.builder()
                .addLimit(limit)
                .build();

        // 3. Simulação de requisições
        for (int i = 1; i <= 15; i++) {
            boolean consumed = bucket.tryConsume(1);
            if (consumed) {
                System.out.println("Requisição " + i + ": Sucesso (token obtido)");
            } else {
                System.out.println("Requisição " + i + ": NEGADO (limite excedido)");
            }
        }
    }
}

Este código cria um balde com 10 tokens. A cada segundo, 10 novos tokens são adicionados (reabastecimento greedy — os tokens são adicionados continuamente, não em lote no final do intervalo). As primeiras 10 requisições serão executadas imediatamente.