Redisson Spring Boot 依赖冲突快速修复指南NoClassDefFoundError 与版本兼容的完整排查【免费下载链接】redissonRedisson: Valkey Redis Java Client and Real-Time Data Platform. Sync/Async/RxJava/Reactive API. Over 50 Valkey and Redis based Java objects and services: Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Spring, Tomcat, Scheduler, JCache API, Hibernate, RPC, local cache..项目地址: https://gitcode.com/GitHub_Trending/re/redisson上周三凌晨一个 Spring Boot 2.7 的老项目升级 Redisson 之后直接起不来了。日志刷出来的第一行就是它java.lang.NoClassDefFoundError: org/springframework/data/redis/ connection/RedisConnectionFactory Caused by: java.lang.ClassNotFoundException: ... at org.redisson.spring.starter.RedissonAutoConfigurationV2场景很典型starter 拉进来的是适配最新 Spring Boot 的 Spring Data Redis 适配模块而你的项目还停在 2.7。两边的RedisConnectionFactory接口签名对不上类加载直接失败。下面这套排查路径是我踩过坑之后沉淀下来的。把报错读对NoClassDefFoundError 堆栈的关键行在哪先别管上面那一片at ...调用链你的眼睛只需要盯两个位置 第一Caused by指向的那一行。那才是根因外层异常只是它传导出来的症状。NoClassDefFoundError和ClassNotFoundException在这里是同源的JVM 找不到某个类可能是 jar 没进来也可能是 jar 里类被改过名、挪了包。第二at行里第一个org.redisson开头的帧。它告诉你谁在用这个类。如果这个类属于org.springframework.data.redis或org.springframework.boot说明是 Redisson 适配层和你项目里的 Spring 版本错位了——这是 Redisson 依赖冲突里最高发的一类。一个快速判断法你项目里的 Spring Boot 版本和你引的 redisson-spring-data 模块适配的版本差得越远报这种错的概率越高。顺藤摸瓜redisson-spring-data 模块与 Spring Boot 版本对应表把 Redisson 的 Spring 集成文档 翻出来核心机制一句话redisson-spring-boot-starter依赖的是适配最新版 Spring Boot的redisson-spring-data模块需要支持旧版 Spring Boot 时要手动降级。拆开 starter 的 pom.xmlredisson-spring/redisson-spring-boot-starter/pom.xml能看到依赖链长这样你的项目 └─ redisson-spring-boot-starter ├─ redisson (核心客户端) ├─ redisson-spring-data-41 (适配最新 Spring Boot 的适配器) ├─ spring-boot-starter-data-redis (starter 本身) └─ spring-boot-actuator (provided/optional可选)redisson-spring-data-41里面编译时用的是 spring-data-redis 4.1.0见redisson-spring/redisson-spring-data/redisson-spring-data-41/pom.xml。而 Spring Boot 2.7 项目里 spring-data-redis 是 2.7.x。两个版本的同名接口签名不兼容这就是错位根因。官方文档给出的模块 ↔ Spring Boot 版本对应关系建议收藏redisson-spring-data 模块适配 Spring Boot 版本redisson-spring-data-161.3.yredisson-spring-data-171.4.yredisson-spring-data-181.5.yredisson-spring-data-20 ~ 272.0.y ~ 2.7.yredisson-spring-data-30 ~ 353.0.y ~ 3.5.yredisson-spring-data-40 ~ 414.x.y比如 2.7 的项目对应的是redisson-spring-data-27内部依赖 spring-data-redis 2.7.18。对症下刀三档处理方案成本与风险对比同样是修下手的位置不一样。先上对比表再逐档展开。档位适用场景改动成本风险应急档排除冲突依赖线上起不来要最快恢复只改 pom/build 脚本低换的是同版本号的等价适配模块日常档属性统一版本长期维护项目防升级复发加几行版本属性低全项目版本收敛进阶档排除自动配置要完全接管初始化、多客户端共存主类 新增配置类中RedissonClient 生命周期自己维护应急档排除冲突依赖手动指定匹配版本把 starter 拖进来的最新版适配模块排掉手动换上与你 Spring Boot 版本匹配的那个排除传递依赖 把引包时被顺带拖进来的依赖踢出去。Maven 写法dependency groupIdorg.redisson/groupId artifactIdredisson-spring-boot-starter/artifactId versionxVERSIONx/version exclusions !-- 排掉 starter 默认带进来的最新适配模块 -- exclusion groupIdorg.redisson/groupId artifactIdredisson-spring-data-40/artifactId /exclusion /exclusions /dependency !-- 手动补上与 Spring Boot 版本匹配的适配模块版本号保持一致 -- dependency groupIdorg.redisson/groupId artifactIdredisson-spring-data-27/artifactId versionxVERSIONx/version /dependencyGradle 写法// 排除 starter 默认带入的最新 spring-data 适配模块 implementation(org.redisson:redisson-spring-boot-starter:xVERSIONx) { exclude group: org.redisson, module: redisson-spring-data-40 } // 换回与 Spring Boot 2.7 匹配的适配模块 implementation org.redisson:redisson-spring-data-27:xVERSIONx注意xVERSIONx是官方文档里的占位符两个模块版本号必须一致都填你实际用的 Redisson 版本。排除哪个、补哪个对照上面那张表。日常档用属性统一管理版本防止升级复发应急之后顺手把版本归属权收回来。Redisson 的 FAQ 就给了现成套路Netty 版本被 Spring Boot 拖跑时直接在properties里定义netty.versionnetty.version这类属性会被 Spring Boot 的 BOM 识别从而覆盖传递依赖的版本。Mavenproperties !-- 强制全项目的 Netty 使用指定版本压制传递依赖 -- netty.version4.2.9.Final/netty.version /propertiesGradle 的对应习惯是 resolutionStrategy 强制configurations.all { resolutionStrategy { // 与 Maven 的 netty.version 属性等价的强制锁定 force io.netty:netty-handler:4.2.9.Final } }版本归属权收在一个地方以后谁升级改一处就行不会又出现三个地方三个版本。进阶档排除自动配置完全接管 Redisson 初始化如果你的场景更复杂——多个 Redis 客户端共存、或者想绕开自动装配的所有不确定性——就把 Redisson 的自动配置类直接摘掉手动建 Bean。自动配置类按 Spring Boot 版本区分见 Spring 集成文档 的 FAQSpring Boot 版本要排除的自动配置类4.0RedissonAutoConfigurationV42.7RedissonAutoConfigurationV22.6 及以下RedissonAutoConfiguration主类上排除以 2.7 为例SpringBootApplication EnableAutoConfiguration(exclude { RedissonAutoConfigurationV2.class // 摘掉 Redisson 自动装配 }) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }然后自己写配置类从 redisson.yaml 构建客户端Configuration public class RedissonConfig { Bean(destroyMethod shutdown) // 别忘了 shutdown连接池要释放 public RedissonClient redisson( Value(classpath:/redisson.yaml) Resource configFile) throws IOException { Config config Config.fromYAML(configFile.getInputStream()); return Redisson.create(config); } }yaml 的完整格式参考 Redisson 配置文档。别急着关单修复后的 Maven 与 Gradle 依赖树检查改完 pom 别直接宣布修复先跑依赖树确认树对了再重启。依赖树就是把所有传递依赖引一个包时顺带拖进来的依赖摊开来给你看的那张图。Maven# 只看 redisson 相关分支确认适配模块只剩你要的那一个 mvn dependency:tree -Dincludesorg.redisson预期输出应该只有你手动指定的模块类似[INFO] - org.redisson:redisson-spring-boot-starter:jar [INFO] | - org.redisson:redisson:jar [INFO] - org.redisson:redisson-spring-data-27:jar !-- 只剩这一个适配模块 --Gradle# 在 runtimeClasspath 上过滤 redis 相关依赖 ./gradlew dependencies --configuration runtimeClasspath | grep redis预期同样只出现一个redisson-spring-data-xx且 xx 与你 Spring Boot 版本对得上。如果看到两个适配模块同时挂着说明排除没生效回去检查 exclusion 的 groupId 和 artifactId 有没有拼对。打疫苗以后升级 Redisson 或 Spring Boot 前的自检清单这次修完不算完升级前把这五条过一遍坑基本不会再踩 先查对应表对照 Spring 集成文档 里的模块 ↔ Spring Boot 版本表确认你要换的redisson-spring-data-xx匹配目标版本两个模块版本号一致starter 和手动指定的 spring-data 模块必须同版本号不能一个 4.x 一个 3.x跑依赖树mvn dependency:tree -Dincludesorg.redisson或 Gradle 等价命令确认适配模块唯一确认自动配置类版本升跨 Spring Boot 大版本时RedissonAutoConfigurationV2/V4这些类名会随版本变exclude 列表要同步改冒烟验证本地起一次应用确认RedissonClientBean 正常创建、连上一次 Redis再谈发布依赖冲突的本质从来不是哪个包坏了而是版本的归属权没人管——谁的 BOM 说了算谁就赢。把它收回到你自己手里这类问题就不会再来。【免费下载链接】redissonRedisson: Valkey Redis Java Client and Real-Time Data Platform. Sync/Async/RxJava/Reactive API. Over 50 Valkey and Redis based Java objects and services: Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Spring, Tomcat, Scheduler, JCache API, Hibernate, RPC, local cache..项目地址: https://gitcode.com/GitHub_Trending/re/redisson创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Redisson Spring Boot 依赖冲突快速修复指南NoClassDefFoundError 与版本兼容的完整排查【免费下载链接】redissonRedisson: Valkey Redis Java Client and Real-Time Data Platform. Sync/Async/RxJava/Reactive API. Over 50 Valkey and Redis based Java objects and services: Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Spring, Tomcat, Scheduler, JCache API, Hibernate, RPC, local cache..项目地址: https://gitcode.com/GitHub_Trending/re/redisson上周三凌晨一个 Spring Boot 2.7 的老项目升级 Redisson 之后直接起不来了。日志刷出来的第一行就是它java.lang.NoClassDefFoundError: org/springframework/data/redis/ connection/RedisConnectionFactory Caused by: java.lang.ClassNotFoundException: ... at org.redisson.spring.starter.RedissonAutoConfigurationV2场景很典型starter 拉进来的是适配最新 Spring Boot 的 Spring Data Redis 适配模块而你的项目还停在 2.7。两边的RedisConnectionFactory接口签名对不上类加载直接失败。下面这套排查路径是我踩过坑之后沉淀下来的。把报错读对NoClassDefFoundError 堆栈的关键行在哪先别管上面那一片at ...调用链你的眼睛只需要盯两个位置 第一Caused by指向的那一行。那才是根因外层异常只是它传导出来的症状。NoClassDefFoundError和ClassNotFoundException在这里是同源的JVM 找不到某个类可能是 jar 没进来也可能是 jar 里类被改过名、挪了包。第二at行里第一个org.redisson开头的帧。它告诉你谁在用这个类。如果这个类属于org.springframework.data.redis或org.springframework.boot说明是 Redisson 适配层和你项目里的 Spring 版本错位了——这是 Redisson 依赖冲突里最高发的一类。一个快速判断法你项目里的 Spring Boot 版本和你引的 redisson-spring-data 模块适配的版本差得越远报这种错的概率越高。顺藤摸瓜redisson-spring-data 模块与 Spring Boot 版本对应表把 Redisson 的 Spring 集成文档 翻出来核心机制一句话redisson-spring-boot-starter依赖的是适配最新版 Spring Boot的redisson-spring-data模块需要支持旧版 Spring Boot 时要手动降级。拆开 starter 的 pom.xmlredisson-spring/redisson-spring-boot-starter/pom.xml能看到依赖链长这样你的项目 └─ redisson-spring-boot-starter ├─ redisson (核心客户端) ├─ redisson-spring-data-41 (适配最新 Spring Boot 的适配器) ├─ spring-boot-starter-data-redis (starter 本身) └─ spring-boot-actuator (provided/optional可选)redisson-spring-data-41里面编译时用的是 spring-data-redis 4.1.0见redisson-spring/redisson-spring-data/redisson-spring-data-41/pom.xml。而 Spring Boot 2.7 项目里 spring-data-redis 是 2.7.x。两个版本的同名接口签名不兼容这就是错位根因。官方文档给出的模块 ↔ Spring Boot 版本对应关系建议收藏redisson-spring-data 模块适配 Spring Boot 版本redisson-spring-data-161.3.yredisson-spring-data-171.4.yredisson-spring-data-181.5.yredisson-spring-data-20 ~ 272.0.y ~ 2.7.yredisson-spring-data-30 ~ 353.0.y ~ 3.5.yredisson-spring-data-40 ~ 414.x.y比如 2.7 的项目对应的是redisson-spring-data-27内部依赖 spring-data-redis 2.7.18。对症下刀三档处理方案成本与风险对比同样是修下手的位置不一样。先上对比表再逐档展开。档位适用场景改动成本风险应急档排除冲突依赖线上起不来要最快恢复只改 pom/build 脚本低换的是同版本号的等价适配模块日常档属性统一版本长期维护项目防升级复发加几行版本属性低全项目版本收敛进阶档排除自动配置要完全接管初始化、多客户端共存主类 新增配置类中RedissonClient 生命周期自己维护应急档排除冲突依赖手动指定匹配版本把 starter 拖进来的最新版适配模块排掉手动换上与你 Spring Boot 版本匹配的那个排除传递依赖 把引包时被顺带拖进来的依赖踢出去。Maven 写法dependency groupIdorg.redisson/groupId artifactIdredisson-spring-boot-starter/artifactId versionxVERSIONx/version exclusions !-- 排掉 starter 默认带进来的最新适配模块 -- exclusion groupIdorg.redisson/groupId artifactIdredisson-spring-data-40/artifactId /exclusion /exclusions /dependency !-- 手动补上与 Spring Boot 版本匹配的适配模块版本号保持一致 -- dependency groupIdorg.redisson/groupId artifactIdredisson-spring-data-27/artifactId versionxVERSIONx/version /dependencyGradle 写法// 排除 starter 默认带入的最新 spring-data 适配模块 implementation(org.redisson:redisson-spring-boot-starter:xVERSIONx) { exclude group: org.redisson, module: redisson-spring-data-40 } // 换回与 Spring Boot 2.7 匹配的适配模块 implementation org.redisson:redisson-spring-data-27:xVERSIONx注意xVERSIONx是官方文档里的占位符两个模块版本号必须一致都填你实际用的 Redisson 版本。排除哪个、补哪个对照上面那张表。日常档用属性统一管理版本防止升级复发应急之后顺手把版本归属权收回来。Redisson 的 FAQ 就给了现成套路Netty 版本被 Spring Boot 拖跑时直接在properties里定义netty.versionnetty.version这类属性会被 Spring Boot 的 BOM 识别从而覆盖传递依赖的版本。Mavenproperties !-- 强制全项目的 Netty 使用指定版本压制传递依赖 -- netty.version4.2.9.Final/netty.version /propertiesGradle 的对应习惯是 resolutionStrategy 强制configurations.all { resolutionStrategy { // 与 Maven 的 netty.version 属性等价的强制锁定 force io.netty:netty-handler:4.2.9.Final } }版本归属权收在一个地方以后谁升级改一处就行不会又出现三个地方三个版本。进阶档排除自动配置完全接管 Redisson 初始化如果你的场景更复杂——多个 Redis 客户端共存、或者想绕开自动装配的所有不确定性——就把 Redisson 的自动配置类直接摘掉手动建 Bean。自动配置类按 Spring Boot 版本区分见 Spring 集成文档 的 FAQSpring Boot 版本要排除的自动配置类4.0RedissonAutoConfigurationV42.7RedissonAutoConfigurationV22.6 及以下RedissonAutoConfiguration主类上排除以 2.7 为例SpringBootApplication EnableAutoConfiguration(exclude { RedissonAutoConfigurationV2.class // 摘掉 Redisson 自动装配 }) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }然后自己写配置类从 redisson.yaml 构建客户端Configuration public class RedissonConfig { Bean(destroyMethod shutdown) // 别忘了 shutdown连接池要释放 public RedissonClient redisson( Value(classpath:/redisson.yaml) Resource configFile) throws IOException { Config config Config.fromYAML(configFile.getInputStream()); return Redisson.create(config); } }yaml 的完整格式参考 Redisson 配置文档。别急着关单修复后的 Maven 与 Gradle 依赖树检查改完 pom 别直接宣布修复先跑依赖树确认树对了再重启。依赖树就是把所有传递依赖引一个包时顺带拖进来的依赖摊开来给你看的那张图。Maven# 只看 redisson 相关分支确认适配模块只剩你要的那一个 mvn dependency:tree -Dincludesorg.redisson预期输出应该只有你手动指定的模块类似[INFO] - org.redisson:redisson-spring-boot-starter:jar [INFO] | - org.redisson:redisson:jar [INFO] - org.redisson:redisson-spring-data-27:jar !-- 只剩这一个适配模块 --Gradle# 在 runtimeClasspath 上过滤 redis 相关依赖 ./gradlew dependencies --configuration runtimeClasspath | grep redis预期同样只出现一个redisson-spring-data-xx且 xx 与你 Spring Boot 版本对得上。如果看到两个适配模块同时挂着说明排除没生效回去检查 exclusion 的 groupId 和 artifactId 有没有拼对。打疫苗以后升级 Redisson 或 Spring Boot 前的自检清单这次修完不算完升级前把这五条过一遍坑基本不会再踩 先查对应表对照 Spring 集成文档 里的模块 ↔ Spring Boot 版本表确认你要换的redisson-spring-data-xx匹配目标版本两个模块版本号一致starter 和手动指定的 spring-data 模块必须同版本号不能一个 4.x 一个 3.x跑依赖树mvn dependency:tree -Dincludesorg.redisson或 Gradle 等价命令确认适配模块唯一确认自动配置类版本升跨 Spring Boot 大版本时RedissonAutoConfigurationV2/V4这些类名会随版本变exclude 列表要同步改冒烟验证本地起一次应用确认RedissonClientBean 正常创建、连上一次 Redis再谈发布依赖冲突的本质从来不是哪个包坏了而是版本的归属权没人管——谁的 BOM 说了算谁就赢。把它收回到你自己手里这类问题就不会再来。【免费下载链接】redissonRedisson: Valkey Redis Java Client and Real-Time Data Platform. Sync/Async/RxJava/Reactive API. Over 50 Valkey and Redis based Java objects and services: Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Spring, Tomcat, Scheduler, JCache API, Hibernate, RPC, local cache..项目地址: https://gitcode.com/GitHub_Trending/re/redisson创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
