当Spring Boot遇见"ClassNotFoundException：org.springframework.data.redis.connection.zset.Tuple"——一次排障记录

关键词：Spring Boot、Redisson、ClassNotFoundException、Tuple、版本对齐

一、异常现场

今天在升级Redisson时，应用启动失败，日志里抛出：

java.lang.ClassNotFoundException: org.springframework.data.redis.connection.zset.Tuple

乍一看是"少jar"，但项目里明明已经引用了spring-boot-starter-data-redis。继续翻堆栈才发现，报错触发点位于：

org.redisson.spring.data.connection.RedissonConnection.<clinit>

说明Redisson在初始化阶段用到了Tuple这个类，而当前classpath里并没有。

二、原因分析

  1. org.springframework.data.redis.connection.zset.Tuple 属于spring-data-redis jar，版本不同包路径可能变化。
  2. 我的项目
  • Spring Boot 2.5.14
  • 手动指定spring-boot-starter-data-redis版本2.5.14
  • Redisson却用了3.23.4（官方推荐匹配Boot 2.7.x）

→ 高版本Redisson编译时依赖的API在低版本spring-data-redis中不存在，于是运行期ClassNotFoundException。

三、解决思路

核心：让Redisson与spring-data-redis版本对齐。

Spring Boot

推荐Redisson版本

2.5.x

3.16.8

2.6.x

3.17.7

2.7.x

3.23.4

3.0.x

3.24.0+

两种可行方案：

方案① 降级Redisson（快速）

<!-- 去掉手写版本号，交给Boot父POM -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

<!-- 降到与Boot 2.5匹配 -->
<dependency>
    <groupId>org.redisson</groupId>
    <artifactId>redisson-spring-boot-starter</artifactId>
    <version>3.16.8</version>
</dependency>

方案② 升级Spring Boot（彻底）

如果项目允许，直接把Boot升到2.7.x，即可继续用Redisson 3.23.4。

四、验证

  1. mvn clean package -U
  2. 启动应用，RedissonConnection初始化成功，Tuple类加载正常。
  3. Redis命令测试通过，异常消失。

五、避坑建议

  1. 不要手动锁定spring-boot-starter-data-redis版本，除非明确知道兼容性。
  2. 引入Redisson前，先查官方版本对照表。
  3. 使用mvn dependency:tree随时检查spring-data-redis被仲裁到哪个版本。
  4. 多模块项目记得统一dependencyManagement，防止子模块版本漂移。

六、一句话总结

“ClassNotFoundException：Tuple” 99%是Redisson与spring-data-redis版本错位——对齐版本即可瞬间修复！