Bucket4j for Java：Rate Limiting 完整指南

在现代软件开发中，尤其是构建高负载 Web 服务和 API 时，控制请求流量至关重要。如果没有流量控制，一个恶意用户或系统漏洞就可能导致服务拒绝（DoS），影响所有其他用户。这时，Rate Limiting（限流）概念就派上了用场，而 Bucket4j 库是在 Java 平台上实现这一功能最强大、最灵活的工具之一。

Bucket4j 是一个基于 Token Bucket（令牌桶）算法的线程安全 Java 库。它让开发者能够轻松高效地限制操作频率：例如 API 的 HTTP 请求次数、数据库调用次数、消息发送次数等。与简单的计数器不同，Token Bucket 算法可以平滑负载，允许短时流量突发，同时严格遵守长期平均速率。这使其成为大多数实际场景的理想选择。

为什么要使用 Bucket4j？首先，它可以保护您的后端免受过载和恶意攻击。其次，它支持实现多级定价方案（例如，高级用户每秒获得更多请求）。第三，该库提供了丰富的 API 用于精细调优，包括多种令牌补充策略、通过 Redis 或 Hazelcast 实现分布式系统支持，以及与 Spring Boot 等流行框架的集成。Bucket4j 不仅仅是一个“占位符”，而是一个成熟的生产级工具。

安装

Bucket4j 通过 Maven 中央仓库分发。要将该库添加到您的项目中，需要在 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 补充模式——令牌连续添加，而不是在间隔结束时批量添加）。前 10 个请求将立即执行