SpringCache源码解析Annotation案例讲解

〇、常用注解

一、@Cacheable注解

• 简介：表示该方法执行后的结果可以被缓存；可作用于类和方法，作用于类上，则表示对该类的所有方法都有效；
• 执行逻辑：查找对应的缓存是否存在，若不存在，该方法会被调用，并且将返回结果放入缓存；若存在，则不调用方法，直接返回缓存的结果；

1.1 案例

注解业务案例 单一缓存名称和键：

@Cacheable("books")
public Book findBookById(String id) {
    // 业务逻辑
}

多个缓存名称和条件：

@Cacheable(value = {"books", "archivedBooks"}, condition = "#id.length() > 10")
public Book findBookWithComplexKey(String id) {
    // 业务逻辑
}
@Service
public class MyService {
    /**
     * 一个使用 @Cacheable 所有属性的案例。
     * 
     * @param id 用户ID
     * @return 返回用户对象
     */
    @Cacheable(
        value = "users",          // 缓存名称
        key = "#id",              // 缓存键，使用SpEL表达式
        condition = "#id.length() > 3",  // 缓存条件，只有当ID长度大于3时才缓存
        unless = "#result == null" // 除非条件，如果结果为null，则不缓存
    )
    public User findUserById(String id) {
        // 模拟数据库查询操作，这里假设ID长度小于3时没有结果
        if (id == null || id.length() <= 3) {
            return null;
        }
        return performDatabaseQuery(id);
    }
    private User performDatabaseQuery(String id) {
        // 模拟数据库查询逻辑
        return new User(id, "Name based on ID");
    }
}

1.2 核心源码

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface Cacheable {
    // 缓存KEY所在缓存的标识符，支持多个，CSV格式
    @AliasFor("cacheNames")
    String[] value() default {};
    // 缓存KEY所在缓存的标识符，支持多个，CSV格式
    @AliasFor("value")
    String[] cacheNames() default {};
    // 缓存的KEY，支持SpEL表达式动态计算
    // 默认为空(缺省按照方法的所有参数组合生成SimpleKey)
    String key() default "";
    // 缓存KEY生成器
    String keyGenerator() default "";
    // 缓存管理器
    String cacheManager() default "";
    // 缓存解析器
    String cacheResolver() default "";
    // 缓存的条件，使用SpEL表达式，方法调用前计算，当结果为true时执行动作
    // 默认为空，表示总是缓存方法返回值
    String condition() default "";
    // 否决缓存的条件，使用SpEL表达式，方法调用后计算（可使用result），当结果为true时不执行动作
    // 默认为空，表示永不否决；
    String unless() default "";
    // 使用异步模式标识
    boolean sync() default false;
}

二、@CachePut

注解作用：@CachePut 注解用于在方法执行后更新缓存。
注解属性：与@Cacheable相同。

• 简介：表示该方法执行后的结果需要更新到缓存；可作用于类和方法，作用于类上，则表示对该类的所有方法都有效；
• 执行逻辑：和Cacheable不同的是，带有CachePut注解的方法一定会被执行，方法执行后的结果由condition/unless判定是否存入缓存；

2.1 案例

@CachePut("books")
public Book updateBookDetails(String id, Book details) {
    // 业务逻辑
}
@Service
public class MyService {
    /**
     * 使用 @CachePut 所有属性的案例。
     *
     * @param user 用户对象，包含ID
     * @return 更新后的用户对象
     */
    @CachePut(
        value = "users",      // 缓存名称
        key = "#user.id",     // 缓存键，使用SpEL表达式
        condition = "#user.age > 18"  // 条件，只有当用户年龄大于18时才更新缓存
    )
    public User updateUserProfile(User user) {
        // 模拟更新用户信息的业务逻辑
        return performUpdate(user);
    }
    private User performUpdate(User user) {
        // 模拟更新逻辑
        user.setName("Updated Name");
        return user;
    }
}

2.2 核心源码

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface CachePut {
    // 缓存KEY所在缓存的标识符，支持多个，CSV格式
    @AliasFor("cacheNames")
    String[] value() default {};
    // 缓存KEY所在缓存的标识符，支持多个，CSV格式
    @AliasFor("value")
    String[] cacheNames() default {};
    // 缓存的KEY，可以为空(缺省按照方法的所有参数组合生成SimpleKey)；
    // 支持SpEL表达式
    String key() default "";
    // KEY的生成器
    String keyGenerator() default "";
    // 缓存管理器
    String cacheManager() default "";
    // 缓存解析器
    String cacheResolver() default "";
    // 放置缓存的条件，使用SpEL表达式，方法调用后计算（可使用result），当结果为true时执行动作
    // 默认为空，表示方法结果总是被缓存
    String condition() default "";
    // 否决放置缓存的条件，使用SpEL表达式，方法调用后计算（可使用result），当结果为true时不执行动作
    // 默认为空，表示永不否决；
    String unless() default "";
}

三、@CacheEvict

注解作用：@CacheEvict 注解用于在方法执行后清除缓存。

注解属性介绍：

• value 或 cacheNames: 指定缓存名称，可以是单个或多个；
• allEntries: 清除所有缓存项；
• condition: 指定清除缓存的条件SpEL表达式；

简介：表示清除该方法的缓存KEY对应的缓存；可作用于类和方法，作用于类上，则表示对该类的所有方法都有效；

3.1 案例

清除特定缓存名称的条目：

@CacheEvict("books")
public void deleteBook(String id) {
    // 业务逻辑
}

清除所有缓存名称的所有条目：

@CacheEvict(allEntries = true)
public void clearAllCaches() {
    // 业务逻辑
}

3.2 核心源码

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface CacheEvict {
    // 缓存KEY所在缓存的标识符，支持多个，CSV格式
    @AliasFor("cacheNames")
    String[] value() default {};
    // 缓存KEY所在缓存的标识符，支持多个，CSV格式
    @AliasFor("value")
    String[] cacheNames() default {};
    // 缓存的KEY，可以为空(缺省按照方法的所有参数组合生成SimpleKey)；
    // 支持SpEL表达式
    String key() default "";
    // KEY的生成器
    String keyGenerator() default "";
    // 缓存管理器
    String cacheManager() default "";
    // 缓存解析器
    String cacheResolver() default "";
    // 清除缓存的条件，使用SpEL表达式，执行次序由beforeInvocation()决定
    // 默认为空，表示总是清除缓存
    String condition() default "";
    // 删除缓存中所有条目标识
    // 默认为false，表示只删除指定KEY的值
    boolean allEntries() default false;
    // 方法调用前执行标识
    // 默认为false，表示方法成功调用（未抛出异常）后执行；为true则方法调用前执行
    boolean beforeInvocation() default false;
}

四、@Caching(不常用)

注解作用：@Caching 注解用于组合多个缓存操作。

注解属性介绍：

• value: 包含多个缓存操作的数组；
• 简介：表示多个Cache注解的组注解；可作用于类和方法，作用于类上，则表示对该类的所有方法都有效；

4.1 案例

@Caching(
    cacheable = {@Cacheable("books")},
    put = {@CachePut("books")},
    evict = {@CacheEvict("archivedBooks")}
)
public Book processBook(String id, Book details) {
    // 业务逻辑
}

4.2 核心源码

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface Caching {
    // Cacheable集合
     Cacheable[] cacheable() default {};
    // CachePut集合
     CachePut[] put() default {};
    // CacheEvict集合
     CacheEvict[] evict() default {};
}

五、@CacheConfig

注解作用：@CacheConfig 注解用于在类级别提供缓存相关的共享配置。

注解属性介绍：

• cacheNames: 指定类中所有缓存操作的默认缓存名称;
• keyGenerator: 指定默认的缓存键生成器;
• condition: 指定类中所有缓存操作的默认条件;
• 简介：提供在类层次上共享缓存相关配置的机制；只可作用于类上；

当作用在某个类上，会给这个类中定义的所有缓存动作提供默认配置，当然，具体缓存动作的配置可覆盖提供的默认配置；

5.1 案例

@CacheConfig(cacheNames = "books", keyGenerator = "customKeyGenerator")
public class BookService {
    // 类中的方法可以使用缓存注解
}

5.2 核心源码

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface CacheConfig {
    // 缓存KEY所在缓存的标识符，支持多个，CSV格式
    String[] cacheNames() default {};
    // KEY的生成器
    String keyGenerator() default "";
    // 缓存管理器
    String cacheManager() default "";
    // 缓存解析器
    String cacheResolver() default "";
}

六、@EnableCaching

简介：
表示启用Spring的注解驱动的缓存管理能力，和@Configuration配合使用；

必须创建CacheManager Bean，Spring框架不会提供默认值；@EnableCaching会根据类型搜索CacheManager Bean，因此CacheManager Bean的命名并不重要；
可以实现CachingConfigurer接口的cacheManager()方法来创建@EnableCaching指定的CacheManager Bean，这种情况下需要明确提供KeyGenerator（@EnableCaching会默认提供SimpleKeyGenerator）；如果不需要自定义，可以考虑从CachingConfigurerSupport扩展，它为所有方法提供了默认实现；

6.1 核心源码

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Import(CachingConfigurationSelector.class)
public @interface EnableCaching {
    // 代理模式：CGLIB or JDK Interface
    // 默认为false，表示基于JDK Interface
    // 设置为true，会影响所有需要代理的Spring管理的Bean
    boolean proxyTargetClass() default false;
    // 缓存应用模式：Proxy or AspectJ
    // Proxy模式只允许通过代理拦截调用，不会拦截同一类中的本地调用
    // AspectJ模式下，proxyTargetClass()无效，会拦截同一类中的本地调用
    AdviceMode mode() default AdviceMode.PROXY;
    // 特定连接点应用多个建议时，缓存操作的执行顺序
    int order() default Ordered.LOWEST_PRECEDENCE;
}