接手过不少 Spring Boot 服务我发现在缓存这件事上团队里最容易出现两种极端一种是完全不用注解RedisTemplate的get/set到处飞一个业务方法里先查缓存再查数据库然后把结果写回缓存改个 key 策略要动十几处代码另一种是注解确实用了但Cacheable加完就不管了TTL 不配、key 不设计、序列化出问题也不知道线上缓存穿透把数据库打挂了才回头排查。Spring Boot 中的 Cache 缓存本质上是帮你把“查缓存、回源、写缓存”这套固定流程抽成声明式注解。这篇文章从一个真实业务视角出发覆盖从注解用法、缓存抽象原理、key 设计、CacheManager 切换到 Redis 序列化、缓存一致性、穿透击穿雪崩等线上排障经验。适合刚接触 Spring Boot 缓存的开发者也适合已经用过注解但没深入思考过原理的同学照着操作一次基本能把 Spring Cache 这块的地基打牢。1. Spring Cache 解决的是哪一类“写重复代码”的问题1.1 一段典型的手写缓存代码看得让人头大假设你在做一个用户查询接口没有抽象层之前代码通常是这样的public UserDTO getUserById(String userId) { String key user: userId; Object cached redisTemplate.opsForValue().get(key); if (cached ! null) { return (UserDTO) cached; } UserDTO user userMapper.selectById(userId); if (user ! null) { redisTemplate.opsForValue().set(key, user, 30, TimeUnit.MINUTES); } return user; }而且这还算写得规整的至少知道先查缓存。再往后你会发现问题越来越多每个查询接口都有一段几乎一模一样的“查缓存-回源数据库-写缓存”三段式代码团队里每个人写的 redis key 风格还不一样有的用冒号拼接有的用.拼接。用户一更新删缓存的逻辑散落在各个 service 里经常漏掉一处导致用户改了资料界面还是旧数据。缓存中间件今天用 Redis明天想换成本地 Caffeine接口层一个没动Service 层所有方法全部重写。缓存存放的对象类型一旦变更(UserDTO) cached强转这里就会埋雷运行到一半报ClassCastException。我在项目里看到这类代码的第一反应是业务复杂度还没上来缓存代码的复杂度已经喧宾夺主了。Spring Cache 的出现就是要消除这些重复工作把缓存读写和业务方法解耦让开发者只需要告诉框架“这个方法的结果需要缓存”和“这个方法的执行会导致哪些缓存失效”剩下的事交给框架。1.2 CacheManager、Cache、CacheInterceptor 三层抽象各管一段Spring Cache 不是一个缓存中间件它是一层标准抽象。具体落到代码里这三层各司其职CacheManager缓存管理器负责创建、管理和获取各种 Cache。一个 Spring 容器里可以注册多个 CacheManager比如一个 RedisCacheManager 管分布式缓存一个 CaffeineCacheManager 管本地热点缓存。Cache真正和中间件打交道的对象定义了 get、put、evict、clear 等操作相当于把 Redis 的 set/get/delete 包了一层统一接口。CacheInterceptorAOP 拦截器代理所有标注了缓存注解的 Bean 方法负责解析注解参数、生成 key、调用 Cache 接口并在方法执行异常时决定是否回滚缓存操作。我再打个比方CacheManager 像快递总站Cache 是里面一个个货架而 CacheInterceptor 是分拣员。快递总站管理货架列表分拣员接到订单后去对应货架的格子查货、放货、清货业务代码本身不用关心货架堆在哪里。这里要强调一点Spring Cache 的注解默认拦截粒度是 public 方法而且必须通过 Spring 代理对象调用自己在类内部用this调用是绕过了代理的注解不会生效。这个坑放在后面专门展开。2. 四个核心注解的实操从 EnableCaching 到 CacheEvict2.1 EnableCaching开关的作用比你想的更基础Spring Boot 项目里启用缓存注解第一步就是在配置类上加上EnableCachingConfiguration EnableCaching public class CacheConfig { }这个注解本身很简单但它背后做了一件事向容器注册一个CacheInterceptor的 Advisor让 Spring AOP 能识别Cacheable、CachePut、CacheEvict这些注解。也就是说不加它下面所有注解都会被当成普通注解忽略方法该执行照常执行只是没有缓存效果。同时要注意即使加了EnableCaching如果没有手动配置 CacheManagerSpring Boot 会自动装配一个ConcurrentMapCacheManager也就是基于ConcurrentHashMap的本地缓存。这个缓存适合开发环境验证但不适合生产原因后面会讲。2.2 Cacheable查询接口的正确打开方式Cacheable是使用频率最高的注解语义是方法执行前先查缓存缓存命中直接返回缓存结果不执行方法体缓存未命中则执行方法方法返回后自动把结果写进缓存。Cacheable(cacheNames user, key #userId) public UserDTO getUserById(String userId) { return userMapper.selectById(userId); }注意几个点cacheNames相当于命名空间同一个缓存名下的 key 是隔离的。key用 Spring Expression LanguageSpEL表达式#userId表示取方法参数列表里的userId后面会单独讲。方法返回值会被序列化后存入缓存所以谨慎起见缓存对象建议是纯 DTO不要直接把 ORM 实体丢进去避免出现多层关联对象序列化循环等问题。还有一个容易被忽略的参数sync true。它表示当缓存未命中时多个线程同时打到这个方法只有一个线程去执行目标方法其他线程等待结果。这在单机环境下能有效缓解缓存击穿但这是 JVM 级别的同步多实例部署时还是要靠分布式锁兜底。2.3 CachePut 和 CacheEvict写操作怎么保持缓存干净缓存设计中更新和删除往往比查询更考验功底。CachePut的语义是方法一定会执行执行完之后把返回值写进缓存。适合“更新后刷新缓存”的场景CachePut(cacheNames user, key #userDTO.userId) public UserDTO updateUser(UserDTO userDTO) { userMapper.updateById(userDTO); return userDTO; }CacheEvict的语义是方法执行后或执行前删除一个或多个缓存条目。适合“删除数据后清缓存”的场景CacheEvict(cacheNames user, key #userId) public void deleteUser(String userId) { userMapper.deleteById(userId); }这里要记住三个配套参数allEntries true清空整个 cacheNames 下的所有缓存条目。适合该维度下 key 不可枚举、或一次操作影响全部数据的情况代价是瞬时缓存全失效。beforeInvocation true在方法调用前清缓存。如果方法有报错风险但缓存又必须清理这个参数就有用了默认是在方法成功返回后才清缓存方法抛异常时缓存不会被清理。condition执行清理前先判断条件不满足则不清理。我在实际项目中有一个体会更新业务时更推荐“先写库再删缓存”的CacheEvict方案而不是CachePut。因为CachePut写进缓存的数据和数据库里的最终数据可能在并发窗口内不一致而且如果方法返回对象比实际落库数据少几个字段缓存里存的就是残缺数据。删缓存成本低最多下次查询回源一次。2.4 Caching 和 CacheConfig组合注解与类级别默认值业务方法往往不是单向操作。比如订单支付成功后订单详情缓存要更新用户订单列表缓存要清理这时候就需要组合注解Caching( put CachePut(cacheNames order, key #result.orderId), evict { CacheEvict(cacheNames orderList, allEntries true), CacheEvict(cacheNames userOrder, key #userId) } ) public OrderDTO payOrder(String userId, String orderId) { // 支付逻辑 }组合注解容易出现 key 写错导致缓存不更新的问题我的建议是如果一个方法里涉及多个缓存维度的变更先用工具类把 key 统一拼接好再写注解不要用三四个不同的 key 风格。CacheConfig是类级别的公共配置可以把cacheNames提到类上减少重复Service CacheConfig(cacheNames user) public class UserServiceImpl { Cacheable(key #userId) public UserDTO getUser(String userId) { ... } CacheEvict(key #userId) public void deleteUser(String userId) { ... } }但要注意CacheConfig定义的cacheNames优先级低于注解上的cacheNames这算是一个常见的预期偏差。3. 缓存 Key 生成与 SpEL 表达式数据不串用的根基3.1 默认 KeyGenerator 的行为以及为什么容易踩坑如果Cacheable上不写keySpring 会使用SimpleKeyGenerator生成 key。规则如下方法无参数key 是SimpleKey.EMPTY所有同类调用共用一条缓存。方法有一个参数key 就是参数本身要求参数正确重写了equals和hashCode。方法有多个参数key 是SimpleKey对象内部包裹了参数数组同样依赖参数的 equals。这个默认方案看起来省事实际上隐患不小。如果你方法的参数是一个可变的 Map 或者一个缺少 equals 的实体对象key 的稳定性就无法保证另外 key 的生成受参数数量、类型、顺序影响签名一变缓存就读不到了。我在一个老项目里遇到过同一个查询方法入参从String userId改成UserQuery query结果当天缓存命中率骤降因为 key 从字符串变成了对象类型对不上。所以我的建议是生产环境一定显式声明key。哪怕是只有一个参数也建议写成key #userId让 key 的意图体现在代码里而不是依赖框架猜。3.2 key 的演化从字符串拼接走到统一规则早期团队里常见的写法是Cacheable(cacheNames user, key user: #userId) public UserDTO getUser(String userId) { ... }这种写法的问题是开发者各自定义前缀userService里写user:orderService里写order:维护成本很高而且 cacheNames 本身已经起到前缀作用key 里再加业务前缀是重复的。后来项目里统一成了一种做法cacheNames 作为业务域前缀key 只表达业务维度。比如订单详情Cacheable(cacheNames order:detail, key #orderId) public OrderDTO getOrderDetail(String orderId) { ... } CacheEvict(cacheNames order:detail, key #orderId) public void cancelOrder(String orderId) { ... }组合维度可以用 SpEL 拼接例如用户维度下查角色列表Cacheable(cacheNames user:role, key #userId : #appId) public ListRoleDTO listUserRoles(String userId, String appId) { ... }用冒号分隔业务维度最终落到 Redis 里的完整 key 就是user:role::userId:appId可读性很强出问题也好在 Redis 客户端里手动排查。3.3 condition 与 unless两个条件注解判断时机完全不同很多新手容易把condition和unless当同一个东西用但其实它们作用的阶段不一样。condition在方法执行前判断基于入参决定“要不要走缓存逻辑”。如果条件为 false缓存读写都不参与相当于这个注解不生效。unless在方法执行后判断基于返回值决定“要不要写入缓存”。它不管读缓存只决定写不写。一个典型的场景根据商品 ID 查询详情只有库存大于 100 的商品才缓存因为热销商品查询频率高冷门商品没必要缓存。Cacheable(cacheNames product, key #productId, condition #stock 100, unless #result.stock 10) public ProductDTO getProductDetail(String productId, int stock) { ... }执行流程是先判断 stock 是否大于 100不满足直接查库不入缓存满足后查缓存未命中就执行方法方法返回后再看result.stock是否小于 10小于 10 则不写缓存。这种双条件配合适合“大促商品缓存”这类业务。4. 从本地缓存到 RedisCacheManager 切换与序列化排雷4.1 默认 ConcurrentMapCacheManager 为什么只能用于开发如果不做任何配置Spring Boot 自动配置的ConcurrentMapCacheManager会把缓存存在 JVM 堆内的 ConcurrentHashMap 中。它有三个致命问题多实例不共享。假设服务部署了三个节点同一个 key 的查询请求打到不同节点每个节点各持一份缓存命中率被平摊数据也可能不一致。重启即失效。发布时缓存清空启动瞬间所有请求直接打到数据库这就是典型的缓存雪崩场景。不可控。没有过期时间、没有容量上限、没有淘汰策略内存只增不减迟早出问题。我在一个小型内部系统里见过用本地缓存跑了一年的项目最后缓存了上百万数据又没人清理接口响应越来越慢GC 越来越频繁。所以生产级项目即使单节点也建议上 Caffeine多节点则直接考虑 Redis。4.2 引入 Caffeine高性能本地缓存的配置方式Caffeine 是目前 Java 生态里性能最好的本地缓存库Spring Boot 也内置了支持。引入依赖后配置一个CaffeineCacheManagerdependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-cache/artifactId /dependency dependency groupIdcom.github.ben-manes.caffeine/groupId artifactIdcaffeine/artifactId /dependency然后注册 CacheManagerBean public CacheManager caffeineCacheManager() { CaffeineCacheManager manager new CaffeineCacheManager(); manager.setCaffeine(Caffeine.newBuilder() .maximumSize(10_000) .expireAfterWrite(Duration.ofMinutes(30)) .recordStats()); manager.setAllowNullValues(false); return manager; }这里有几个实践要点maximumSize必须设置否则缓存不受控无限增长。expireAfterWrite适合读多写少且允许短暂不一致的场景如果是需要基于访问时间刷新的场景可以用expireAfterAccess。需要统计命中率时开启recordStats()配合 actuator 查看 Cache 指标。一个容易被忽略的问题是Caffeine 的refreshAfterWrite并不会自动更新缓存内容它只会在访问某个过期条目时触发异步加载需要显式传入一个 CacheLoader。如果没有 loaderrefreshAfterWrite相当于失效这一点官方文档写得比较含蓄实际调试时容易一头雾水。4.3 切到 RedisCacheManager 配置、TTL 与序列化多数 Web 服务最终都会落到 Redis。引入依赖后关键是配置RedisCacheManager而不是直接用 Spring Boot 的默认装配。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependency配置类代码如下Bean public RedisCacheManager redisCacheManager(RedisConnectionFactory factory) { ObjectMapper om new ObjectMapper(); om.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.ANY); om.activateDefaultTyping(LaissezFaireSubTypeValidator.instance, ObjectMapper.DefaultTyping.NON_FINAL, JsonTypeInfo.As.PROPERTY); om.findAndRegisterModules(); // 处理 LocalDateTime 等 Java 8 时间类型 GenericJackson2JsonRedisSerializer serializer new GenericJackson2JsonRedisSerializer(om); RedisCacheConfiguration config RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofMinutes(30)) .serializeValuesWith( RedisSerializationContext.SerializationPair.fromSerializer(serializer)) .computePrefixWith(name - name ::); return RedisCacheManager.builder(factory) .cacheDefaults(config) .withInitialCacheConfigurations(customTtlMap()) .build(); }序列化是这里最容易出问题的地方。很多项目直接使用JdkSerializationRedisSerializer缓存里存的是一大段二进制Redis 客户端里没法直接查看开发排查很不方便。我建议统一用GenericJackson2JsonRedisSerializer让缓存内容以 JSON 形式存储可读性高也让 Java 端和未来可能的非 Java 调用方都能理解数据。TTL 方面我习惯按缓存维度区分用户基础信息 30 分钟商品详情 10 分钟配置类数据 1 小时。不同 cacheNames 配不同 TTL方法是使用withInitialCacheConfigurationsprivate MapString, RedisCacheConfiguration customTtlMap() { MapString, RedisCacheConfiguration map new HashMap(); map.put(user, RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofMinutes(60)) .serializeValuesWith(...重复上面的序列化配置...)); map.put(product, RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofMinutes(10)) .serializeValuesWith(...)); return map; }4.4 本地缓存和 Redis 缓存并存类级别和注解级别的 CacheManager 选择如果项目同时注册了 Caffeine 和 Redis 两个 CacheManager默认注入时容易报错。解决办法是指定一个为主缓存管理器其他通过注解参数显式指定。我推荐把 Redis 作为默认 CacheManager高频且允许短期不一致的热点数据单独用 Caffeine 管理。使用方式Cacheable(cacheNames hot:rank, cacheManager caffeineCacheManager) public ListRankItem getHotRank() { ... } Cacheable(cacheNames order:detail, cacheManager redisCacheManager) public OrderDTO getOrderDetail(String orderId) { ... }这样做的好处是热点排行这类数据对一致性要求低、访问频率高放在本地内存里性能最好订单详情这种需要多个节点共享、并且希望客户端查 Redis 也能看到数据的放进 Redis 更合理。5. 踩坑实录注解不生效、缓存不更新、穿透击穿雪崩5.1 同一个类内部调用时为什么缓存注解“看不见”这是 Spring Cache 最常见、也最让人摸不着头脑的问题。看代码Service public class UserServiceImpl { Cacheable(cacheNames user, key #userId) public UserDTO getUser(String userId) { ... } public UserDTO getUserWithDetail(String userId) { UserDTO user this.getUser(userId); // 注解不生效 user.setExtra(...); return user; } }getUserWithDetail通过this.getUser()调用了同类方法this是原始对象而不是 Spring 生成的代理对象所以Cacheable的拦截器根本没有执行每次调用都会直接回源数据库。解决办法有几种把需要缓存的方法拆到一个单独的 Service Bean 里然后注入这个 Bean 调用。这是最清晰、最可控的方案。注入自身的代理引用例如Autowired private UserServiceImpl self;然后调用self.getUser()。开启exposeProxy后使用AopContext.currentProxy()但这种方式侵入性强我不太推荐。我在代码评审时看到过一种隐蔽的写法把Cacheable加在 private 方法上。这个必须避免Spring AOP 只能增强 public 方法的调用过程private 方法根本不经过代理。5.2 缓存不更新CachePut 的 key 和 Cacheable 对不上另一个高发问题是查询方法用#userId做 key更新方法的入参里没有userId结果缓存写入时 key 计算失败或者写进了一个完全不同的 key。举个例子Cacheable(cacheNames user, key #userId) public UserDTO getUser(String userId) { ... } CachePut(cacheNames user, key #userDTO.userId) public UserDTO updateUser(UserDTO userDTO) { ... }查询时的 key 是userId字符串更新时如果userDTO.userId为 null框架会抛IllegalArgumentException而且抛出的时机在方法成功执行之后导致数据库更新成功但缓存没写对。做法上我建议更新方法的入参里强制带上业务主键如果拿不到主键就通过上下文工具类获取当前登录用户 ID拼接 key。总之一个业务维度的 key 必须在所有操作里保持一致这是缓存数据不串味的前提。还有一种冷门但真实的坑返回对象是一个接口或者抽象类序列化后反序列化时丢失字段。Spring Cache 默认的SimpleKeyGenerator在生成 key 时也依赖参数的 hashCode/equals如果参数是一个带了枚举、内部类、代理对象的实体equals 计算结果不稳定缓存命中率会变得毫无规律。5.3 序列化失败与类型转换失败的典型表现Redis 缓存模式下缓存读不出来或者读出来不对主要集中在序列化配置上。我列了最常见的三种现象现象原因解法反序列化时报ClassCastException缓存里存的是 LinkedHashMap代码强转成 DTO 类型使用 GenericJackson2JsonRedisSerializer 并激活 DefaultTypingDTO 必须有默认构造和 getter/setterLocalDateTime 反序列化报错Jackson 没有注册日期时间模块在 ObjectMapper 上调用findAndRegisterModules()Redis 里看到一长串二进制使用了 JdkSerializationRedisSerializer改为 JSON 序列化便于排查在代码设计上缓存对象建议单独定义。不要直接把大量字段的数据库实体丢进缓存字段多了序列化时间长也更容易出现版本兼容问题。最好是定义只包含必要字段的 DTO字段类型尽量用基本类型和常用 JDK 类型避免自定义嵌套对象引起反序列化折腾。5.4 缓存穿透、击穿、雪崩的兜底策略Spring Cache 本身不会自动解决这三个经典问题但它提供了部分工具。缓存穿透查询一个根本不存在的数据每次请求都绕过缓存直接打到数据库。防御策略有两个方向一是参数合法性校验非法 ID 直接返回二是把空结果也缓存起来Spring Cache 默认allowNullValues是 true即方法返回 null 时也会写缓存这样可以挡住大量恶意请求。缓存击穿一个热点 key 失效瞬间大量请求同时击到数据库。单机环境下Cacheable(sync true)可以保证同一 JVM 内只有一个线程去回源。多实例部署时可以在回源方法里用 Redisson 等分布式锁做双检锁。缓存雪崩大量 key 在同一时间过期数据库瞬时被打爆。核心对策是给 TTL 加随机扰动不让一批 key 整整齐齐地同时失效。这里必须说清楚sync true解决的是单个 key 的并发回源而雪崩解决的是“很多 key 同时过期”的问题两者不要混淆。5.5 事务提交与缓存更新顺序问题在 Spring Cache 和Transactional混用的场景里有一个顺序问题经常被忽略事务还没有提交缓存已经被更新了。比如Transactional CacheEvict(cacheNames user, key #userId) public void updateUser(String userId) { userMapper.updateById(userId); // 如果事务回滚缓存已经被清掉了数据库还是旧值下次查询又会回源 }如果事务回滚了缓存清理动作不会跟着回滚。下一次请求打过来缓存里没有数据于是回源数据库这时数据库还是旧值反而没问题。但反过来的问题是如果是CachePut事务回滚了缓存却被写入了新值缓存里的数据和数据库不一致问题就严重了。更稳妥的方案是在事务提交后再清理缓存Transactional public void updateUser(String userId) { userMapper.updateById(userId); TransactionSynchronizationManager.registerSynchronization( new TransactionSynchronization() { Override public void afterCommit() { cacheEvictUser(userId); // 调用一个 CacheEvict 方法 } }); }顺带说一句CacheEvict默认是在方法执行成功后、退出前执行清理这个时机和事务提交不是一个节点所以涉及事务的写操作务必把缓存清理放到afterCommit里。6. 可观测与验证不要只加注解还要能证明缓存有效6.1 用指标统计看命中率别靠“感觉”我见过很多项目Cacheable加得很勤快但从来没有确认过缓存到底有没有命中。没有指标等于闭着眼开车。Spring Boot Actuator 配合 Cache 指标可以看到每个 CacheManager 下不同 cacheName 的命中次数、未命中次数、加载耗时。首先引入 actuator 依赖注册CacheMetricsRegistrarBean public CacheMetricsRegistrar cacheMetricsRegistrar(CacheManager cacheManager) { return new CacheMetricsRegistrar(cacheManager); }开启指标后通过 actuator 的 metrics 端点查看cache.gets cache.puts cache.evictions cache.gets.success命中率 cache.gets.success / cache.gets。我在监控面板上同时接了这三个指标并设置了告警活跃缓存命中率低于 80% 时就要人工排查 key 设计或者 TTL 配置。真实项目里很多“缓存不生效”的问题最后都是靠命中率骤降这个指标暴露出来的。如果不想引入繁杂的监控体系也可以用 Caffeine 的recordStats()结合本地日志做快速验证。线上压测时观察数据库查询 QPS 和缓存命中数如果 QPS 没有明显下降说明注解可能没生效。6.2 压测与验证的简单做法写完缓存后我自己习惯做一轮“前测后测”第一步确认 Redis 里产生了预期的 key。第二步连续请求同一个 key 两次观察第二次是否走了缓存最简单的方法是看日志里是否打印目标方法。第三步用小流量压测工具打 1000 个请求观察 DB 的 QPS 波动和缓存命中数。这里有一个经验不要只看 controller 层返回成功就认为缓存生效。Spring Cache 的注解不是编译期拦截它是运行期 AOP代理没生效时业务照样能跑只是慢而已。如果你在服务日志里看到目标方法被打印了 N 次而 N 又等于请求次数那基本可以断定代理失效了。6.3 最后分享一个我个人的体会在真实项目中缓存设计的核心难点往往不是注解怎么用而是先想清楚“缓存什么数据、存在哪、怎么失效、失效后有没有兜底”。我把这套问题列在需求评审清单里每次新增缓存接口都过一遍。实际踩过几次线上事故后我越来越认同一个观点缓存是牺牲一致性换取性能的手段所以在方案设计时要能明确回答“脏数据能容忍多久”。顺带一个小技巧我在线上环境会为每个缓存名维护一个配置化的 TTL通过配置中心动态调整。大促前把核心热点的 TTL 调短或加长不用重新发布代码。Spring Cache 的 RedisCacheManager 本身支持覆盖默认配置利用好这一点缓存策略会灵活很多。
接手过不少 Spring Boot 服务我发现在缓存这件事上团队里最容易出现两种极端一种是完全不用注解RedisTemplate的get/set到处飞一个业务方法里先查缓存再查数据库然后把结果写回缓存改个 key 策略要动十几处代码另一种是注解确实用了但Cacheable加完就不管了TTL 不配、key 不设计、序列化出问题也不知道线上缓存穿透把数据库打挂了才回头排查。Spring Boot 中的 Cache 缓存本质上是帮你把“查缓存、回源、写缓存”这套固定流程抽成声明式注解。这篇文章从一个真实业务视角出发覆盖从注解用法、缓存抽象原理、key 设计、CacheManager 切换到 Redis 序列化、缓存一致性、穿透击穿雪崩等线上排障经验。适合刚接触 Spring Boot 缓存的开发者也适合已经用过注解但没深入思考过原理的同学照着操作一次基本能把 Spring Cache 这块的地基打牢。1. Spring Cache 解决的是哪一类“写重复代码”的问题1.1 一段典型的手写缓存代码看得让人头大假设你在做一个用户查询接口没有抽象层之前代码通常是这样的public UserDTO getUserById(String userId) { String key user: userId; Object cached redisTemplate.opsForValue().get(key); if (cached ! null) { return (UserDTO) cached; } UserDTO user userMapper.selectById(userId); if (user ! null) { redisTemplate.opsForValue().set(key, user, 30, TimeUnit.MINUTES); } return user; }而且这还算写得规整的至少知道先查缓存。再往后你会发现问题越来越多每个查询接口都有一段几乎一模一样的“查缓存-回源数据库-写缓存”三段式代码团队里每个人写的 redis key 风格还不一样有的用冒号拼接有的用.拼接。用户一更新删缓存的逻辑散落在各个 service 里经常漏掉一处导致用户改了资料界面还是旧数据。缓存中间件今天用 Redis明天想换成本地 Caffeine接口层一个没动Service 层所有方法全部重写。缓存存放的对象类型一旦变更(UserDTO) cached强转这里就会埋雷运行到一半报ClassCastException。我在项目里看到这类代码的第一反应是业务复杂度还没上来缓存代码的复杂度已经喧宾夺主了。Spring Cache 的出现就是要消除这些重复工作把缓存读写和业务方法解耦让开发者只需要告诉框架“这个方法的结果需要缓存”和“这个方法的执行会导致哪些缓存失效”剩下的事交给框架。1.2 CacheManager、Cache、CacheInterceptor 三层抽象各管一段Spring Cache 不是一个缓存中间件它是一层标准抽象。具体落到代码里这三层各司其职CacheManager缓存管理器负责创建、管理和获取各种 Cache。一个 Spring 容器里可以注册多个 CacheManager比如一个 RedisCacheManager 管分布式缓存一个 CaffeineCacheManager 管本地热点缓存。Cache真正和中间件打交道的对象定义了 get、put、evict、clear 等操作相当于把 Redis 的 set/get/delete 包了一层统一接口。CacheInterceptorAOP 拦截器代理所有标注了缓存注解的 Bean 方法负责解析注解参数、生成 key、调用 Cache 接口并在方法执行异常时决定是否回滚缓存操作。我再打个比方CacheManager 像快递总站Cache 是里面一个个货架而 CacheInterceptor 是分拣员。快递总站管理货架列表分拣员接到订单后去对应货架的格子查货、放货、清货业务代码本身不用关心货架堆在哪里。这里要强调一点Spring Cache 的注解默认拦截粒度是 public 方法而且必须通过 Spring 代理对象调用自己在类内部用this调用是绕过了代理的注解不会生效。这个坑放在后面专门展开。2. 四个核心注解的实操从 EnableCaching 到 CacheEvict2.1 EnableCaching开关的作用比你想的更基础Spring Boot 项目里启用缓存注解第一步就是在配置类上加上EnableCachingConfiguration EnableCaching public class CacheConfig { }这个注解本身很简单但它背后做了一件事向容器注册一个CacheInterceptor的 Advisor让 Spring AOP 能识别Cacheable、CachePut、CacheEvict这些注解。也就是说不加它下面所有注解都会被当成普通注解忽略方法该执行照常执行只是没有缓存效果。同时要注意即使加了EnableCaching如果没有手动配置 CacheManagerSpring Boot 会自动装配一个ConcurrentMapCacheManager也就是基于ConcurrentHashMap的本地缓存。这个缓存适合开发环境验证但不适合生产原因后面会讲。2.2 Cacheable查询接口的正确打开方式Cacheable是使用频率最高的注解语义是方法执行前先查缓存缓存命中直接返回缓存结果不执行方法体缓存未命中则执行方法方法返回后自动把结果写进缓存。Cacheable(cacheNames user, key #userId) public UserDTO getUserById(String userId) { return userMapper.selectById(userId); }注意几个点cacheNames相当于命名空间同一个缓存名下的 key 是隔离的。key用 Spring Expression LanguageSpEL表达式#userId表示取方法参数列表里的userId后面会单独讲。方法返回值会被序列化后存入缓存所以谨慎起见缓存对象建议是纯 DTO不要直接把 ORM 实体丢进去避免出现多层关联对象序列化循环等问题。还有一个容易被忽略的参数sync true。它表示当缓存未命中时多个线程同时打到这个方法只有一个线程去执行目标方法其他线程等待结果。这在单机环境下能有效缓解缓存击穿但这是 JVM 级别的同步多实例部署时还是要靠分布式锁兜底。2.3 CachePut 和 CacheEvict写操作怎么保持缓存干净缓存设计中更新和删除往往比查询更考验功底。CachePut的语义是方法一定会执行执行完之后把返回值写进缓存。适合“更新后刷新缓存”的场景CachePut(cacheNames user, key #userDTO.userId) public UserDTO updateUser(UserDTO userDTO) { userMapper.updateById(userDTO); return userDTO; }CacheEvict的语义是方法执行后或执行前删除一个或多个缓存条目。适合“删除数据后清缓存”的场景CacheEvict(cacheNames user, key #userId) public void deleteUser(String userId) { userMapper.deleteById(userId); }这里要记住三个配套参数allEntries true清空整个 cacheNames 下的所有缓存条目。适合该维度下 key 不可枚举、或一次操作影响全部数据的情况代价是瞬时缓存全失效。beforeInvocation true在方法调用前清缓存。如果方法有报错风险但缓存又必须清理这个参数就有用了默认是在方法成功返回后才清缓存方法抛异常时缓存不会被清理。condition执行清理前先判断条件不满足则不清理。我在实际项目中有一个体会更新业务时更推荐“先写库再删缓存”的CacheEvict方案而不是CachePut。因为CachePut写进缓存的数据和数据库里的最终数据可能在并发窗口内不一致而且如果方法返回对象比实际落库数据少几个字段缓存里存的就是残缺数据。删缓存成本低最多下次查询回源一次。2.4 Caching 和 CacheConfig组合注解与类级别默认值业务方法往往不是单向操作。比如订单支付成功后订单详情缓存要更新用户订单列表缓存要清理这时候就需要组合注解Caching( put CachePut(cacheNames order, key #result.orderId), evict { CacheEvict(cacheNames orderList, allEntries true), CacheEvict(cacheNames userOrder, key #userId) } ) public OrderDTO payOrder(String userId, String orderId) { // 支付逻辑 }组合注解容易出现 key 写错导致缓存不更新的问题我的建议是如果一个方法里涉及多个缓存维度的变更先用工具类把 key 统一拼接好再写注解不要用三四个不同的 key 风格。CacheConfig是类级别的公共配置可以把cacheNames提到类上减少重复Service CacheConfig(cacheNames user) public class UserServiceImpl { Cacheable(key #userId) public UserDTO getUser(String userId) { ... } CacheEvict(key #userId) public void deleteUser(String userId) { ... } }但要注意CacheConfig定义的cacheNames优先级低于注解上的cacheNames这算是一个常见的预期偏差。3. 缓存 Key 生成与 SpEL 表达式数据不串用的根基3.1 默认 KeyGenerator 的行为以及为什么容易踩坑如果Cacheable上不写keySpring 会使用SimpleKeyGenerator生成 key。规则如下方法无参数key 是SimpleKey.EMPTY所有同类调用共用一条缓存。方法有一个参数key 就是参数本身要求参数正确重写了equals和hashCode。方法有多个参数key 是SimpleKey对象内部包裹了参数数组同样依赖参数的 equals。这个默认方案看起来省事实际上隐患不小。如果你方法的参数是一个可变的 Map 或者一个缺少 equals 的实体对象key 的稳定性就无法保证另外 key 的生成受参数数量、类型、顺序影响签名一变缓存就读不到了。我在一个老项目里遇到过同一个查询方法入参从String userId改成UserQuery query结果当天缓存命中率骤降因为 key 从字符串变成了对象类型对不上。所以我的建议是生产环境一定显式声明key。哪怕是只有一个参数也建议写成key #userId让 key 的意图体现在代码里而不是依赖框架猜。3.2 key 的演化从字符串拼接走到统一规则早期团队里常见的写法是Cacheable(cacheNames user, key user: #userId) public UserDTO getUser(String userId) { ... }这种写法的问题是开发者各自定义前缀userService里写user:orderService里写order:维护成本很高而且 cacheNames 本身已经起到前缀作用key 里再加业务前缀是重复的。后来项目里统一成了一种做法cacheNames 作为业务域前缀key 只表达业务维度。比如订单详情Cacheable(cacheNames order:detail, key #orderId) public OrderDTO getOrderDetail(String orderId) { ... } CacheEvict(cacheNames order:detail, key #orderId) public void cancelOrder(String orderId) { ... }组合维度可以用 SpEL 拼接例如用户维度下查角色列表Cacheable(cacheNames user:role, key #userId : #appId) public ListRoleDTO listUserRoles(String userId, String appId) { ... }用冒号分隔业务维度最终落到 Redis 里的完整 key 就是user:role::userId:appId可读性很强出问题也好在 Redis 客户端里手动排查。3.3 condition 与 unless两个条件注解判断时机完全不同很多新手容易把condition和unless当同一个东西用但其实它们作用的阶段不一样。condition在方法执行前判断基于入参决定“要不要走缓存逻辑”。如果条件为 false缓存读写都不参与相当于这个注解不生效。unless在方法执行后判断基于返回值决定“要不要写入缓存”。它不管读缓存只决定写不写。一个典型的场景根据商品 ID 查询详情只有库存大于 100 的商品才缓存因为热销商品查询频率高冷门商品没必要缓存。Cacheable(cacheNames product, key #productId, condition #stock 100, unless #result.stock 10) public ProductDTO getProductDetail(String productId, int stock) { ... }执行流程是先判断 stock 是否大于 100不满足直接查库不入缓存满足后查缓存未命中就执行方法方法返回后再看result.stock是否小于 10小于 10 则不写缓存。这种双条件配合适合“大促商品缓存”这类业务。4. 从本地缓存到 RedisCacheManager 切换与序列化排雷4.1 默认 ConcurrentMapCacheManager 为什么只能用于开发如果不做任何配置Spring Boot 自动配置的ConcurrentMapCacheManager会把缓存存在 JVM 堆内的 ConcurrentHashMap 中。它有三个致命问题多实例不共享。假设服务部署了三个节点同一个 key 的查询请求打到不同节点每个节点各持一份缓存命中率被平摊数据也可能不一致。重启即失效。发布时缓存清空启动瞬间所有请求直接打到数据库这就是典型的缓存雪崩场景。不可控。没有过期时间、没有容量上限、没有淘汰策略内存只增不减迟早出问题。我在一个小型内部系统里见过用本地缓存跑了一年的项目最后缓存了上百万数据又没人清理接口响应越来越慢GC 越来越频繁。所以生产级项目即使单节点也建议上 Caffeine多节点则直接考虑 Redis。4.2 引入 Caffeine高性能本地缓存的配置方式Caffeine 是目前 Java 生态里性能最好的本地缓存库Spring Boot 也内置了支持。引入依赖后配置一个CaffeineCacheManagerdependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-cache/artifactId /dependency dependency groupIdcom.github.ben-manes.caffeine/groupId artifactIdcaffeine/artifactId /dependency然后注册 CacheManagerBean public CacheManager caffeineCacheManager() { CaffeineCacheManager manager new CaffeineCacheManager(); manager.setCaffeine(Caffeine.newBuilder() .maximumSize(10_000) .expireAfterWrite(Duration.ofMinutes(30)) .recordStats()); manager.setAllowNullValues(false); return manager; }这里有几个实践要点maximumSize必须设置否则缓存不受控无限增长。expireAfterWrite适合读多写少且允许短暂不一致的场景如果是需要基于访问时间刷新的场景可以用expireAfterAccess。需要统计命中率时开启recordStats()配合 actuator 查看 Cache 指标。一个容易被忽略的问题是Caffeine 的refreshAfterWrite并不会自动更新缓存内容它只会在访问某个过期条目时触发异步加载需要显式传入一个 CacheLoader。如果没有 loaderrefreshAfterWrite相当于失效这一点官方文档写得比较含蓄实际调试时容易一头雾水。4.3 切到 RedisCacheManager 配置、TTL 与序列化多数 Web 服务最终都会落到 Redis。引入依赖后关键是配置RedisCacheManager而不是直接用 Spring Boot 的默认装配。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependency配置类代码如下Bean public RedisCacheManager redisCacheManager(RedisConnectionFactory factory) { ObjectMapper om new ObjectMapper(); om.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.ANY); om.activateDefaultTyping(LaissezFaireSubTypeValidator.instance, ObjectMapper.DefaultTyping.NON_FINAL, JsonTypeInfo.As.PROPERTY); om.findAndRegisterModules(); // 处理 LocalDateTime 等 Java 8 时间类型 GenericJackson2JsonRedisSerializer serializer new GenericJackson2JsonRedisSerializer(om); RedisCacheConfiguration config RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofMinutes(30)) .serializeValuesWith( RedisSerializationContext.SerializationPair.fromSerializer(serializer)) .computePrefixWith(name - name ::); return RedisCacheManager.builder(factory) .cacheDefaults(config) .withInitialCacheConfigurations(customTtlMap()) .build(); }序列化是这里最容易出问题的地方。很多项目直接使用JdkSerializationRedisSerializer缓存里存的是一大段二进制Redis 客户端里没法直接查看开发排查很不方便。我建议统一用GenericJackson2JsonRedisSerializer让缓存内容以 JSON 形式存储可读性高也让 Java 端和未来可能的非 Java 调用方都能理解数据。TTL 方面我习惯按缓存维度区分用户基础信息 30 分钟商品详情 10 分钟配置类数据 1 小时。不同 cacheNames 配不同 TTL方法是使用withInitialCacheConfigurationsprivate MapString, RedisCacheConfiguration customTtlMap() { MapString, RedisCacheConfiguration map new HashMap(); map.put(user, RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofMinutes(60)) .serializeValuesWith(...重复上面的序列化配置...)); map.put(product, RedisCacheConfiguration.defaultCacheConfig() .entryTtl(Duration.ofMinutes(10)) .serializeValuesWith(...)); return map; }4.4 本地缓存和 Redis 缓存并存类级别和注解级别的 CacheManager 选择如果项目同时注册了 Caffeine 和 Redis 两个 CacheManager默认注入时容易报错。解决办法是指定一个为主缓存管理器其他通过注解参数显式指定。我推荐把 Redis 作为默认 CacheManager高频且允许短期不一致的热点数据单独用 Caffeine 管理。使用方式Cacheable(cacheNames hot:rank, cacheManager caffeineCacheManager) public ListRankItem getHotRank() { ... } Cacheable(cacheNames order:detail, cacheManager redisCacheManager) public OrderDTO getOrderDetail(String orderId) { ... }这样做的好处是热点排行这类数据对一致性要求低、访问频率高放在本地内存里性能最好订单详情这种需要多个节点共享、并且希望客户端查 Redis 也能看到数据的放进 Redis 更合理。5. 踩坑实录注解不生效、缓存不更新、穿透击穿雪崩5.1 同一个类内部调用时为什么缓存注解“看不见”这是 Spring Cache 最常见、也最让人摸不着头脑的问题。看代码Service public class UserServiceImpl { Cacheable(cacheNames user, key #userId) public UserDTO getUser(String userId) { ... } public UserDTO getUserWithDetail(String userId) { UserDTO user this.getUser(userId); // 注解不生效 user.setExtra(...); return user; } }getUserWithDetail通过this.getUser()调用了同类方法this是原始对象而不是 Spring 生成的代理对象所以Cacheable的拦截器根本没有执行每次调用都会直接回源数据库。解决办法有几种把需要缓存的方法拆到一个单独的 Service Bean 里然后注入这个 Bean 调用。这是最清晰、最可控的方案。注入自身的代理引用例如Autowired private UserServiceImpl self;然后调用self.getUser()。开启exposeProxy后使用AopContext.currentProxy()但这种方式侵入性强我不太推荐。我在代码评审时看到过一种隐蔽的写法把Cacheable加在 private 方法上。这个必须避免Spring AOP 只能增强 public 方法的调用过程private 方法根本不经过代理。5.2 缓存不更新CachePut 的 key 和 Cacheable 对不上另一个高发问题是查询方法用#userId做 key更新方法的入参里没有userId结果缓存写入时 key 计算失败或者写进了一个完全不同的 key。举个例子Cacheable(cacheNames user, key #userId) public UserDTO getUser(String userId) { ... } CachePut(cacheNames user, key #userDTO.userId) public UserDTO updateUser(UserDTO userDTO) { ... }查询时的 key 是userId字符串更新时如果userDTO.userId为 null框架会抛IllegalArgumentException而且抛出的时机在方法成功执行之后导致数据库更新成功但缓存没写对。做法上我建议更新方法的入参里强制带上业务主键如果拿不到主键就通过上下文工具类获取当前登录用户 ID拼接 key。总之一个业务维度的 key 必须在所有操作里保持一致这是缓存数据不串味的前提。还有一种冷门但真实的坑返回对象是一个接口或者抽象类序列化后反序列化时丢失字段。Spring Cache 默认的SimpleKeyGenerator在生成 key 时也依赖参数的 hashCode/equals如果参数是一个带了枚举、内部类、代理对象的实体equals 计算结果不稳定缓存命中率会变得毫无规律。5.3 序列化失败与类型转换失败的典型表现Redis 缓存模式下缓存读不出来或者读出来不对主要集中在序列化配置上。我列了最常见的三种现象现象原因解法反序列化时报ClassCastException缓存里存的是 LinkedHashMap代码强转成 DTO 类型使用 GenericJackson2JsonRedisSerializer 并激活 DefaultTypingDTO 必须有默认构造和 getter/setterLocalDateTime 反序列化报错Jackson 没有注册日期时间模块在 ObjectMapper 上调用findAndRegisterModules()Redis 里看到一长串二进制使用了 JdkSerializationRedisSerializer改为 JSON 序列化便于排查在代码设计上缓存对象建议单独定义。不要直接把大量字段的数据库实体丢进缓存字段多了序列化时间长也更容易出现版本兼容问题。最好是定义只包含必要字段的 DTO字段类型尽量用基本类型和常用 JDK 类型避免自定义嵌套对象引起反序列化折腾。5.4 缓存穿透、击穿、雪崩的兜底策略Spring Cache 本身不会自动解决这三个经典问题但它提供了部分工具。缓存穿透查询一个根本不存在的数据每次请求都绕过缓存直接打到数据库。防御策略有两个方向一是参数合法性校验非法 ID 直接返回二是把空结果也缓存起来Spring Cache 默认allowNullValues是 true即方法返回 null 时也会写缓存这样可以挡住大量恶意请求。缓存击穿一个热点 key 失效瞬间大量请求同时击到数据库。单机环境下Cacheable(sync true)可以保证同一 JVM 内只有一个线程去回源。多实例部署时可以在回源方法里用 Redisson 等分布式锁做双检锁。缓存雪崩大量 key 在同一时间过期数据库瞬时被打爆。核心对策是给 TTL 加随机扰动不让一批 key 整整齐齐地同时失效。这里必须说清楚sync true解决的是单个 key 的并发回源而雪崩解决的是“很多 key 同时过期”的问题两者不要混淆。5.5 事务提交与缓存更新顺序问题在 Spring Cache 和Transactional混用的场景里有一个顺序问题经常被忽略事务还没有提交缓存已经被更新了。比如Transactional CacheEvict(cacheNames user, key #userId) public void updateUser(String userId) { userMapper.updateById(userId); // 如果事务回滚缓存已经被清掉了数据库还是旧值下次查询又会回源 }如果事务回滚了缓存清理动作不会跟着回滚。下一次请求打过来缓存里没有数据于是回源数据库这时数据库还是旧值反而没问题。但反过来的问题是如果是CachePut事务回滚了缓存却被写入了新值缓存里的数据和数据库不一致问题就严重了。更稳妥的方案是在事务提交后再清理缓存Transactional public void updateUser(String userId) { userMapper.updateById(userId); TransactionSynchronizationManager.registerSynchronization( new TransactionSynchronization() { Override public void afterCommit() { cacheEvictUser(userId); // 调用一个 CacheEvict 方法 } }); }顺带说一句CacheEvict默认是在方法执行成功后、退出前执行清理这个时机和事务提交不是一个节点所以涉及事务的写操作务必把缓存清理放到afterCommit里。6. 可观测与验证不要只加注解还要能证明缓存有效6.1 用指标统计看命中率别靠“感觉”我见过很多项目Cacheable加得很勤快但从来没有确认过缓存到底有没有命中。没有指标等于闭着眼开车。Spring Boot Actuator 配合 Cache 指标可以看到每个 CacheManager 下不同 cacheName 的命中次数、未命中次数、加载耗时。首先引入 actuator 依赖注册CacheMetricsRegistrarBean public CacheMetricsRegistrar cacheMetricsRegistrar(CacheManager cacheManager) { return new CacheMetricsRegistrar(cacheManager); }开启指标后通过 actuator 的 metrics 端点查看cache.gets cache.puts cache.evictions cache.gets.success命中率 cache.gets.success / cache.gets。我在监控面板上同时接了这三个指标并设置了告警活跃缓存命中率低于 80% 时就要人工排查 key 设计或者 TTL 配置。真实项目里很多“缓存不生效”的问题最后都是靠命中率骤降这个指标暴露出来的。如果不想引入繁杂的监控体系也可以用 Caffeine 的recordStats()结合本地日志做快速验证。线上压测时观察数据库查询 QPS 和缓存命中数如果 QPS 没有明显下降说明注解可能没生效。6.2 压测与验证的简单做法写完缓存后我自己习惯做一轮“前测后测”第一步确认 Redis 里产生了预期的 key。第二步连续请求同一个 key 两次观察第二次是否走了缓存最简单的方法是看日志里是否打印目标方法。第三步用小流量压测工具打 1000 个请求观察 DB 的 QPS 波动和缓存命中数。这里有一个经验不要只看 controller 层返回成功就认为缓存生效。Spring Cache 的注解不是编译期拦截它是运行期 AOP代理没生效时业务照样能跑只是慢而已。如果你在服务日志里看到目标方法被打印了 N 次而 N 又等于请求次数那基本可以断定代理失效了。6.3 最后分享一个我个人的体会在真实项目中缓存设计的核心难点往往不是注解怎么用而是先想清楚“缓存什么数据、存在哪、怎么失效、失效后有没有兜底”。我把这套问题列在需求评审清单里每次新增缓存接口都过一遍。实际踩过几次线上事故后我越来越认同一个观点缓存是牺牲一致性换取性能的手段所以在方案设计时要能明确回答“脏数据能容忍多久”。顺带一个小技巧我在线上环境会为每个缓存名维护一个配置化的 TTL通过配置中心动态调整。大促前把核心热点的 TTL 调短或加长不用重新发布代码。Spring Cache 的 RedisCacheManager 本身支持覆盖默认配置利用好这一点缓存策略会灵活很多。
