Spring Boot中@Cacheable注解缓存未生效排查解决方案

文
章
目
录

• 一、缓存管理器配置问题
• （一）未定义CacheManager Bean
• （二）@Cacheable未正确指定缓存管理器
• 二、未启用缓存支持
• 三、缓存名称不匹配问题
• 四、Redis或其他缓存组件配置错误
• （一）检查Redis配置
• （二）确保Redis服务器正常运行
• （三）配置正确的序列化方式
• 五、方法参数或返回值问题
• （一）检查参数对象
• （二）调整缓存条件
• 六、条件过滤（condition/unless）问题
• 七、类内部方法调用问题
• 八、多缓存管理器冲突
• 九、缓存过期或未命中
• 十、日志调试
• 十一、总结排查步骤

Spring Boot中可以使用@Cacheable注解来实现缓存功能提升系统性能，但有时候会遇到一个让人头疼的问题：明明加了注解，查询时缓存却没有生效。这到底是怎么回事呢？别着急，下面我就带着大家一起逐步排查可能的原因，并给出对应的解决方案。

一、缓存管理器配置问题

在Spring Boot中，缓存管理器是缓存功能的核心配置部分。如果没有正确配置它，@Cacheable注解很可能无法正常工作。

（一）未定义CacheManager Bean

有时候，我们可能会忘记在配置类中定义CacheManager Bean。这就好比盖房子没有打好地基，后续的缓存功能自然无法正常运转。解决方法很简单，在配置类中添加如下代码：

@Bean
public CacheManager myCacheManager() {
    return new ConcurrentMapCacheManager(\"myCache\");
}

这段代码定义了一个名为myCacheManager的CacheManager Bean，使用ConcurrentMapCacheManager来管理缓存，并且指定了缓存名称为myCache。

（二）@Cacheable未正确指定缓存管理器

仅仅定义了CacheManager Bean还不够，在使用@Cacheable注解时，还需要正确指定缓存管理器的名称。比如这样：

@Cacheable(value = \"myCache\", cacheManager = \"myCacheManager\")

这里通过cacheManager属性指定了使用myCacheManager这个缓存管理器，同时通过value指定了具体的缓存名称为myCache，确保两者名称对应正确。

二、未启用缓存支持

在Spring Boot项目中，缓存功能不是默认开启的，需要我们手动启用。如果主启动类或配置类中缺少@EnableCaching注解，就相当于没有打开缓存功能的开关。解决办法就是在主类上添加这个注解：

@SpringBootApplication
@EnableCaching // 确保启用缓存
public class Application { 
  // 主类的其他代码
}

加上@EnableCaching注解后，Spring Boot就会开始扫描并启用缓存相关的功能。

三、缓存名称不匹配问题

@Cacheable注解中指定的缓存名称（通过value或cacheNames属性），必须与缓存管理器中定义的名称一致，否则缓存无法生效。这就像你要去某个房间拿东西，结果房间号都记错了，肯定拿不到。所以，一定要仔细检查缓存管理器配置的缓存名称和@Cacheable注解中的名称是否一致。

四、Redis或其他缓存组件配置错误

如果项目中使用了Redis等外部缓存组件，那么它们的配置正确与否至关重要。哪怕是一个小的配置失误，都可能导致缓存失效。

（一）检查Redis配置

在application.properties文件中，要确保Redis的配置正确。常见的配置如下：

spring.cache.type=redis
spring.redis.host=localhost
spring.redis.port=6379

这里指定了缓存类型为Redis，并且配置了Redis服务器的主机地址和端口号。需要注意的是，要根据实际情况修改主机地址和端口号，如果Redis服务器在其他机器上，就不能写localhost了。

（二）确保Redis服务器正常运行

配置正确还不够，Redis服务器本身也必须正常运行。可以通过命令行工具或者相关的监控工具检查Redis是否启动成功，端口是否正常监听。

（三）配置正确的序列化方式

有时候，缓存中的数据需要进行序列化和反序列化操作。如果序列化方式配置错误，也会导致缓存出现问题。比如，可以使用Jackson2JsonRedisSerializer来配置序列化方式，具体配置方法根据项目实际情况而定。

五、方法参数或返回值问题

缓存键的生成依赖于方法的参数，如果参数对象没有正确实现hashCode()和equals()方法，就可能导致缓存键生成异常，从而影响缓存效果。另外，如果方法返回值为null，默认情况下是不会被缓存的。

（一）检查参数对象

要确保参数对象支持正确的键生成。如果参数是自定义的对象，就需要检查这个对象是否正确重写了hashCode()和equals()方法。

（二）调整缓存条件

如果希望缓存null值，可以使用unless属性来调整缓存条件。例如：

@Cacheable(value=\"myCache\", unless=\"#result == null\")

这样设置后，即使方法返回值为null，也会被缓存起来。

六、条件过滤（condition/unless）问题

@Cacheable注解中的condition或unless表达式用于控制缓存的条件，如果这些表达式的逻辑有误，就可能导致缓存被跳过。所以，要仔细检查这些条件表达式，确保它们的逻辑符合项目的实际需求。

七、类内部方法调用问题

在同一个类中，如果通过内部方法调用被@Cacheable注解修饰的方法，就会绕过AOP代理，导致缓存不生效。这是因为AOP代理是在类的外部创建的，类内部的方法调用不会经过这个代理。解决办法是将被调用的方法移到另一个Bean中，或者通过代理对象来调用。

八、多缓存管理器冲突

如果项目中存在多个CacheManager Bean，但在使用@Cacheable注解时没有明确指定使用哪一个，就可能出现缓存管理器冲突的问题。解决方法很简单，在@Cacheable注解中通过cacheManager属性明确指定要使用的缓存管理器。

九、缓存过期或未命中

有时候，缓存没有生效可能是因为缓存已经过期，或者在查询时没有命中缓存。可以检查缓存的TTL（Time To Live，存活时间）设置，看看缓存是否因为过期而失效。另外，通过日志来验证缓存的操作细节，也能帮助我们找到问题所在。

十、日志调试

启用缓存日志是一个很好的排查问题的方法。在application.properties文件中添加如下日志配置：

logging.level.org.springframework.cache=DEBUG

启用日志后，在项目运行过程中，就可以通过日志观察缓存的相关行为，比如缓存的读取、写入、删除等操作，从而更方便地定位问题。

十一、总结排查步骤

为了方便大家记忆和操作，这里总结一下排查缓存未生效问题的主要步骤：

1. 确认@EnableCaching注解已经添加到主启动类或配置类中，启用了缓存支持。
2. 检查CacheManager Bean的配置是否正确，并且确认其名称与@Cacheable注解中指定的cacheManager名称一致。
3. 确保@Cacheable注解中的value或cacheNames属性指定的缓存名称，与缓存管理器中定义的名称匹配。
4. 验证缓存组件（如Redis）的连接和配置是否正确，包括服务器是否正常运行、序列化方式是否正确等。
5. 检查方法的参数和返回值是否符合缓存条件，比如参数对象是否正确实现了相关方法，是否需要调整缓存条件以支持null值等。
6. 通过日志分析缓存操作的细节，查看是否有异常情况出现。

通过按照以上步骤逐步排查，通常都能找到并解决Spring Boot中@Cacheable注解缓存未生效的问题。希望这篇文章能帮助大家在项目开发中更好地使用缓存功能，至少有一个排查的方向