2. Spring Boot 缓存抽象：@Cacheable、@CachePut、@CacheEvict 注解详解与配置

Spring 框架从 3.1 版本开始引入了声明式缓存抽象，它通过一组注解将缓存操作与业务逻辑解耦。开发者无需手动编写缓存读写代码，只需在方法上添加注解，即可实现缓存数据的存取、更新与失效。本章将深入剖析三个核心注解 @Cacheable、@CachePut 和 @CacheEvict 的工作原理、配置细节及最佳实践。

2.1 缓存抽象核心概念

在深入注解之前，需要理解 Spring 缓存抽象中的几个关键组件：

2.2 @Cacheable：缓存读取与存储

@Cacheable 是最常用的缓存注解，用于标记需要缓存结果的方法。当方法被调用时，Spring 会先检查缓存中是否存在对应键的值：

• 缓存命中： 直接返回缓存值，不执行方法体。
• 缓存未命中： 执行方法体，将返回值存入缓存，再返回结果。

2.2.1 基本用法与属性

@Service
public class UserService {

    @Cacheable(value = "users", key = "#id")
    public User getUserById(Long id) {
        // 模拟耗时数据库查询
        simulateSlowQuery();
        return userRepository.findById(id).orElse(null);
    }
}

2.2.2 缓存键生成策略

Spring 使用 KeyGenerator 接口生成缓存键。默认实现 SimpleKeyGenerator 的规则如下：

• 无参数： 使用 SimpleKey.EMPTY（空键）。
• 一个参数： 直接使用该参数作为键。
• 多个参数： 使用 SimpleKey 对象包装所有参数。

2.2.3 condition 与 unless 的区别

@Cacheable(value = "users", key = "#id",
           condition = "#id != null",
           unless = "#result == null")
public User getUserById(Long id) {
    return userRepository.findById(id).orElse(null);
}

2.2.4 sync 同步模式

在高并发场景下，多个线程同时请求同一个未缓存的 key 会导致缓存击穿。设置 sync = true 后，Spring 会对缓存键加锁，确保只有一个线程执行方法体，其他线程等待结果：

@Cacheable(value = "users", key = "#id", sync = true)
public User getUserById(Long id) {
    // 高并发下只有一个线程执行此方法
    return userRepository.findById(id).orElse(null);
}

2.3 @CachePut：缓存更新

@CachePut 注解用于强制更新缓存。与 @Cacheable 不同，它始终执行方法体，并将返回值更新到缓存中。常用于数据更新操作后刷新缓存。

@CachePut(value = "users", key = "#user.id")
public User updateUser(User user) {
    return userRepository.save(user);
}

2.4 @CacheEvict：缓存失效

@CacheEvict 用于从缓存中移除数据，通常在删除或更新操作后调用，避免脏数据残留。

2.4.1 基本用法

@CacheEvict(value = "users", key = "#id")
public void deleteUser(Long id) {
    userRepository.deleteById(id);
}

2.4.2 关键属性

2.4.3 allEntries：批量清空

当需要清空某个缓存区域的所有数据时，设置 allEntries = true：

@CacheEvict(value = "users", allEntries = true)
public void clearAllUserCache() {
    // 方法体可以为空，仅用于触发缓存清理
}

2.4.4 beforeInvocation：执行时机

默认情况下，@CacheEvict 在方法执行成功返回后才清除缓存。如果方法抛出异常，缓存不会被清除。设置 beforeInvocation = true 可以在方法执行前清除缓存：

@CacheEvict(value = "users", key = "#id", beforeInvocation = true)
public void deleteUserWithException(Long id) {
    // 即使此方法抛出异常，缓存也会被清除
    userRepository.deleteById(id);
    throw new RuntimeException("模拟异常");
}

2.5 注解组合与缓存一致性闭环

在实际业务中，单一注解往往无法满足复杂的缓存一致性需求。下图展示了典型的缓存一致性闭环流程：

2.6 缓存配置与启用

2.6.1 启用缓存抽象

在 Spring Boot 中，只需在配置类或启动类上添加 @EnableCaching 注解即可启用缓存抽象：

@SpringBootApplication
@EnableCaching
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

2.6.2 配置缓存管理器

Spring Boot 自动配置了 CacheManager，但可以通过配置文件自定义缓存行为。以 Caffeine 缓存为例：

# application.yml
spring:
  cache:
    type: caffeine
    cache-names: users,products,orders
    caffeine:
      spec: maximumSize=500,expireAfterWrite=10m

2.6.3 自定义 KeyGenerator

当默认的键生成策略不满足需求时，可以自定义 KeyGenerator：

@Configuration
public class CacheConfig {

    @Bean("customKeyGenerator")
    public KeyGenerator customKeyGenerator() {
        return (target, method, params) -> {
            StringBuilder sb = new StringBuilder();
            sb.append(target.getClass().getSimpleName());
            sb.append(".");
            sb.append(method.getName());
            sb.append("(");
            for (Object param : params) {
                sb.append(param).append(",");
            }
            sb.append(")");
            return sb.toString();
        };
    }
}

// 使用自定义 KeyGenerator
@Cacheable(value = "users", keyGenerator = "customKeyGenerator")
public User getUserById(Long id) {
    return userRepository.findById(id).orElse(null);
}

2.7 常见问题与最佳实践