JHipster+Consul生产环境启用限流时抛出ClassNotFoundException异常

你在dev环境限流正常，prod环境抛出ClassNotFoundException，大概率是依赖引入、配置初始化或者打包环节出了问题，结合你的技术栈（Gateway+UAA+Consul+Hazelcast），我整理了几个必须检查的关键点：

1. 确认限流依赖在生产构建中被正确引入 #

JHipster 4.x的Gateway限流基于spring-cloud-zuul-ratelimit组件，如果你在dev环境能正常运行但prod不行，很可能是依赖被标记为了dev/test scope，导致生产包中没有包含这些类：

• 打开你的Gateway项目的pom.xml（如果用Maven），检查以下依赖的scope是否为compile或runtime，而非dev：

  <dependency>
      <groupId>com.marcosbarbero.cloud</groupId>
      <artifactId>spring-cloud-zuul-ratelimit</artifactId>
  </dependency>
  <dependency>
      <groupId>com.marcosbarbero.cloud</groupId>
      <artifactId>spring-cloud-zuul-ratelimit-hazelcast</artifactId>
  </dependency>
  

• 如果你用Gradle，确保这些依赖没有被放在developmentOnly或test配置块中。

2. 完善Hazelcast分布式限流的生产配置 #

既然你启用了Hazelcast作为限流存储，prod环境下必须明确配置限流组件与Hazelcast实例的绑定，否则会因为找不到对应的实现类抛出异常：
在application-prod.yml中补充以下配置：

zuul:
  ratelimit:
    enabled: true
    repository: hazelcast # 指定用Hazelcast存储限流数据
    hazelcast:
      instance-name: jhipster-hazelcast-instance # 要和你Hazelcast配置的实例名一致
      rate-limiter-error-handler: com.marcosbarbero.cloud.zuul.ratelimit.repository.hazelcast.HazelcastRateLimiterErrorHandler
    # 以下是具体的限流规则（根据你的需求调整）
    policies:
      your-service-id:
        limit: 100
        quota: 1000
        refresh-interval: 60
        type:
          - user
          - origin
          - url

同时确保Hazelcast在prod环境能正常形成集群（通过Consul服务发现），检查Gateway启动日志中是否有Hazelcast实例初始化成功的日志。

3. 验证生产环境的组件扫描范围 #

有时候prod环境的组件扫描配置会比dev更严格，导致限流相关的配置类没被加载：

• 检查Gateway主类上的@SpringBootApplication或@ComponentScan注解，确保包含了限流组件的包路径（比如com.marcosbarbero.cloud）。
• 如果你的自定义限流配置类在某个子包下，也要确保这个包被包含在扫描范围内。

4. 检查生产打包的完整性 #

如果生产环境的jar包没有正确打包所有依赖类，也会触发ClassNotFoundException：

• 用jar tf your-gateway-prod.jar命令查看jar包内容，确认是否存在com/marcosbarbero/cloud/zuul/ratelimit相关的类文件。
• 确保Maven构建时执行了spring-boot:repackage目标，生成的是可执行的fat jar，而非普通jar。

快速排查小技巧 #

• 先看抛出的ClassNotFoundException具体是哪个类，比如如果是HazelcastRateLimiter，直接定位到Hazelcast限流依赖的问题；如果是ZuulRateLimitFilter，则是核心限流组件的依赖缺失。
• 对比dev和prod的application.yml配置，确保所有限流相关的配置项在prod中都有正确设置，没有遗漏。

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