2.4.6 Redis⾃动配置源码剖析

Spring Boot Redis 自动配置源码剖析

Spring Boot 对 Redis 的自动配置以 RedisAutoConfiguration 为核心入口，通过条件注解、配置属性绑定和连接工厂的智能选择，实现了开箱即用的 Redis 集成体验。

一、核心入口：RedisAutoConfiguration

RedisAutoConfiguration 是 Redis 自动配置的总入口，位于 org.springframework.boot.autoconfigure.data.redis 包下。其类定义上的注解已经勾勒出整个自动配置的骨架：

@Configuration(proxyBeanMethods = false)@ConditionalOnClass(RedisOperations.class)@EnableConfigurationProperties(RedisProperties.class)@Import({    LettuceConnectionConfiguration.class,    JedisConnectionConfiguration.class})public class RedisAutoConfiguration {    // ...}

1.1 四大条件注解解析

注解	作用	在 RedisAutoConfiguration 中的含义
`@ConditionalOnClass(RedisOperations.class)`	Classpath 中存在指定类时生效	`RedisOperations` 是 `RedisTemplate` 实现的接口，确保 Spring Data Redis 核心依赖已引入
`@EnableConfigurationProperties(RedisProperties.class)`	启用指定类的配置属性绑定	将 `application.yml` 中以 `spring.redis` 为前缀的配置项绑定到 `RedisProperties` 对象
`@Import`	导入连接配置类	按顺序导入 `LettuceConnectionConfiguration` 和 `JedisConnectionConfiguration`，分别对应两种 Redis 客户端驱动

1.2 RedisProperties：配置属性绑定

RedisProperties 使用 @ConfigurationProperties(prefix = "spring.redis") 注解，将 spring.redis 前缀的所有配置项映射到 Java 对象。它支持单机、集群（Cluster）、哨兵（Sentinel）三种部署模式，以及 Jedis 和 Lettuce 两种客户端的专属配置。

二、连接工厂的二选一：Lettuce vs Jedis

@Import 导入的两个配置类，通过条件注解实现智能选择：

// LettuceConnectionConfiguration（默认）@Configuration(proxyBeanMethods = false)@ConditionalOnClass(LettuceConnection.class)@ConditionalOnProperty(name = "spring.redis.client-type",     havingValue = "lettuce", matchIfMissing = true)  // 关键：未配置时默认选中class LettuceConnectionConfiguration {    @Bean    @ConditionalOnMissingBean(RedisConnectionFactory.class)    public LettuceConnectionFactory redisConnectionFactory() { ... }}// JedisConnectionConfiguration@Configuration(proxyBeanMethods = false)@ConditionalOnClass(JedisConnection.class)@ConditionalOnProperty(name = "spring.redis.client-type", havingValue = "jedis")class JedisConnectionConfiguration {    @Bean    @ConditionalOnMissingBean(RedisConnectionFactory.class)    public JedisConnectionFactory redisConnectionFactory() { ... }}

默认选中的是 Lettuce，原因在于 matchIfMissing = true——当用户没有配置 spring.redis.client-type 时，Lettuce 分支的条件满足，而 Jedis 分支不满足，因此 Lettuce 成为默认选项。

Lettuce vs Jedis：Lettuce 基于 Netty 实现，支持异步和响应式编程，连接可共享，在高并发场景下性能更优；Jedis 是同步阻塞式客户端，每个连接独立，实现更简单直接。

三、核心 Bean 创建：RedisTemplate 与 StringRedisTemplate

RedisAutoConfiguration 的主体通过两个 @Bean 方法创建了两种操作模板：

@Bean@ConditionalOnMissingBean(name = "redisTemplate")@ConditionalOnSingleCandidate(RedisConnectionFactory.class)public RedisTemplate<Object, Object> redisTemplate(RedisConnectionFactory redisConnectionFactory) {    RedisTemplate<Object, Object> template = new RedisTemplate<>();    template.setConnectionFactory(redisConnectionFactory);    return template;}@Bean@ConditionalOnMissingBean@ConditionalOnSingleCandidate(RedisConnectionFactory.class)public StringRedisTemplate stringRedisTemplate(RedisConnectionFactory redisConnectionFactory) {    return new StringRedisTemplate(redisConnectionFactory);}

3.1 两个模板的差异

模板	key-value 类型	默认序列化器	适用场景
RedisTemplate	Object → Object	`JdkSerializationRedisSerializer`	存储 Java 对象（需实现 `Serializable`）
StringRedisTemplate	String → String	`StringRedisSerializer`（UTF-8）	存储字符串，如验证码、配置项、计数器

3.2 @ConditionalOnMissingBean 的谦让原则

两个模板的创建都带有 @ConditionalOnMissingBean：

如果开发者自定义了 RedisTemplate Bean，自动配置的默认实例将不会创建
同理，StringRedisTemplate 也遵循相同的谦让规则

这体现了 Spring Boot 一贯的设计哲学：自动配置兜底，开发者优先。

四、缓存自动配置：RedisCacheConfiguration

当需要在 Spring Boot 中使用 Redis 作为缓存时，RedisCacheConfiguration 负责自动创建 RedisCacheManager。

@Configuration(proxyBeanMethods = false)@ConditionalOnClass(RedisConnectionFactory.class)@AutoConfigureAfter(RedisAutoConfiguration.class)    // 在 RedisAutoConfiguration 之后执行@ConditionalOnBean(RedisConnectionFactory.class)     // 必须存在 RedisConnectionFactory@ConditionalOnMissingBean(CacheManager.class)        // 用户未自定义 CacheManager@Conditional(CacheCondition.class)                   // 通用缓存条件（需 @EnableCaching）public class RedisCacheConfiguration {    @Bean    public RedisCacheManager cacheManager(            RedisConnectionFactory redisConnectionFactory,            ResourceLoader resourceLoader) {        RedisCacheManagerBuilder builder = RedisCacheManager            .builder(redisConnectionFactory)            .cacheDefaults(determineConfiguration(resourceLoader.getClassLoader()));        // 如果配置了 spring.cache.cache-names，则预创建这些缓存实例        List<String> cacheNames = cacheProperties.getCacheNames();        if (!cacheNames.isEmpty()) {            builder.initialCacheNames(new LinkedHashSet<>(cacheNames));        }        return builder.build();    }}

4.1 与其他 CacheManager 的优先级

Spring Boot 的缓存自动配置中，RedisCacheConfiguration 的加载顺序优先于 SimpleCacheConfiguration。因此只要 classpath 中存在 RedisConnectionFactory 且用户未自定义 CacheManager，Redis 缓存管理器会优先被选中。

4.2 RedisCacheManager 内部结构

RedisCacheManager 管理着多个 RedisCache 实例：

public class RedisCacheManager extends AbstractTransactionSupportingCacheManager {    // 预定义的缓存名称 → 缓存配置映射    private final Map<String, RedisCacheConfiguration> initialCacheConfiguration;    @Override    protected Collection<RedisCache> loadCaches() {        // 遍历 initialCacheConfiguration，为每个名称创建 RedisCache[reference:26]        for (Map.Entry<String, RedisCacheConfiguration> entry :                 initialCacheConfiguration.entrySet()) {            caches.add(createRedisCache(entry.getKey(), entry.getValue()));        }        return caches;    }}

4.3 RedisCache 的读写操作

RedisCache 是真正执行缓存读写操作的组件：

查找（lookup）：将 key 序列化后从 Redis 读取，再反序列化 value
写入（put）：将 key 和 value 序列化后写入 Redis，并设置 TTL
过期控制：通过 RedisCacheConfiguration 中的 entryTtl 控制缓存过期时间

五、完整自动配置流程图

六、Spring Boot 3.x 的重要变化

对比维度	Spring Boot 2.x	Spring Boot 3.x
自动配置注册	`META-INF/spring.factories`（键值对格式）	`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`（每行一个类名）
Jakarta EE 迁移	使用 `javax.*` 包	迁移到 `jakarta.*` 包
连接细节抽象	无	引入 `RedisConnectionDetails` 接口，解耦自动配置与连接属性
配置路径更严格	宽松	任何配置路径、属性名的偏差都会导致初始化中断

升级提醒：Spring Boot 3.x 已完全弃用 spring.factories，旧项目升级后若残留该文件，会导致所有自动配置静默失效。

七、总结

Spring Boot Redis 自动配置的源码架构可以归纳为三层：

层级	核心类	职责
入口层	`RedisAutoConfiguration`	条件检查、属性绑定、导入连接配置
连接层	`LettuceConnectionConfiguration` / `JedisConnectionConfiguration`	根据 classpath 和配置选择并创建 Redis 连接工厂
操作层	`RedisTemplate` / `StringRedisTemplate`	提供 Redis 操作 API（序列化 + 连接管理）
缓存层	`RedisCacheConfiguration` → `RedisCacheManager` → `RedisCache`	将 Redis 作为 Spring Cache 抽象的实现

核心设计思想：

条件装配：通过 @ConditionalOnClass 和 @ConditionalOnProperty 实现灵活的按需加载
默认优先：Lettuce 通过 matchIfMissing=true 成为默认客户端，用户无需任何配置即可使用
开发者优先：@ConditionalOnMissingBean 确保用户自定义 Bean 始终优先于自动配置
SPI 机制：通过 AutoConfiguration.imports 文件实现自动配置类的服务发现