【JetCache】JetCache的配置说明和注解属性说明

以你之姓@ 2023-09-30 14:14 54阅读 0赞

**本文目录**

一、配置说明

二、注解属性说明

--------------------

## 一、配置说明 ##

yml配置文件案例（如果没使用springboot，直接配置GlobalCacheConfig是类似的，参考快速入门教程）：

jetcache:
      statIntervalMinutes: 15
      areaInCacheName: false
      hidePackages: com.alibaba
      local:
        default:
          type: caffeine
          limit: 100
          keyConvertor: fastjson
          expireAfterWriteInMillis: 100000
        otherArea:
          type: linkedhashmap
          limit: 100
          keyConvertor: none
          expireAfterWriteInMillis: 100000
      remote:
        default:
          type: redis
          keyConvertor: fastjson
          valueEncoder: java
          valueDecoder: java
          poolConfig:
            minIdle: 5
            maxIdle: 20
            maxTotal: 50
          host: ${redis.host}
          port: ${redis.port}
        otherArea:
          type: redis
          keyConvertor: fastjson
          valueEncoder: kryo
          valueDecoder: kryo
          poolConfig:
            minIdle: 5
            maxIdle: 20
            maxTotal: 50
          host: ${redis.host}
          port: ${redis.port}

配置通用说明如下：

<table> 
 <thead> 
  <tr> 
   <th style="width:289px;">属性</th> 
   <th style="width:72px;">默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td style="width:289px;">jetcache.statIntervalMinutes</td> 
   <td style="width:72px;">0</td> 
   <td>统计间隔，0表示不统计</td> 
  </tr> 
  <tr> 
   <td style="width:289px;">jetcache.areaInCacheName</td> 
   <td style="width:72px;">true</td> 
   <td>jetcache-anno把cacheName作为远程缓存key前缀，2.4.3以前的版本总是把areaName加在cacheName中，因此areaName也出现在key前缀中。2.4.4以后可以配置，为了保持远程key兼容默认值为true，但是新项目的话false更合理些。</td> 
  </tr> 
  <tr> 
   <td style="width:289px;">jetcache.hiddenPackages</td> 
   <td style="width:72px;">无</td> 
   <td>@Cached和@CreateCache自动生成name的时候，为了不让name太长，hiddenPackages指定的包名前缀被截掉</td> 
  </tr> 
  <tr> 
   <td style="width:289px;">jetcache.[local|remote].${area}.type</td> 
   <td style="width:72px;">无</td> 
   <td>缓存类型。tair、redis为当前支持的远程缓存；linkedhashmap、caffeine为当前支持的本地缓存类型</td> 
  </tr> 
  <tr> 
   <td style="width:289px;">jetcache.[local|remote].${area}.keyConvertor</td> 
   <td style="width:72px;">无</td> 
   <td>key转换器的全局配置，当前只有一个已经实现的keyConvertor：<code>fastjson</code>。仅当使用@CreateCache且缓存类型为LOCAL时可以指定为<code>none</code>，此时通过equals方法来识别key。方法缓存必须指定keyConvertor</td> 
  </tr> 
  <tr> 
   <td style="width:289px;">jetcache.[local|remote].${area}.valueEncoder</td> 
   <td style="width:72px;">java</td> 
   <td>序列化器的全局配置。仅remote类型的缓存需要指定，可选java和kryo</td> 
  </tr> 
  <tr> 
   <td style="width:289px;">jetcache.[local|remote].${area}.valueDecoder</td> 
   <td style="width:72px;">java</td> 
   <td>序列化器的全局配置。仅remote类型的缓存需要指定，可选java和kryo</td> 
  </tr> 
  <tr> 
   <td style="width:289px;">jetcache.[local|remote].${area}.limit</td> 
   <td style="width:72px;">100</td> 
   <td>每个缓存实例的最大元素的全局配置，仅local类型的缓存需要指定。注意是每个缓存实例的限制，而不是全部，比如这里指定100，然后用@CreateCache创建了两个缓存实例（并且注解上没有设置localLimit属性），那么每个缓存实例的限制都是100</td> 
  </tr> 
  <tr> 
   <td style="width:289px;">jetcache.[local|remote].${area}.expireAfterWriteInMillis</td> 
   <td style="width:72px;">无穷大</td> 
   <td>以毫秒为单位指定超时时间的全局配置(以前为defaultExpireInMillis)</td> 
  </tr> 
  <tr> 
   <td style="width:289px;">jetcache.local.${area}.expireAfterAccessInMillis</td> 
   <td style="width:72px;">0</td> 
   <td>需要jetcache2.2以上，以毫秒为单位，指定多长时间没有访问，就让缓存失效，当前只有本地缓存支持。0表示不使用这个功能。</td> 
  </tr> 
 </tbody> 
</table>

上表中$\{area\}对应@Cached和@CreateCache的area属性。注意如果注解上没有指定area，默认值是"default"。

关于缓存的超时时间，有多个地方指定，澄清说明一下：

1.  put等方法上指定了超时时间，则以此时间为准
2.  put等方法上未指定超时时间，使用Cache实例的默认超时时间
3.  Cache实例的默认超时时间，通过在@CreateCache和@Cached上的expire属性指定，如果没有指定，使用yml中定义的全局配置，例如@Cached(cacheType=local)使用jetcache.local.default.expireAfterWriteInMillis，如果仍未指定则是无穷大

## 二、注解属性说明 ##

JetCache方法缓存和SpringCache比较类似，它原生提供了TTL支持，以保证最终一致，并且支持二级缓存。JetCache2.4以后支持基于注解的缓存更新和删除。

在spring环境下，使用@Cached注解可以为一个方法添加缓存，@CacheUpdate用于更新缓存，@CacheInvalidate用于移除缓存元素。注解可以加在接口上也可以加在类上，加注解的类必须是一个spring bean，例如：

public interface UserService {
        @Cached(name="userCache.", key="#userId", expire = 3600)
        User getUserById(long userId);
    
        @CacheUpdate(name="userCache.", key="#user.userId", value="#user")
        void updateUser(User user);
    
        @CacheInvalidate(name="userCache.", key="#userId")
        void deleteUser(long userId);
    }

key使用Spring的[SpEL][]脚本来指定。如果要使用参数名（比如这里的`key="#userId"`），项目编译设置target必须为1.8格式，并且指定javac的-parameters参数，否则就要使用`key="args[0]"`这样按下标访问的形式。

@CacheUpdate和@CacheInvalidate的name和area属性必须和@Cached相同，name属性还会用做cache的key前缀。

@Cached注解和@CreateCache的属性非常类似，但是多几个：

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>area</td> 
   <td>“default”</td> 
   <td>如果在配置中配置了多个缓存area，在这里指定使用哪个area</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>未定义</td> 
   <td>指定缓存的唯一名称，不是必须的，如果没有指定，会使用类名+方法名。name会被用于远程缓存的key前缀。另外在统计中，一个简短有意义的名字会提高可读性。</td> 
  </tr> 
  <tr> 
   <td>key</td> 
   <td>未定义</td> 
   <td>使用<a href="https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html" title="SpEL" rel="nofollow">SpEL</a>指定key，如果没有指定会根据所有参数自动生成。</td> 
  </tr> 
  <tr> 
   <td>expire</td> 
   <td>未定义</td> 
   <td>超时时间。如果注解上没有定义，会使用全局配置，如果此时全局配置也没有定义，则为无穷大</td> 
  </tr> 
  <tr> 
   <td>timeUnit</td> 
   <td>TimeUnit.SECONDS</td> 
   <td>指定expire的单位</td> 
  </tr> 
  <tr> 
   <td>cacheType</td> 
   <td>CacheType.REMOTE</td> 
   <td>缓存的类型，包括CacheType.REMOTE、CacheType.LOCAL、CacheType.BOTH。如果定义为BOTH，会使用LOCAL和REMOTE组合成两级缓存</td> 
  </tr> 
  <tr> 
   <td>localLimit</td> 
   <td>未定义</td> 
   <td>如果cacheType为LOCAL或BOTH，这个参数指定本地缓存的最大元素数量，以控制内存占用。如果注解上没有定义，会使用全局配置，如果此时全局配置也没有定义，则为100</td> 
  </tr> 
  <tr> 
   <td>localExpire</td> 
   <td>未定义</td> 
   <td>仅当cacheType为BOTH时适用，为内存中的Cache指定一个不一样的超时时间，通常应该小于expire</td> 
  </tr> 
  <tr> 
   <td>serialPolicy</td> 
   <td>未定义</td> 
   <td>指定远程缓存的序列化方式。可选值为SerialPolicy.JAVA和SerialPolicy.KRYO。如果注解上没有定义，会使用全局配置，如果此时全局配置也没有定义，则为SerialPolicy.JAVA</td> 
  </tr> 
  <tr> 
   <td>keyConvertor</td> 
   <td>未定义</td> 
   <td>指定KEY的转换方式，用于将复杂的KEY类型转换为缓存实现可以接受的类型，当前支持KeyConvertor.FASTJSON和KeyConvertor.NONE。NONE表示不转换，FASTJSON可以将复杂对象KEY转换成String。如果注解上没有定义，会使用全局配置。</td> 
  </tr> 
  <tr> 
   <td>enabled</td> 
   <td>true</td> 
   <td>是否激活缓存。例如某个dao方法上加缓存注解，由于某些调用场景下不能有缓存，所以可以设置enabled为false，正常调用不会使用缓存，在需要的地方可使用CacheContext.enableCache在回调中激活缓存，缓存激活的标记在ThreadLocal上，该标记被设置后，所有enable=false的缓存都被激活</td> 
  </tr> 
  <tr> 
   <td>cacheNullValue</td> 
   <td>false</td> 
   <td>当方法返回值为null的时候是否要缓存</td> 
  </tr> 
  <tr> 
   <td>condition</td> 
   <td>未定义</td> 
   <td>使用<a href="https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html" title="SpEL" rel="nofollow">SpEL</a>指定条件，如果表达式返回true的时候才去缓存中查询</td> 
  </tr> 
  <tr> 
   <td>postCondition</td> 
   <td>未定义</td> 
   <td>使用<a href="https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html" title="SpEL" rel="nofollow">SpEL</a>指定条件，如果表达式返回true的时候才更新缓存，该评估在方法执行后进行，因此可以访问到#result</td> 
  </tr> 
 </tbody> 
</table>

@CacheInvalidate注解说明：

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>area</td> 
   <td>“default”</td> 
   <td>如果在配置中配置了多个缓存area，在这里指定使用哪个area，指向对应的@Cached定义。</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>未定义</td> 
   <td>指定缓存的唯一名称，指向对应的@Cached定义。</td> 
  </tr> 
  <tr> 
   <td>key</td> 
   <td>未定义</td> 
   <td>使用<a href="https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html" title="SpEL" rel="nofollow">SpEL</a>指定key</td> 
  </tr> 
  <tr> 
   <td>condition</td> 
   <td>未定义</td> 
   <td>使用<a href="https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html" title="SpEL" rel="nofollow">SpEL</a>指定条件，如果表达式返回true才执行删除，可访问方法结果#result</td> 
  </tr> 
 </tbody> 
</table>

@CacheUpdate注解说明：

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>area</td> 
   <td>“default”</td> 
   <td>如果在配置中配置了多个缓存area，在这里指定使用哪个area，指向对应的@Cached定义。</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>未定义</td> 
   <td>指定缓存的唯一名称，指向对应的@Cached定义。</td> 
  </tr> 
  <tr> 
   <td>key</td> 
   <td>未定义</td> 
   <td>使用<a href="https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html" title="SpEL" rel="nofollow">SpEL</a>指定key</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>未定义</td> 
   <td>使用<a href="https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html" title="SpEL" rel="nofollow">SpEL</a>指定value</td> 
  </tr> 
  <tr> 
   <td>condition</td> 
   <td>未定义</td> 
   <td>使用<a href="https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html" title="SpEL" rel="nofollow">SpEL</a>指定条件，如果表达式返回true才执行更新，可访问方法结果#result</td> 
  </tr> 
 </tbody> 
</table>

使用@CacheUpdate和@CacheInvalidate的时候，相关的缓存操作可能会失败（比如网络IO错误），所以指定缓存的超时时间是非常重要的。

@CacheRefresh注解说明：

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>refresh</td> 
   <td>未定义</td> 
   <td>刷新间隔</td> 
  </tr> 
  <tr> 
   <td>timeUnit</td> 
   <td>TimeUnit.SECONDS</td> 
   <td>时间单位</td> 
  </tr> 
  <tr> 
   <td>stopRefreshAfterLastAccess</td> 
   <td>未定义</td> 
   <td>指定该key多长时间没有访问就停止刷新，如果不指定会一直刷新</td> 
  </tr> 
  <tr> 
   <td>refreshLockTimeout</td> 
   <td>60秒</td> 
   <td>类型为BOTH/REMOTE的缓存刷新时，同时只会有一台服务器在刷新，这台服务器会在远程缓存放置一个分布式锁，此配置指定该锁的超时时间</td> 
  </tr> 
 </tbody> 
</table>

@CachePenetrationProtect注解：

当缓存访问未命中的情况下，对并发进行的加载行为进行保护。 当前版本实现的是单JVM内的保护，即同一个JVM中同一个key只有一个线程去加载，其它线程等待结果。

对于以上未定义默认值的参数，如果没有指定，将使用yml中指定的全局配置，全局配置请参考[配置说明][Link 1]。

完结！

[SpEL]: https://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/expressions.html
[Link 1]: https://github.com/alibaba/jetcache/wiki/Config_CN