在 Spring Boot 项目里引入缓存可以显著降低数据库压力，但注解用得不严谨就会留下难以排查的数据不一致问题。@EnableCaching 负责激活 Spring 的缓存抽象，而 @CachePut 专门用来在方法执行后把返回值塞进缓存，二者配合才是完整的写缓存链路。理解它们背后的代理机制和键值规则，比单纯复制注解更重要。
@EnableCaching 的底层作用与配置方式
@EnableCaching 本身并不提供缓存存储能力，它做的是向 Spring 容器注册一系列后置处理器，比如 ProxyCachingConfiguration 里定义的切面。这些切面会扫描带有缓存注解的 Bean，并通过 AOP 代理在方法调用前后织入缓存读写逻辑。如果不在配置类或启动类上声明这个注解，即便写了 @CachePut 也不会有任何效果，因为对应的 CacheInterceptor 根本没有被创建。
在 Spring Boot 中通常直接在主类标注即可，但需要注意缓存管理器必须存在。框架默认会按顺序查找 ConcurrentMapCacheManager、Redis 等实现，若引入了 spring-boot-starter-data-redis 且没有自定义，就会自动装配 Redis 缓存管理器。下面是最基础的开启方式：
@SpringBootApplication
@EnableCaching
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
有些团队习惯把缓存配置独立成 CacheConfig 类，这没有问题，但务必保证该类被组件扫描覆盖。另外当项目里出现多个 CacheManager 实例时，需要用 @Primary 标明默认实现，否则启动阶段就会抛出 NoUniqueBeanDefinitionException，导致整个应用无法起来。
@CachePut 的执行机制与常见误用
@CachePut 的设计目标是“无论如何都执行方法，并把结果写入缓存”。它和 @Cacheable 最大区别在于：后者先查缓存，命中就直接返回不进方法；前者永远进方法，执行完再用返回值覆盖缓存。因此在更新场景中，正确做法是先通过 Repository 修改数据库，再让 @CachePut 把新对象写回，而不是指望它顺带查库。
一个典型错误是把 @CachePut 和 @Cacheable 放在同一个方法上，或者 key 表达式写得不一致。例如更新方法用 key = "#user.id"，查询方法却用 key = "#id"，由于 SpEL 解析出的键不同，更新后的数据并不会刷新旧缓存，前端仍然读到老值。下面给出配对使用的规范示例：
@Cacheable(value = "user", key = "#id")
public User findById(Long id) {
return userMapper.selectById(id);
}
@CachePut(value = "user", key = "#user.id")
public User update(User user) {
userMapper.updateById(user);
return user;
}
还有一点容易被忽略：@CachePut 标注的方法如果返回 null，缓存里对应的键会被置空，下次查询直接穿透到数据库。因此在写更新接口时，务必确认 Mapper 或 Service 返回的实体不是空对象。另外方法必须是 public 且通过外部 Bean 调用，类内部 this.update() 这类自调用不会经过代理，注解完全失效。
整合过程中的典型坑点与排查思路
最先遇到的大概率是“注解写了但缓存没反应”。除了前面说的没加 @EnableCaching，还可能是依赖缺失。比如只用 spring-context 没引入具体缓存实现，控制台虽不会报红，但 CacheResolver 解析不到存储层，操作都被无缓存实现默默跳过。引入 Redis 后还要检查连接配置，本地没启 Redis 却填了地址，会导致启动时 RedisConnectionFailureException。
事务边界和缓存顺序也常引发脏数据。假设在 @Transactional 方法里先更新库再调用 @CachePut 方法，如果事务中途回滚，数据库没变但缓存已被新值覆盖，形成不一致。推荐把写缓存放在事务提交之后，或采用 TransactionSynchronizationManager 监听提交事件再操作。此外 key 里包含对象时，记得重写 hashCode 与 equals，否则默认引用比较会让相同业务主键生成不同缓存键。
@Transactional
public void saveAndCache(User user) {
userMapper.insert(user);
// 错误：事务未提交就可能写缓存
cacheService.refresh(user);
}
最后看性能层面。@CachePut 每次都执行真实方法，对于计算昂贵但结果稳定的场景并不合适，那种情况应优先 @Cacheable。若业务要求批量失效，可用 @CacheEvict 的 allEntries = true 清理整个区域，而不是循环调 @CachePut。理清这几个注解的语义边界，Spring Boot 的缓存整合才算真正落地。
Spring_BootEnableCachingCachePut修改时间：2026-08-15 07:15:27