<p>Spring Boot 3.x 中 Redis 连接池配置必须使用 spring.data.redis.lettuce.pool.* 路径且显式启用 enabled: true，同时需引入 commons-pool2 依赖，否则静默降级为单连接。</p>
spring.data.redis 配置层级必须严格匹配 Spring Boot 3.x 的自动配置路径
Spring Boot 3.x 彻底移除了 spring.redis.* 下的连接池配置支持，只认 spring.data.redis.* 开头的路径。如果你在 application.yml 里写的是：
spring:
redis:
host: localhost
lettuce:
pool:
max-active: 32那这个 max-active 就完全不会被读取——Lettuce 连接池工厂压根不监听这个路径。
正确写法必须是：
spring:
data:
redis:
host: localhost
port: 6379
lettuce:
pool:
enabled: true
max-active: 32
max-idle: 16
min-idle: 4
max-wait: 3000ms-
spring.data.redis.lettuce.pool.enabled: true是强制项，3.x 默认禁用池化，漏掉就永远是单连接 -
spring.redis.*路径下只剩基础连接参数（如host、port、password）还兼容，但所有pool子项已失效 - 如果同时存在
spring.redis.*和spring.data.redis.*，后者会覆盖前者中同名项，但池化配置不会“跨路径继承”
为什么改了配置却看不到连接数变化？检查 RedisConnectionFactory 实际类型
配置写对了，不代表生效了。最直接的验证方式是运行时检查实际注入的 RedisConnectionFactory 类型和池状态：
在任意 @Service 中加一段调试代码：
System.out.println(redisConnectionFactory.getClass().getName());
if (redisConnectionFactory instanceof LettuceConnectionFactory) {
LettuceConnectionFactory factory = (LettuceConnectionFactory) redisConnectionFactory;
System.out.println("Pool enabled: " + factory.isUsePooling());
System.out.println("Pool size: " + factory.getPoolConfig().getMaxTotal());
}常见结果及含义：
- 输出
org.springframework.data.redis.connection.lettuce.LettuceConnectionFactory且isUsePooling()为false→ 配置未触发池化，优先查enabled: true是否遗漏 - 输出
org.springframework.boot.autoconfigure.data.redis.LettuceConnectionConfiguration相关警告日志 → 表明自动配置类加载失败，大概率是依赖冲突或版本不匹配 -
getMaxTotal()返回8（Lettuce 默认值）→ 配置路径错误或commons-pool2缺失
commons-pool2 是硬性依赖，不是可选组件
Lettuce 本身不实现连接池逻辑，它依赖 org.apache.commons:commons-pool2 提供对象池能力。Spring Boot 3.x 的 starter 不再自动拉取它，必须显式声明：
Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。
<dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-pool2</artifactId> </dependency>
没这行，哪怕配置全对、路径全准，LettuceConnectionFactory 也会静默降级为非池化模式，且不报错——只在启动日志里埋一句 WARN o.s.b.a.d.r.RedisConnectionConfiguration - Unable to configure RedisConnectionFactory，很容易被忽略。
其他关键点：
- Spring Boot 3.2+ 推荐使用
commons-pool22.11.1+，低版本可能有线程安全问题 - 不要用
org.apache.commons:pool（老版 Jakarta Commons Pool），那是 v1，与 Lettuce 不兼容 - 如果项目里已有旧版
commons-pool2（比如被其他组件传递引入），需用<exclusions>强制升级
自定义 RedisConnectionFactory 时，必须手动启用池化
一旦你写了 @Bean public RedisConnectionFactory redisConnectionFactory()，Spring Boot 的自动配置就彻底退出，所有连接池参数都得手写：
@Bean
public RedisConnectionFactory redisConnectionFactory() {
RedisStandaloneConfiguration config = new RedisStandaloneConfiguration("localhost", 6379);
GenericObjectPoolConfig<?> poolConfig = new GenericObjectPoolConfig<>();
poolConfig.setMaxTotal(32);
poolConfig.setMaxIdle(16);
poolConfig.setMinIdle(4);
poolConfig.setMaxWaitMillis(3000);
<pre class='brush:php;toolbar:false;'>LettuceClientConfiguration clientConfig = LettuceClientConfiguration.builder()
.commandTimeout(Duration.ofSeconds(5))
.useSsl() // 如需
.pool(poolConfig)
.build();
return new LettuceConnectionFactory(config, clientConfig);}
这里最容易踩的坑：
- 漏掉
.pool(poolConfig)→ 没池化 - 用
LettuceClientConfiguration.builder().build()空构造 → 所有池参数丢失 - 把
GenericObjectPoolConfig和LettucePoolingClientConfiguration混用（后者已废弃） - 在配置类里用
@Value("${spring.data.redis.lettuce.pool.max-active}")手动读配置 → 多此一举，不如直接走自动配置
复杂点在于：连接池行为不是开关式生效，而是一组协同参数。比如 min-idle 太小，连接空闲后会被快速回收；max-wait 设为 -1（无限等待），在高并发下可能卡住线程而不抛异常——这些细节不验证运行态，光看配置根本发现不了。
