Spring缓存注解详解：核心价值与实战技巧-代码聚汇网

Spring缓存注解详解：核心价值与实战技巧

阿丁的猫·2026-08-11·阅读 23 GEO检测（免费）

Spring Cache缓存注解@Cacheable

|难度：普通|阅读约 17 分钟

1. Spring缓存注解的核心价值与应用场景

在Java企业级开发中，缓存是提升系统性能的银弹级解决方案。Spring框架从3.1版本开始引入的缓存抽象层，通过声明式注解的方式让开发者可以零侵入地实现缓存功能。相比直接操作Redis或Memcached等缓存中间件，Spring Cache提供了更高层次的抽象，使得：

业务代码与缓存实现解耦
缓存配置集中化管理
缓存操作语义化表达

实际项目中常见的适用场景包括：

高频查询且数据变化不频繁的字典表数据
复杂计算结果缓存（如报表数据）
接口防重提交的临时令牌存储
热点数据预加载

重要提示：Spring Cache是抽象层而非具体实现，底层仍需配合Caffeine、Redis等具体缓存库使用。注解只是定义了"做什么"，具体"怎么做"由CacheManager配置决定。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 核心注解全景解析

2.1 @Cacheable - 查询缓存的标准姿势

这是最常用的缓存注解，方法执行前会检查缓存，命中则直接返回缓存值。其核心属性包括：

java复制@Cacheable(
    value = "userCache", 
    key = "#userId",
    condition = "#userId.length() > 5",
    unless = "#result == null"
)
public User getUserById(String userId) {
    // 数据库查询逻辑
}

value/cacheNames：必填项，指定缓存名称（可多个），对应CacheManager中的缓存配置
key：SpEL表达式生成的缓存键，默认使用方法参数计算
keyGenerator：自定义键生成器Bean名称（与key属性互斥）
condition：执行前判断条件，满足才查缓存
unless：执行后判断条件，满足则不缓存结果
sync：是否同步加载（防止缓存击穿）

实战经验：

建议显式指定key属性，避免多参数方法产生意外键冲突
unless判断结果而非condition判断参数是更安全的做法
对于耗时方法建议设置sync=true，但会降低吞吐量

2.2 @CachePut - 数据更新时的双写策略

强制方法执行并更新缓存，常用于新增/修改操作：

java复制@CachePut(
    value = "userCache",
    key = "#user.userId",
    unless = "#result == null"
)
public User updateUser(User user) {
    // 更新数据库
    return user; 
}

特别注意：

方法必须返回缓存值（建议返回持久化后的对象）
通常与@Cacheable使用相同的key策略
更新操作要考虑事务回滚时的缓存一致性

2.3 @CacheEvict - 精准的缓存清理

删除指定缓存项，支持两种模式：

java复制// 单条删除
@CacheEvict(value="userCache", key="#userId")

// 清空整个缓存区域
@CacheEvict(value="userCache", allEntries=true)

关键属性：

allEntries：是否清空整个缓存区
beforeInvocation：是否在方法执行前清除（默认false）
事务场景下建议结合@Transactional使用

2.4 @Caching - 复合缓存操作

组合多个缓存注解的元注解：

java复制@Caching(
    cacheable = {
        @Cacheable(value="userCache", key="#username")
    },
    put = {
        @CachePut(value="userCache", key="#result.userId")
    }
)
public User getUserByUsername(String username) {
    // 同时按username和userId缓存
}

典型使用场景：

多维度查询缓存（如同时按ID和名称缓存）
级联更新关联缓存

2.5 @CacheConfig - 类级别的缓存配置

统一类中所有缓存注解的默认配置：

java复制@CacheConfig(cacheNames = "userCache")
@Service
public class UserService {
    @Cacheable(key = "#id")
    public User get(Long id) {...}
}

可配置项包括：

cacheNames
keyGenerator
cacheManager
cacheResolver

3. 高级特性与实战技巧

3.1 自定义KeyGenerator实现

当默认的键生成策略不满足需求时，可以实现KeyGenerator接口：

java复制@Component("customKeyGenerator")
public class MyKeyGenerator implements KeyGenerator {
    @Override
    public Object generate(Object target, Method method, Object... params) {
        return method.getName() + 
               Arrays.stream(params)
                     .map(Object::hashCode)
                     .collect(Collectors.toList());
    }
}

// 使用示例
@Cacheable(value="books", keyGenerator="customKeyGenerator")

3.2 条件缓存的高级玩法

SpEL表达式在condition和unless中的妙用：

java复制// 只缓存管理员用户
@Cacheable(value="users", condition="#user.role == 'admin'")

// 不缓存异常结果
@Cacheable(value="data", unless="#result instanceof T(java.lang.Exception)")

// 工作时间才缓存
@Cacheable(value="reports", 
          condition="T(java.time.LocalTime).now()
                    .isAfter(T(java.time.LocalTime).of(9, 0))")

3.3 缓存与事务的协同问题

缓存操作默认不与Spring事务同步，可能导致：

事务回滚但缓存已更新
事务未提交但缓存已读取到旧值

解决方案：

配置TransactionAwareCacheManagerProxy
在@Transactional注解的方法内手动控制缓存操作顺序
使用@CacheEvict的beforeInvocation=true

3.4 多级缓存实现策略

结合本地缓存与分布式缓存：

java复制@Cacheable(value = {
    "localUserCache",  // Caffeine
    "redisUserCache"   // Redis
}, key = "#userId")
public User getUser(String userId) {
    // ...
}

配置示例：

yaml复制spring:
  cache:
    cache-names: localUserCache,redisUserCache
    caffeine:
      spec: maximumSize=1000,expireAfterWrite=5m
    redis:
      time-to-live: 30m

4. 性能调优与问题排查

4.1 缓存命中率监控

通过CacheStatistics可视化缓存效果：

java复制@Autowired
private CacheManager cacheManager;

public void printStats() {
    cacheManager.getCacheNames().forEach(name -> {
        Cache cache = cacheManager.getCache(name);
        if (cache.getNativeCache() instanceof CaffeineCache) {
            com.github.benmanes.caffeine.cache.CaffeineCache nativeCache = 
                (com.github.benmanes.caffeine.cache.CaffeineCache) cache.getNativeCache();
            System.out.println(nativeCache.stats());
        }
    });
}

关键指标：

命中率（hitRate）
加载时间（averageLoadPenalty）
缓存项数量（estimatedSize）

4.2 缓存雪崩预防策略

差异化过期时间：

java复制@Cacheable(value="products", 
          key="#productId",
          cacheManager="randomTtlCacheManager")

热点数据预加载：

java复制@Scheduled(fixedRate = 10_000)
public void preloadHotData() {
    hotProductIds.forEach(id -> 
        productService.getProduct(id));
}

4.3 常见问题排查指南

问题1：缓存未生效

检查是否启用@EnableCaching
确认方法是否为public且被Spring代理
查看condition/unless条件是否意外拦截

问题2：缓存脏读

检查@CachePut和@CacheEvict的key是否匹配
确认事务边界是否正确
考虑添加版本号或时间戳字段

问题3：内存泄漏

限制本地缓存大小
对大数据对象考虑软引用

java复制caffeine.spec=maximumSize=1000,softValues

5. 最新生态整合

5.1 与Spring Boot 3.x的适配

自动配置变化：

java复制@Configuration
@EnableCaching
public class CacheConfig {
    @Bean
    public RedisCacheManagerBuilderCustomizer redisCacheManagerBuilderCustomizer() {
        return builder -> builder
            .withCacheConfiguration("userCache",
                RedisCacheConfiguration.defaultCacheConfig()
                    .entryTtl(Duration.ofMinutes(30)));
    }
}

记录式接口支持：

java复制@Cacheable(cacheNames="users")
public Optional<User> findById(Long id) {
    // 自动处理Optional返回值
}

5.2 响应式编程支持

WebFlux环境下的缓存使用：

java复制@Cacheable("fluxCache")
public Mono<User> findUserReactive(String userId) {
    return reactiveRepo.findById(userId);
}

配置要点：

yaml复制spring:
  cache:
    type: reactive
    redis:
      enable-statistics: true

5.3 智能缓存实践

结合Spring AI实现动态缓存策略：

java复制@Cacheable(
    value = "smartCache",
    key = "#query",
    condition = "#aiService.shouldCache(#query)"
)
public Result getAIResult(String query) {
    return aiService.process(query);
}