Spring Boot 自定义 RedisTemplate 泛型不匹配踩坑记录

开发中使用 Redis 时，自定义 RedisStringTemplate 工具类依赖 RedisTemplate 注入，遇到一个诡异问题：给 RedisStringTemplate 加 @Component 注解就启动报错，提示找不到 RedisTemplate 类型的 Bean；注释 @Component 后，项目反而能正常启动，RedisTemplate 也能被 Spring 自动创建。排查后发现，核心问题出在 RedisTemplate 的泛型匹配 上，特此记录踩坑过程与解决方案。

一、踩坑现象

1. 自定义 RedisStringTemplate 中注入 RedisTemplate<String, Object>，添加 @Component 后，启动报错：Field redisTemplate in ...RedisStringTemplate required a bean of type 'org.springframework.data.redis.core.RedisTemplate' that could not be found.

2. 注释 @Component 后，项目启动正常，通过 Actuator 查看 Bean，发现 Spring 已自动创建 RedisTemplate，但无法注入到自定义工具类中。

二、问题根源：泛型不匹配

核心原因的是：Spring Boot 官方自动配置的 RedisTemplate，泛型为 RedisTemplate<Object, Object>，而我在自定义工具类中注入的是 RedisTemplate<String, Object>，泛型不匹配导致 Spring 无法完成注入。

查看 Spring 官方源码可知，默认自动配置的 RedisTemplate 如下：

@Bean
@ConditionalOnMissingBean(name = "redisTemplate")
public RedisTemplate<Object, Object> redisTemplate(RedisConnectionFactory factory) {
    RedisTemplate<Object, Object&gt; template = new RedisTemplate<>();
    template.setConnectionFactory(factory);
    return template;
}

当给 RedisStringTemplate 加 @Component 时，Spring 尝试注入 RedisTemplate<String, Object>，但容器中只有 RedisTemplate<Object, Object>，类型不匹配导致注入失败，进而启动报错；注释 @Component 后，不触发注入逻辑，自然不会报错。

三、解决方案（3种实用方案）

方案1：修改注入泛型（最简单、推荐）

将自定义工具类中注入的 RedisTemplate 泛型，改为与官方一致的 RedisTemplate<Object, Object>，Key 仍可正常传入 String 类型（泛型不影响实际使用），同时结合 @ConditionalOnBean 避免无 Redis 时报错。

@Slf4j
@Component
@ConditionalOnBean(name = "redisTemplate") // 有redisTemplate才创建
@RequiredArgsConstructor
public class RedisStringTemplate {
    // 改为与官方一致的泛型
    private final RedisTemplate<Object, Object> redisTemplate;
    // 其他依赖...
    
    // 方法使用不受影响，Key传入String即可
    public boolean set(String key, Object value) {
        redisTemplate.opsForValue().set(key, value);
        return true;
    }
}

方案2：自定义符合泛型的 RedisTemplate

自己配置 RedisTemplate<String, Object>，并添加 @Primary 注解优先使用自定义版本，同时结合 @ConditionalOnProperty 控制只有配置 Redis 才加载，兼顾序列化增强。

方案3：按名称注入（不推荐，临时可用）

使用 @Resource 按 Bean 名称注入，忽略泛型匹配，适合临时调试，生产环境不推荐（泛型校验失效，存在隐患）。

四、踩坑总结

1. 注入 Spring 自动配置的 Bean 时，需注意泛型一致性，尤其是 RedisTemplate、RestTemplate 这类带泛型的组件。

2. 自定义工具类依赖容器 Bean 时，建议添加 @ConditionalOnBean 注解，避免无依赖 Bean 时启动报错。

3. 遇到 Bean 注入失败，优先排查：泛型匹配、Bean 名称、Bean 是否被正确创建（可通过 Actuator 查看 Bean 列表，http://localhost:8080/actuator/beans）。

看似诡异的启动报错，本质是基础的泛型匹配问题，开发中多关注细节，可避免此类低级踩坑。