Bucket4j项目中的统一风格构建器改造

背景介绍

Bucket4j是一个Java库，提供了基于令牌桶算法的速率限制实现。在项目演进过程中，开发团队决定对ProxyManagers（代理管理器）的构建方式进行统一改造，引入更现代的构建器模式（Builder Pattern）来替代传统的构造函数初始化方式。

改造目标

本次改造的核心目标是统一所有ProxyManagers的构建风格，同时保持向后兼容性。具体来说：

1. 保留原有的构造函数初始化方式，但将其标记为过时（deprecated）
2. 引入流畅的构建器（Fluent Builder）模式
3. 使用递归泛型（Recursive Generics）处理构建器继承层次
4. 特殊场景（如JDBC集成中的自定义主键映射器）通过特定代理管理器构建器处理

技术实现细节

递归泛型的应用

递归泛型是Java中处理构建器继承层次的一种优雅方式。它允许子类方法返回子类类型，而不是父类类型，从而保持流畅接口的连贯性。在Bucket4j的改造中，这种技术被广泛应用于构建器层次结构。

public abstract class AbstractProxyManagerBuilder<B extends AbstractProxyManagerBuilder<B>> {
    protected B self() {
        return (B) this;
    }
    
    public B withSomeSetting(String value) {
        // 设置逻辑
        return self();
    }
}

构建器模式的实现

新的构建器模式提供了更灵活的配置方式。例如，配置一个代理管理器现在可以这样写：

ProxyManager<String> manager = new SomeProxyManagerBuilder()
    .withExpirationAfterWrite(Duration.ofMinutes(10))
    .withMaximumSize(1000)
    .build();

向后兼容处理

为了不影响现有代码，项目采取了以下策略：

1. 原有构造函数仍然保留，但添加@Deprecated注解
2. 在文档中推荐使用新的构建器方式
3. 确保新旧两种方式在功能上完全等价

改造带来的优势

1. 更清晰的API：构建器模式使配置过程更加直观和可读
2. 更好的扩展性：新增配置项不需要修改构造函数签名
3. 更安全的配置：可以在构建时验证配置的有效性
4. 更灵活的默认值：可以集中管理默认配置

实际应用示例

假设我们需要配置一个基于JDBC的ProxyManager，新的构建器方式如下：

JdbcProxyManagerBuilder builder = new JdbcProxyManagerBuilder()
    .withDataSource(dataSource)
    .withTableName("rate_limits")
    .withPrimaryKeyMapper(customKeyMapper)
    .withExpirationStrategy(ExpirationStrategy.AFTER_WRITE);
    
ProxyManager<String> manager = builder.build();

总结

Bucket4j通过引入统一风格的构建器，显著改善了ProxyManagers的配置体验。这种改造不仅提升了API的现代性和易用性，还通过递归泛型等技术保证了代码的健壮性和扩展性，同时谨慎处理了向后兼容问题，确保现有用户能够平稳过渡。