Bucket4j API限流未生效：配置加载与规则失效问题排查

一、确认application-local.yml是否加载 #

• 激活Local Profile：Spring Boot不会自动加载local环境配置，必须显式指定激活。可以通过以下方式：
  • 启动参数添加：--spring.profiles.active=local
  • 在主配置文件application.yml中设置：

    spring:
      profiles:
        active: local
    

• 验证配置加载状态：在任意Spring组件中注入配置项并打印，确认是否读取到local配置：

  @Value("${bucket4j.enabled}")
  private boolean bucket4jEnabled;
  
  @PostConstruct
  public void checkConfig() {
      System.out.println("Bucket4j enabled: " + bucket4jEnabled);
  }
  

• 检查文件位置：确保application-local.yml放在src/main/resources（生产环境）或src/test/resources（测试环境）目录下，Spring Boot仅默认加载该路径下的配置文件。

二、排查Bucket4j配置有效性 #

• 版本兼容性：你使用的bucket4j-spring-boot-starter:0.7.0适配Spring Boot 2.x版本，若当前项目使用Spring Boot 3.x，会因版本不兼容导致配置失效。建议升级到适配对应Spring Boot版本的Bucket4j Starter（如0.19.x适配Spring Boot 3.x）。
• URL匹配规则：配置中url: /patient仅匹配精确路径/patient，若你的API是/patient/{id}或/patient/list这类子路径，需修改为/patient/**以匹配所有该前缀的请求。
• 客户端IP表达式：若应用部署在反向代理（如Nginx）后，getRemoteAddr()获取的是代理服务器IP而非真实客户端IP，导致限流逻辑按代理IP统计，无法触发限制。需：
  1. 配置反向代理传递X-Forwarded-For头
  2. 修改表达式为：expression: getHeader('X-Forwarded-For')
  3. 或启用Spring的ForwardedHeaderFilter处理真实IP
• 缓存初始化验证：注入CacheManager检查缓存是否正确创建：

  @Autowired
  private CacheManager cacheManager;
  
  @PostConstruct
  public void checkCache() {
      System.out.println("Available caches: " + cacheManager.getCacheNames());
  }
  

  确认输出包含rate-limit-buckets。

三、调试Bucket4j过滤器 #

• 开启调试日志：在application-local.yml中添加日志配置，查看过滤器执行细节：

  logging:
    level:
      com.giffing.bucket4j.spring.boot.starter: DEBUG
  

  启动后观察日志，确认是否有过滤器初始化日志、请求拦截日志，判断限流逻辑是否触发。
• 调整过滤器顺序：若存在其他过滤器（如Spring Security过滤器）优先级更高，会导致请求未经过Bucket4j过滤器。可通过order参数调整优先级：

  bucket4j:
    filters:
    - cache-name: rate-limit-buckets
      filter-method: servlet
      strategy: first
      url: /patient/**
      order: -100  # 调高优先级，确保先执行
      # 其他配置...
  

内容的提问来源于stack exchange，提问作者Ali Azlan