给查询方法加上 @Cacheable,连续点两次接口,SQL 日志却照打不误。先别急着改 Redis 的过期时间,缓存可能压根没走到。

排查时先固定一个条件:同一个应用实例、同一个入口、同一组参数,串行调用两次。只看第二次有没有进入查询方法。数据库连接池日志、HTTP 请求日志还在,并不代表缓存没命中;要看的是目标方法里的查询是否再次执行。

下面按 JDK 17、Spring Boot 3.3.x 与 Spring Framework 6.1 的普通同步方法来讲,使用默认的代理模式。响应式返回值、异步加载和分布式一致性需要另外分析。

先确认缓存开了,以及实际用的是谁

@Cacheable 只是声明。项目还得启用缓存支持,由 CacheManager 提供真正的存储。Spring Boot 项目通常会加入下面的依赖,并在配置类上添加 @EnableCaching;已有 Boot 父 POM 或 BOM 管理版本时,不用给这个 starter 另写版本号。Spring Boot 缓存说明

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-cache</artifactId>
</dependency>

接着看运行中的 CacheManager 类型。别只看项目里有没有 Redis 依赖,也别因为 Redis 客户端能连上,就认定这个方法一定把结果放进了 Redis。Boot 可以根据依赖和配置选择不同实现;如果你自己声明了缓存管理器,就要检查这个 Bean。多个管理器并存时,还要核对注解有没有通过 cacheManager 指向另一个实例。Boot 的缓存实现选择

常见的误会是,本地测试用着 ConcurrentMapCacheManager,却一直打开 Redis 找 key。前者把数据存在当前 JVM 内存里,这样查当然看不到。配置了 spring.cache.type=none 的环境也值得检查,它会使用不实际缓存数据的实现。Boot 的空缓存配置

同一个类里调用,最容易绕过缓存

默认代理模式下,调用要先经过 Spring 创建的代理,缓存拦截器才有机会工作。在一个类的方法里直接调用本类的另一个方法,即使后者写了 @Cacheable,这次调用也不会被缓存拦截。EnableCaching 的代理规则

下面这个例子不连数据库,用计数器表示“真正查询了一次”。在已加入上述 starter 的练习项目里,将它保存为 src/main/java/demo/CacheProbe.java,用 IDE 运行 main。它只启动一个 Spring 容器,方便把调用路径看清楚。

package demo;

import java.util.concurrent.atomic.AtomicInteger;
import org.springframework.cache.CacheManager;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.cache.annotation.CacheEvict;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.cache.concurrent.ConcurrentMapCacheManager;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

public class CacheProbe {
    public static void main(String[] args) {
        try (var ctx = new AnnotationConfigApplicationContext(Config.class)) {
            var service = ctx.getBean(BookService.class);
            var manager = ctx.getBean(CacheManager.class);
            System.out.println("manager=" + manager.getClass().getSimpleName());

            service.find(1L);
            service.find(1L);
            System.out.println("external=" + service.queryCount());

            service.findTwice(1L);
            System.out.println("self=" + service.queryCount());

            service.evict(1L);
            service.find(1L);
            System.out.println("afterEvict=" + service.queryCount());
        }
    }

    @Configuration(proxyBeanMethods = false)
    @EnableCaching
    static class Config {
        @Bean
        CacheManager cacheManager() {
            return new ConcurrentMapCacheManager("books");
        }

        @Bean
        BookService bookService() {
            return new BookService();
        }
    }

    public static class BookService {
        private final AtomicInteger queries = new AtomicInteger();

        @Cacheable(cacheNames = "books", key = "#p0")
        public String find(long id) {
            queries.incrementAndGet();
            return "book-" + id;
        }

        public void findTwice(long id) {
            find(id);
            find(id);
        }

        @CacheEvict(cacheNames = "books", key = "#p0")
        public void evict(long id) {
        }

        public int queryCount() {
            return queries.get();
        }
    }
}

两次外部调用后,external=1。同一个 key 的第二次调用命中了缓存,没有再执行 find 方法体。接着执行 findTwice,两次内部调用都绕过代理,因此累计变成 self=3。最后经代理删除缓存,再查一次,得到 afterEvict=4。

这段计数行为已在本机 JDK 17.0.15、Spring Framework 6.1.14 下运行核对;它验证的是方法拦截和缓存删除,没有连接数据库或 Redis。

放回业务代码,处理办法通常是把缓存查询放到独立的 Bean,由其他 Bean 注入后调用。别在 Controller 里手动 new BookService(),也别把注解加到 private 方法上,期待代理能拦截。使用基于类的代理时,final 方法同样不能被重写拦截。这类调用路径问题与 @Async 不换线程 很像,可以一起对照。

明明存过了,为什么下一次还是 miss

调用路径没问题,就把缓存名称、管理器、key 和条件一起对照。两次请求看起来一样,参与 key 计算的参数未必一样。

默认 key 规则是:无参数使用空 key,一个参数直接使用该参数,多个参数组合成 SimpleKey。如果参数里夹着时间戳、随机请求号,或对象的相等性不是按业务字段判断,就可能每次都查到不同位置。可以显式使用 key="#p0" 取第一个参数;按索引访问不依赖编译时是否保留参数名。Spring 缓存的 key 生成规则

但 key 也不能随便省。查询结果受租户影响时,只放商品 ID 会把不同租户的数据混在一起;价格还受币种影响时,也应考虑币种。先列出“哪些输入会改变结果”,再决定 key 包含什么。

还有两个容易漏看的属性:condition 在调用前判断是否参与缓存,unless 根据调用结果决定是否不写入。比如 unless="#result == null" 会让未查到数据的请求继续查询。先核对条件是否符合预期,再判断是不是缓存故障。Cacheable 条件与结果判断

删除缓存也要使用相同的名称和 key。举个例子,查询方法只有 find(id),更新方法却是 update(id, request),两边都使用默认 key,更新后删除的就是另一个位置。上面的示例在查询和删除处都写 key="#p0",就是为了把这个约定写清楚。CacheEvict 的 key 规则

如果只在并发时出现重复查询,还要区分“缓存失效”和“多次请求同时遇到冷缓存”。普通 @Cacheable 并不默认把并发加载串行化;sync=true 需要底层实现支持,也不能当作跨应用实例的分布式锁。Cacheable 的同步加载限制

用一次可控复测,把原因收拢

在本机或测试环境,可以临时打开缓存拦截器的 TRACE 日志,观察命中的缓存名、key,以及是否真正进入查询方法。下面是 application.properties 写法,查完恢复原级别,业务参数可能出现在日志里。

logging.level.org.springframework.cache.interceptor=TRACE

把观察到的现象与下面几项对上,比一遍遍清空 Redis 更容易定位。

现象接下来查什么
同实例、同参数,串行两次都进方法启用配置、Bean 来源、代理调用路径、condition 与 unless
本地调用命中,业务入口却不命中业务入口是否手动创建对象,或发生了同类内部调用
当前进程命中,另一个实例仍然查询管理器是否只使用 JVM 本地缓存,是否连接同一共享存储
更新后还读到旧值查询与删除的缓存名、key、管理器及事务提交时序
过一会儿才再次查询缓存实现的 TTL、容量淘汰,以及是否有主动删除

本地 ConcurrentMapCacheManager 适合这个演示,但它不提供 TTL 或容量淘汰策略,别把它当成生产缓存配置。ConcurrentMapCacheManager 的适用范围

最后按原业务入口复测:同参数查两次,更新后再查一次;有多实例时再跨实例查一次。记录真正执行查询的次数,同时确认返回的是新数据。缓存命中了但结果串了,比多查一次数据库更麻烦。

更多运行与调用问题,可以从 Java 后端排障专题 继续查。