@CachePut 是 Spring Cache 体系里负责“更新缓存”的注解，但它也是最容易和 @Cacheable 混淆的一个。不少团队在写缓存逻辑时，把更新方法也标上 @Cacheable，结果数据改了缓存还是旧值；也有人标了 @CachePut，却发现缓存根本没写进去。这篇文章从执行原理讲起，配合完整代码，把 @CachePut 在 Spring Boot 中的正确用法和常见陷阱一次说清楚。
@CachePut 的执行原理与三大注解的区别
Spring Cache 抽象层的核心思路是 AOP 代理。当一个 Bean 的方法被 @CachePut 标注后，容器启动时会为这个 Bean 生成代理对象，所有外部调用都会先经过缓存拦截器 CacheInterceptor。对 @CachePut 来说，拦截器的处理顺序是：先执行方法体本身，方法正常返回后，再把返回值写入缓存。注意这里是“先执行后写缓存”，与 @Cacheable 的“先查缓存、命中就跳过方法”完全相反。理解这一点，是正确使用 @CachePut 的前提。
三个常用注解各司其职，对比如下：
- @Cacheable：先按 key 查缓存，命中则直接返回缓存值，方法体不执行；未命中才执行方法并把结果放入缓存。适合查询场景。
- @CachePut：方法体一定会执行，执行完毕后用返回值更新缓存。适合新增、修改后希望缓存与数据库保持一致的场景。
- @CacheEvict：方法执行前或执行后删除指定 key 的缓存，通常配合删除、修改操作触发下次重新加载。
一个典型的完整链路是：查询方法用 @Cacheable，更新方法用 @CachePut，删除方法用 @CacheEvict，三者操作同一个缓存名和同样的 key 生成规则，才能保证缓存数据的一致性。如果查询时 key 是 user::1，而更新时 key 算出来是 user::userService.getUser(1)，缓存自然永远对不上。
Spring Boot 中整合 @CachePut 的完整代码示例
第一步是开启缓存能力。在启动类上加 @EnableCaching，Spring Boot 会根据 classpath 中的依赖自动装配缓存管理器。如果只引入了 spring-boot-starter-cache，默认使用 ConcurrentMapCacheManager，适合单机测试；生产环境一般换成 Redis。
@SpringBootApplication
@EnableCaching
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}第二步是编写服务类，查询与更新使用相同的 key 表达式。下面这个例子中，查询和更新都通过 #id 生成 key，保证读写落在同一个缓存条目上：
@Service
public class UserService {
// 模拟数据库
private Map<Long, User> userDB = new ConcurrentHashMap<>();
// 查询：先查缓存，未命中执行方法并写入缓存
@Cacheable(value = "user", key = "#id")
public User getUser(Long id) {
System.out.println("查询数据库, id=" + id);
return userDB.get(id);
}
// 更新：方法一定执行，返回值覆盖缓存中的旧数据
@CachePut(value = "user", key = "#user.id")
public User updateUser(User user) {
System.out.println("更新数据库, id=" + user.getId());
userDB.put(user.getId(), user);
return user;
}
// 删除：清除缓存
@CacheEvict(value = "user", key = "#id")
public void deleteUser(Long id) {
userDB.remove(id);
}
}如果切换到 Redis，只需在 pom.xml 中加入 spring-boot-starter-data-redis 并在配置文件指定 Redis 地址，CacheManager 会自动切换，业务代码一行都不用改。这正是 Spring Cache 抽象的价值：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
spring.redis.host=127.0.0.1 spring.redis.port=6379 # 缓存过期时间，单位秒 spring.cache.redis.time-to-live=3600
@CachePut 的四个常见坑与解决办法
坑一：key 表达式写错，更新和查询不在同一条目上
这是最高频的错误。查询时 key 写的是 #id，更新时随手写成 #user.id 之外的形式，或者缓存名写成了不同的 value，导致更新写到另一个缓存空间。排查时可以直接看 Redis 中实际生成的 key（默认格式为“缓存名::key”），确认读写两侧是否完全一致。建议把 key 表达式抽成常量或统一放在一个 SpEL 工具类中管理。
坑二：自调用导致注解失效
Spring Cache 基于 AOP 代理，同一个类内部方法直接调用 this.updateUser() 不会走代理，注解完全不生效，缓存不会更新也不会有任何报错，非常隐蔽。解决办法有三种：把方法拆到另一个 Bean；注入自身代理对象（通过 AopContext.currentProxy() 并开启 exposeProxy = true）；或者使用 ObjectProvider 延迟获取自身。最简单可靠的还是第一种，按职责拆类。
坑三：返回值不合适导致缓存被污染
@CachePut 缓存的是方法的返回值。如果更新方法返回 void 或者返回了一个不完整的对象，缓存里就会被写入 null 或半截数据。正确的做法是让更新方法返回更新后的完整实体，而不是返回一个布尔值或者不返回任何内容。
// 错误示例：缓存里会被写入 null
@CachePut(value = "user", key = "#user.id")
public void updateUser(User user) {
userDB.put(user.getId(), user);
}
// 正确示例：返回完整实体
@CachePut(value = "user", key = "#user.id")
public User updateUser(User user) {
userDB.put(user.getId(), user);
return user;
}坑四：条件注解使用不当
@CachePut 支持 condition 和 unless 属性。condition 在方法执行前判断，为 true 才执行缓存写入逻辑；unless 在方法执行后根据返回值判断。常见误用是想“结果为 null 时不缓存”却写到了 condition 上，结果表达式取不到返回值直接报错。正确写法是：
@CachePut(value = "user", key = "#user.id", unless = "#result == null")
public User updateUser(User user) {
// ...
return user;
}使用 @CachePut 的最佳实践
第一，读写两侧的缓存名和 key 表达式必须严格一致，最好在团队内约定统一的命名规范，比如“实体名 + 主键字段”，避免每个人各写各的。第二，更新方法一定要返回完整实体，保证写入缓存的数据结构正确。第三，如果更新操作只是部分字段修改，注意 @CachePut 是整体覆盖，不会做字段级合并，需要先查出完整对象再修改后返回。第四，对一致性要求极高的场景，@CachePut 也只能保证“先更新库再更新缓存”的最终一致性，极端并发下仍可能出现短暂旧值，必要时可以配合 @CacheEvict 直接删缓存，让下次查询回源数据库。
总结一下，@CachePut 的核心就一句话：方法照常执行，返回值刷新缓存。把它和 @Cacheable 的执行时机区分开，管好 key 的生成规则，避开自调用和返回值陷阱，缓存一致性就有了基本保障。理解了这些细节之后，再去看 Spring Cache 的源码和 Redis 集成方案，也会顺畅很多。
Spring BootCachePutSpring Cache修改时间：2026-09-05 04:22:33