Spring Cacheable+Hazelcast客户端周期性NoClassDefFoundError问题求助

异常成因 #

1. 线程泄漏与类加载器失效：Web应用停止后，Hazelcast客户端的后台维护线程（比如成员发现、连接心跳线程）未被正确终止，这些线程绑定了已销毁的Web应用类加载器。当后续线程需要加载com.hazelcast.client.impl.clientside.SubsetMembers这个内部类时，使用的是失效的类加载器，直接抛出NoClassDefFoundError。
2. 客户端生命周期未与Spring同步：Spring容器销毁（Web应用停止）时，没有主动关闭Hazelcast客户端实例，导致客户端后台线程持续存活并执行类加载操作，而此时Web应用的类资源已被释放。
3. 版本不兼容：Hazelcast客户端与服务端版本不匹配时，内部类结构可能存在差异，在应用停止的临界场景下触发类加载失败。

解决方法 #

• 严格对齐客户端与服务端版本：检查项目依赖（Maven/Gradle）中hazelcast-client的版本，确保和本地用hz start启动的Hazelcast服务端版本完全一致（比如都使用5.3.6），避免内部类结构不兼容的问题。
• 绑定Hazelcast客户端到Spring生命周期：
  配置Spring管理的Hazelcast客户端Bean，并添加@PreDestroy方法确保容器关闭时主动销毁客户端：

  @Configuration
  public class HazelcastConfig {
      @Bean
      public HazelcastInstance hazelcastClient() {
          ClientConfig clientConfig = new ClientConfig();
          // 配置客户端连接信息，比如集群地址
          clientConfig.getNetworkConfig().addAddress("localhost:5701");
          return HazelcastClient.newHazelcastClient(clientConfig);
      }
  
      @PreDestroy
      public void shutdownHazelcast() {
          // 关闭所有客户端实例
          HazelcastClient.shutdownAll();
          // 或针对当前Bean实例关闭：hazelcastClient().shutdown();
      }
  }
  

  同时确保HazelcastCacheManager、自定义CacheResolver都依赖这个Spring管理的客户端实例，不要自行创建未被管理的客户端对象。
• 排查并终止泄漏线程：
  应用停止后，用jstack命令查看JVM线程状态，确认是否有名称含hazelcast的线程仍在运行。如果有，说明客户端未正确关闭，检查销毁逻辑是否执行到位，是否有其他代码持有客户端引用导致无法回收。
• 调整类加载策略（可选）：
  如果是类加载器隔离导致的问题，可将hazelcast-client依赖放到Web容器的共享类加载路径（比如Tomcat的shared/lib），让类由容器级加载器加载，避免Web应用类加载器销毁后无法访问类。但这种方式需要注意和其他依赖的兼容性，谨慎使用。

内容的提问来源于stack exchange，提问作者Wooyoung Tyler Kim