3. Spring Boot 缓存抽象：@Cacheable、@CachePut、@CacheEvict 注解详解

Spring 框架自 3.1 版本起提供了声明式缓存抽象，允许开发者通过注解以极低的侵入性为业务方法添加缓存能力。Spring Boot 在此基础上进一步简化了配置，使得开发者只需关注缓存语义本身。本章将深入剖析三个核心注解：@Cacheable、@CachePut 和 @CacheEvict，并探讨它们在缓存一致性场景下的正确使用方式。

3.1 缓存抽象核心概念

在深入注解之前，需要理解 Spring 缓存抽象的三个核心角色：

3.2 @Cacheable：读缓存的核心入口

@Cacheable 用于标记需要缓存结果的方法。其执行流程遵循“先查缓存，再执行方法”的原则：

1. 根据缓存名称和键生成策略计算缓存键。
2. 尝试从缓存中获取值。
3. 如果命中缓存，直接返回缓存值，不执行方法体。
4. 如果未命中，执行方法体，将返回值存入缓存，然后返回结果。

@Service
public class UserService {

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

3.2.1 核心属性详解

3.3 @CachePut：主动更新缓存

@CachePut 总是执行方法体，并将返回值更新到缓存中。它与 @Cacheable 的核心区别在于：不跳过方法执行。适用于写操作后需要同步更新缓存的场景。

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

3.3.1 与 @Cacheable 的对比

3.4 @CacheEvict：缓存失效与清理

@CacheEvict 用于从缓存中移除条目，是维护缓存一致性的关键工具。它支持两种失效模式：单条失效和批量清空。

// 单条缓存失效
@CacheEvict(value = "users", key = "#userId")
public void deleteUser(Long userId) {
    userRepository.deleteById(userId);
}

// 批量清空整个缓存区域
@CacheEvict(value = "users", allEntries = true)
public void clearAllUsers() {
    // 清空 users 缓存区域中的所有条目
}

3.4.1 关键属性

3.5 组合使用：缓存一致性策略

在实际业务中，读多写少的场景需要将三个注解组合使用，形成完整的缓存生命周期管理。以下是一个典型的最佳实践模式：

@Service
public class ProductService {

    // 读操作：缓存结果
    @Cacheable(value = "products", key = "#productId")
    public Product getProduct(Long productId) {
        return productRepository.findById(productId).orElse(null);
    }

    // 写操作：更新缓存
    @CachePut(value = "products", key = "#product.id")
    public Product updateProduct(Product product) {
        return productRepository.save(product);
    }

    // 写操作：失效缓存
    @CacheEvict(value = "products", key = "#productId", beforeInvocation = true)
    public void deleteProduct(Long productId) {
        productRepository.deleteById(productId);
    }

    // 批量操作：清空缓存区域
    @CacheEvict(value = "products", allEntries = true)
    public void refreshAllProducts() {
        // 触发全量数据刷新
    }
}

3.6 注解执行流程与 AOP 原理

Spring 通过 AOP（面向切面编程）拦截带有缓存注解的方法。下图展示了 @Cacheable 注解的完整执行流程：

3.7 常见陷阱与避坑指南

3.8 注解组合与缓存一致性策略矩阵

针对不同的业务操作类型，推荐采用以下注解组合策略来保证缓存与数据库的一致性：

3.9 本章小结