Redisson在Spring Boot项目里的集成我印象最深的一次踩坑是在一个老系统升级时按习惯直接加了org.redisson:redisson原始依赖写了一大段Config配置启动后却各种NoSuchMethodError排查了半天才发现是Redisson版本和Spring Boot版本的兼容性问题。后来在新项目里改用redisson-spring-boot-starter整个配置量直接降了一个数量级。很多同事问我说同样是“集成Redisson”为什么有时候用原始依赖有时候用Starter到底听谁的这篇就把两种集成方式从依赖、配置、代码、运行机理到坑点完整拆开讲一遍看完你就能根据自己的项目情况做选择。先说一个基本概念Redisson是一个基于Redis的Java客户端和Jedis、Lettuce属于同类工具但它不只是连接池而是提供了分布式锁、分布式集合、消息队列、布隆过滤器、延迟队列等一系列开箱即用的分布式组件。在Spring Boot项目里集成Redisson本质上会有两条路线一条是直接引入Redisson官方提供的原始依赖redisson然后自己写Config、自己创建RedissonClient并注册成Spring Bean另一条是引入redisson-spring-boot-starter让Spring Boot自动完成配置和客户端创建。这两条路线没有绝对的优劣关键看你的项目结构、维护成本和扩展诉求。1. 集成之前必须先想清楚原始依赖和Starter到底差在哪1.1 原始依赖Redisson只是被“接入”Spring不是被“接管”原始依赖方式下Redisson就是一个普通的Java库和Spring Boot没有任何自动装配关系。你需要自己构建一个org.redisson.config.Config对象调用Redisson.create(config)生成客户端再把这个客户端通过Bean丢给Spring容器。这种方式的控制力最强连接模式、线程池、序列化、Netty参数、集群节点列表全部由你亲手指定不会出现“Spring Boot悄悄改了你的配置”这种事。但代价也很明显代码量多、初始化逻辑要自己维护、多环境配置要自己做映射、生命周期管理稍微疏忽就会导致连接未释放。对于已经有成熟初始化逻辑、或者需要对接多套Redis环境的项目这种手动控制反而更稳妥因为自动配置往往只覆盖“一个Redis实例”这种最常见场景。1.2 Starter把“配置文件解析”和“Bean注册”交给自动配置完成redisson-spring-boot-starter的本质上就是把Redisson客户端和Spring Boot的AutoConfiguration机制结合起来。依赖引入后Spring Boot启动时会自动读取application.yml里的Redis相关配置自动创建RedissonClient自动把它注册进容器甚至连RedissonReactiveClient都会顺便生成。你不需要关注Config对象怎么构建也不需要写一行Bean。这符合Spring Boot“约定优于配置”的思路项目里能用Autowired直接注入RedissonClient配置内容也基本集中在YAML文件里改动方便。但自动配置的缺点也随之而来当项目需要多个不同Redis环境的客户端时自动配置只帮你建了一个剩下几个还得自己手动new当Spring Boot版本和Redisson版本不对齐时自动配置里的类名、方法签名可能对不上启动阶段就会直接报错排查起来比手动方式更麻烦。1.3 不会告诉你的版本对应关系这是集成Redisson最关键的环节比“选原始依赖还是Starter”更重要。Redisson官方在文档里维护着一张版本匹配表比如Redisson 3.27左右对应Spring Boot 3.2/3.3老一些的3.16、3.17则对应Spring Boot 2.1、2.2。如果你不加验证直接拿一个最新版Redisson去配一个很老的Spring Boot项目启动时大概率会碰到ClassNotFoundException或NoSuchMethodError。举个真实场景Spring Boot 3.x把javax命名空间换成了jakartaRedisson的Starter也同步做了适配。如果你的项目还在Spring Boot 2.x却把Starter升级到只支持Boot 3.x的版本自动配置加载时就会因为找不到javax.*类直接失败。这不是代码问题就是版本错配。我的建议是无论走哪条路先去Redisson官方GitHub的README或wiki里翻一翻版本对应表确定好当前Spring Boot版本对应的Redisson大版本再去Maven仓库锁定具体版本号。宁可少用新特性也不要盲目追新。2. 方案一用原始依赖redisson手动集成完整流程拆解2.1 引入依赖版本号别随便写原始依赖只需要在pom.xml里加一个坐标dependency groupIdorg.redisson/groupId artifactIdredisson/artifactId version3.37.0/version /dependency这里重点提醒redisson原始依赖不包含Spring Boot自动配置所以不要指望加上后YAML里的spring.redis配置能直接生效。你需要单独写配置类。版本号的选择建议和你的JDK版本同步看如果项目是JDK 8选3.17~3.23这类稳定版就够了JDK 11可以选更新的大版本JDK 17跑Spring Boot 3.x就往3.30之后看。不要盲目用最新版原因上节已经说过。2.2 写一个配置类手动创建RedissonClient先看一段最基础的配置代码Configuration public class RedissonConfig { Bean(destroyMethod shutdown) public RedissonClient redissonClient() { Config config new Config(); config.useSingleServer() .setAddress(redis://127.0.0.1:6379) .setDatabase(0) .setPassword(your-password) .setConnectionPoolSize(64) .setConnectionMinimumIdleSize(16) .setConnectTimeout(10000) .setTimeout(3000) .setIdleConnectionTimeout(10000) .setRetryAttempts(3) .setRetryInterval(1500); return Redisson.create(config); } }这段代码的重点在于理解Config里的几个核心属性address必须带redis://前缀否则Redisson无法解析这是新手最常见的报错点。connectionPoolSize表示连接池最大连接数connectionMinimumIdleSize是连接池最小空闲连接数两者最好和业务并发量对应起来盲目调大会白白占用Redis服务端连接资源。timeout是命令等待同步结果的超时时间retryAttempts和retryInterval控制失败重试这几个参数在Redis抖动时影响非常明显。如果你们用的是集群模式就把useSingleServer()换成useClusterServers()地址列表按redis://ip1:6379的格式逐个写进去。主从模式则用useMasterSlaveServers()区别在于把主节点地址和从节点地址分开配。单机起步、未来想扩容的场景建议直接按集群模式配好免得以后改配置类。2.3 把RedissonClient交给Spring管理生命周期别忽略Bean(destroyMethod shutdown)是很容易被忽略的一行。Redisson客户端内部维护着Netty线程组、连接池、定时任务等资源如果Spring容器关闭时不调用shutdown()这些线程不会自动清理在单元测试或者应用反复重启时很容易看到线程数不断上涨最终触发OutOfMemoryError。所以一定要显式声明销毁方法。如果你的项目需要多个Redisson客户端比如同时连接两个独立Redis集群可以给不同的Bean设置不同名字并注入不同配置Bean(name redissonClientOrder) Primary public RedissonClient orderRedissonClient() { ... } Bean(name redissonClientLog) public RedissonClient logRedissonClient() { ... }使用时配合Qualifier(redissonClientOrder)或者Resource(name redissonClientOrder)区分即可。我实际经验是多客户端场景最好在命名上带业务前缀否则时间一长自己都分不清哪个Bean配的是哪个环境。2.4 配置文件里的参数怎么和Config优雅对接原始依赖方式下不建议把一大串参数硬编码在Java类里。更常见的做法是用ConfigurationProperties统一定义一个自定义配置前缀比如app: redisson: address: redis://127.0.0.1:6379 password: your-password database: 0 connection-pool-size: 64然后在配置类里用Value或Environment读取。如果参数多建议直接用ConfigurationProperties(prefix app.redisson)配合一个RedissonProperties类这样配置集中、可维护性高多环境切换时只需要改YAML不用改代码。这部分虽然比Starter多写了几行但从配置管理和多人协作的角度来看反而是优势。3. 方案二用Spring Boot Starter集成笔直走向“零样板代码”3.1 引入Starter依赖注意排除项Starter方式的核心依赖如下dependency groupIdorg.redisson/groupId artifactIdredisson-spring-boot-starter/artifactId version3.37.0/version /dependency如果你已经在项目里单独引入了spring-boot-starter-data-redis其实两者可以共存因为Spring Boot默认用Lettuce创建RedisTemplate而Redisson的Starter只负责创建RedissonClient互不干预。但如果你的项目只为了使用Redisson的功能就不要再引入spring-boot-starter-data-redis否则项目里会同时存在两套Redis客户端配置排查问题时容易误判。3.2 在application.yml里配置两种配置格式要认清Redisson的Starter支持两种配置方式。一种是直接复用Spring Boot的Redis通用配置比如在application.yml里写spring: data: redis: host: 127.0.0.1 port: 6379 database: 0 password: your-password这种方式最简单适合单机场景。但如果你需要调整连接池大小、超时时间等细粒度参数就需要用Redisson自己的YAML配置写在spring.redis.redisson.config之下spring: redis: redisson: config: | singleServerConfig: address: redis://127.0.0.1:6379 database: 0 password: your-password connectionMinimumIdleSize: 8 connectionPoolSize: 32 timeout: 3000注意两点第一旧版本Redisson Starter只认spring.redis.redisson.*前缀但Spring Boot 2.4之后把Redis前缀改成了spring.data.redis不同版本的Redisson Starter对此支持不一致所以如果发现配置没生效先确认版本是不是对应上了新的前缀规则第二config的字符串内容必须严格符合Redisson自己的YAML格式缩进错了直接启动失败。3.3 直接注入RedissonClient业务代码示例Starter自动配置完成之后你的业务类里只需要一个AutowiredRestController public class RedissonController { Autowired private RedissonClient redissonClient; GetMapping(/try-lock) public String tryLock() throws InterruptedException { RLock lock redissonClient.getLock(order:1001); boolean acquired lock.tryLock(3, 10, TimeUnit.SECONDS); if (acquired) { try { // 这里写业务逻辑比如扣库存、下单 return 获取锁成功执行业务; } finally { lock.unlock(); } } return 获取锁失败请稍后重试; } }这段代码里的tryLock(3, 10, TimeUnit.SECONDS)含义是最多等待3秒获取锁拿到锁后10秒内自动释放。如果你希望锁的持有时间能自动续期就不要传leaseTime只传等待时间boolean acquired lock.tryLock(3, TimeUnit.SECONDS);这样Redisson的看门狗机制会每10秒检查一次只要业务线程还活着就自动续期锁避免业务没执行完锁就过期了。这一点在分布式事务和异步任务里特别关键很多线上死锁问题都出在“锁过期但业务没结束”。除了锁Starter方式下其他分布式对象也能直接使用比如RBucket做缓存、RMapCache做带过期时间的Map、RTopic做发布订阅、RBlockingDeque做延迟队列。日常开发里这些组件比自己去实现Redis工具类靠谱得多因为Redisson内部已经处理好了序列化、重试、断线重连这些脏活。3.4 想改默认行为有几种体面的覆盖姿势自动配置并不是永远不可触碰。如果你不满意Starter的默认客户端参数有两种常见做法。第一种是实现RedissonAutoConfigurationCustomizer接口在自动配置创建Config之前对它做定制Configuration public class RedissonCustomizerConfig { Bean public RedissonAutoConfigurationCustomizer redissonCustomizer() { return config - config.setThreads(8) .setNettyThreads(16) .setTransportMode(TransportMode.NIO); } }第二种是直接声明自己的RedissonClientBean把自动配置创建的覆盖掉。虽然Bean冲突时会触发启动异常但如果你在自定义Bean上加了ConditionalOnMissingBean或者用Primary标记Spring容器会优先走你的版本。最彻底的办法是在启动类上排除Redisson自动配置类然后完全手动创建客户端。但这种方案等于又回到了原始依赖方式所以只有极少数需要完全掌控的场景才值得这么做。4. 两种方案实战客观对比代码量、维护成本、启动和运行差异4.1 功能与体验对照表对比维度原始依赖redissonStarterredisson-spring-boot-starter集成代码量需手写Config类和Bean约20~40行几乎为零YAML写完直接注入配置方式Java硬编码或自定义Properties映射application.yml统一管理控制粒度完全控制每参数自己指定自动配置覆盖常见场景多环境适配性灵活可写多套Config Bean一个自动配置Bean多套环境需额外处理连接生命周期需手动声明destroyMethod自动随Spring容器启停排查难度报错点直观问题定位简单自动配置类介入报错看堆栈需多翻一层版本匹配相对宽容但也要看API严格依赖Spring Boot版本对应关系从这张表能看出Starter并不是在所有维度都赢。它最大的价值是“快”和“简洁”但你付出的代价是“控制权”和“透明性”。我个人感受是新项目、单Redis实例、团队成员对Redisson不太熟直接上Starter最省心老项目、多Redis集群、或者团队里已经有一套自己的初始化规范用原始依赖反而更可控。4.2 常见问题排查速查表故障现象可能原因解决方案启动报NoSuchMethodErrorRedisson版本与Spring Boot版本不匹配查官方版本对应表更换Redisson版本启动报ClassNotFoundException: javax.*使用Boot 3.x但Redisson版本偏老升级Redisson到支持jakarta的版本Connection refused: no further informationaddress没加redis://前缀把地址写成redis://ip:port日志出现Failed to submit a listener notification taskNetty线程数不足调大setNettyThreads或减少框架线程抢占锁在业务执行中途失效tryLock时传了leaseTime且时间过短不传leaseTime启用看门狗自动续期YAML里写了配置但客户端参数没变化Redisson Starter不认识该配置前缀确认使用当前版本支持的spring.data.redis还是spring.redis.redisson同时注入了多个RedissonClientBean启动报错自动配置和自定义Bean冲突用Primary指定主Bean或排除自动配置项目里同时存在Lettuce和Redisson连接数翻倍两套客户端各自维护连接池明确职责边界避免重复引入spring-boot-starter-data-redis4.3 我实际踩过的三次坑说给你听第一次是上面提到的老项目升级。当时直接把Redisson从3.12跳到3.30结果Spring Boot 2.2的项目里一堆类路径冲突持续报java.lang.NoSuchMethodError: org.springframework.boot.autoconfigure.data.redis.RedisProperties。后来把Redisson降回3.16问题消失。从此我养成了一个习惯每个项目集成Redisson之前第一件事不是写代码而是先确认版本对应表。第二次是Starter方式下配置没生效。我按官方文档在application.yml里写了spring.redis.redisson.config但连接池最小空闲数始终是默认值。查了半天发现项目用的Redisson Starter版本只认spring.data.redis前缀spring.redis.redisson那一大段配置根本没被读取。所以如果你发现配置参数没生效先看Starter版本的源码或者文档确认它究竟读哪个前缀。第三次是Lock和Transactional混用。我在一个加了Transactional的方法里用Redisson锁保护一段数据库更新逻辑结果锁释放时事务还没提交其他线程已经拿到锁去读了旧数据。这个坑不怪Redisson而是锁边界和事务边界没设计清楚。正确做法是锁范围比事务范围大或者把事务提交放在锁释放之前否则分布式锁形同虚设。5. 最后分享一点个人习惯顺便聊聊扩展思路做了多个项目的集成之后我现在的基本套路是这样新项目、单一Redis实例、业务主要用分布式锁和缓存直接选redisson-spring-boot-starter配置集中在YAML代码里只管注入RedissonClient把精力花在业务上。但如果项目里有多个Redis环境或者有自定义的连接池调优诉求我会退回到原始依赖方式专门写一个RedissonAutoConfiguration类把所有客户端的创建逻辑集中管理并且在Bean命名里体现业务含义。另外还有一个扩展方向值得提如果你的项目用了Spring Cloud或者微服务架构可以基于Redisson的RTopic做本地缓存过期通知或者用RDelayedQueue实现订单超时未支付自动取消这类延时任务。这些能力无论用原始依赖还是Starter都能获得区别只在于你集成阶段图省事还是图掌控。先花十分钟把版本对应关系查清楚再根据项目规模选一条路后面能少踩很多坑。