Master Multi‑Level Caching in Java with JetCache: A Complete Spring Boot Guide

1. Introduction to JetCache

JetCache is an open‑source Java caching framework from Alibaba that supports local, remote and multi‑level caches, offering simple integration with Spring Cache, cache pre‑warming, key prefixes, and other features.

Official site: https://github.com/alibaba/jetcache

2. Adding JetCache to a Spring Boot project

Include the jetcache-starter-redis dependency (Spring Boot 2.6.13) and, for JetCache 2.7.x, also add the jedis dependency.

<dependency>
    <groupId>com.alicp.jetcache</groupId>
    <artifactId>jetcache-starter-redis</artifactId>
    <version>2.7.0</version>
</dependency>
<!-- additional jedis for 2.7.x -->
<dependency>
    <groupId>redis.clients</groupId>
    <artifactId>jedis</artifactId>
    <version>4.3.1</version>
</dependency>

Configure JetCache in application.yml (or application.properties) to set statistics interval, local cache type, key converter, remote Redis settings, thread pool, etc.

jetcache:
  statIntervalMinutes: 15
  areaInCacheName: false
  local:
    default:
      type: linkedhashmap
      keyConvertor: fastjson
  remote:
    default:
      type: redis
      keyConvertor: fastjson
      broadcastChannel: projectA
      valueEncoder: java
      valueDecoder: java
      poolConfig:
        minIdle: 5
        maxIdle: 20
        maxTotal: 50
      host: 127.0.0.1
      port: 6379

3. Enable JetCache annotations

Add @EnableCreateCacheAnnotation and

@EnableMethodCache(basePackages = "com.example.jetcachedemo")

to the Spring Boot main class.

4. Using JetCache in code

Three ways to cache:

AOP mode – annotate methods with @Cached, @CacheUpdate, @CacheInvalidate.

API mode – use @CreateCache (deprecated in 2.7).

Advanced API – obtain a Cache<K,V> from CacheManager and operate directly.

Example controller methods for remote, local and both cache types:

@RestController
@RequestMapping("user")
public class UserController {

    @GetMapping("getRemote")
    @Cached(name="userCache:", key="#id", expire=3600, timeUnit=TimeUnit.SECONDS, cacheType=CacheType.REMOTE)
    public User getRemote(Long id) { /* ... */ }

    @GetMapping("getLocal")
    @Cached(name="userCache:", key="#id", expire=3600, timeUnit=TimeUnit.SECONDS, cacheType=CacheType.LOCAL)
    public User getLocal(Long id) { /* ... */ }

    @GetMapping("getBoth")
    @Cached(name="userCache:", key="#id", expire=3600, timeUnit=TimeUnit.SECONDS, cacheType=CacheType.BOTH)
    public User getBoth(Long id) { /* ... */ }

    @PostMapping("updateUser")
    @CacheUpdate(name="userCache:", key="#user.id", value="#user")
    public Boolean updateUser(@RequestBody User user) { /* ... */ }

    @PostMapping("deleteUser")
    @CacheInvalidate(name="userCache:", key="#id")
    public Boolean deleteUser(Long id) { /* ... */ }
}

The User class must implement Serializable.

5. Testing

Call the endpoints (e.g., GET /user/getRemote?id=1) and observe that the data is stored in Redis; subsequent calls hit the cache. Switching the cache type to LOCAL stores data only in the local cache, which can be verified with a Redis client.

6. Common issues

Missing fastjson dependency leads to ClassNotFoundException: com.alibaba.fastjson.JSON.

JetCache 2.7.x requires the jedis client; otherwise NoClassDefFoundError: redis/clients/jedis/UnifiedJedis occurs.

Adjust the JetCache version or add the required dependencies to resolve.