Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 66 ยท Data Access

Caching

Speed up a Spring Boot app with @Cacheable and @CacheEvict, pick Caffeine or Redis, set TTLs, and avoid stale data, self-invocation bugs and cache stampedes.

The fastest database query is the one you never run. When the same expensive result is requested again and again (a product page, exchange rates, a permission lookup), you can keep the answer in memory and reuse it. That is caching, and it is one of the cheapest ways to make an application faster. It is also a classic source of bugs, because a cache is a second copy of your data, and two copies can disagree.

Spring Boot gives you a small, uniform abstraction: you annotate a method, and Spring wraps it so that repeated calls with the same arguments return the stored result. Behind the annotation sits a pluggable provider: a plain map for tests, Caffeine for an in-process cache, Redis for a cache shared by many instances. This lesson covers the annotations, the providers, time-to-live settings, and the three problems that bite everyone: stale data, calls that bypass the proxy, and the cache stampede. For the framework basics, see also Scheduling, Caching and Async.

Real Spring, Caffeine and Redis do not run on this site, so that code is read-only. The runnable examples are honest stand-ins: a proxy built with java.lang.reflect.Proxy that does what Spring's caching proxy does, and a concurrency demo of the stampede.

A cache is a shortcut with rules

Hit Answer from memory, no database call.
Miss Run the method, store the result.
Evict Remove entries when data changes.
Expire A TTL limits how stale data can get.
1 / 2

Turning caching on

Add the starter, then enable caching once with an annotation on any configuration class:

XML
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-cache</artifactId>
</dependency>
Java
@SpringBootApplication
@EnableCaching
public class ShopApplication {
    public static void main(String[] args) {
        SpringApplication.run(ShopApplication.class, args);
    }
}

Without @EnableCaching the annotations are silently ignored. That is the most common "my cache does nothing" bug. If no provider library is on the classpath, Boot falls back to a ConcurrentMapCache that never expires and never limits its size, which is fine for tests and dangerous in production.

The annotations

Java
@Service
public class ProductService {

    private final ProductRepository products;

    public ProductService(ProductRepository products) {
        this.products = products;
    }

    @Cacheable(cacheNames = "products", key = "#id")
    public Product findById(long id) {
        return products.findById(id).orElseThrow();
    }

    @CachePut(cacheNames = "products", key = "#result.id")
    public Product save(Product product) {
        return products.save(product);
    }

    @CacheEvict(cacheNames = "products", key = "#id")
    public void delete(long id) {
        products.deleteById(id);
    }

    @CacheEvict(cacheNames = "products", allEntries = true)
    public void clearAll() { }
}
  • @Cacheable checks the cache first. On a hit the method body never runs. On a miss it runs and the result is stored.
  • @CachePut always runs the method and stores the result. Use it on updates so the cache gets the new value.
  • @CacheEvict removes one entry (or everything with allEntries = true).
  • key is a SpEL expression (#id is the parameter). Without it, Spring builds a key from all arguments. condition decides before the call whether to cache at all; unless can look at #result, for example unless = "#result == null".
  • sync = true on @Cacheable makes concurrent callers for the same key wait for a single computation (more on that below).

Cache what is expensive, read often and changes rarely. Do not cache anything per-user unless the user is part of the key.

A cache key must identify everything the result depends on. findPrice(sku) cached by sku alone is wrong if the price depends on the customer's country. Put every relevant argument in the key, or the second user sees the first user's data.

How it works: a proxy

Spring does not change your class. At startup it creates a proxy object that implements the same type, wraps your bean, and puts the proxy in the container. Callers talk to the proxy; the proxy checks the cache, calls the real method on a miss and stores the answer. That one fact explains the biggest pitfall: only calls that go through the proxy are cached. A method that calls another method of the same object calls this, which is the raw object, and skips the cache. The same rule applies to @Transactional and @Async.

The first stand-in builds that proxy by hand. It has @Cacheable and @CacheEvict annotations, a time-to-live measured with a fake clock, and a hit and miss counter. Watch the database reads.

Java A caching proxy in plain Java

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

What is real: the proxy mechanism, annotations read by reflection, key building, a TTL and eviction. What is the stand-in: Spring's CacheInterceptor uses SpEL for keys and conditions, supports @CachePut, @Caching, sync, null handling and error handlers, and plugs in any CacheManager. Spring also proxies classes (not just interfaces) with generated subclasses; the pitfall is identical.

Step 2 shows stale data: the database changed, and the cache kept serving the old value until its entry expired or was evicted. Step 5 shows self-invocation. The fixes are to move the cached method into another bean and inject it, or to call the cached method from outside the class.

Providers and time-to-live

Caffeine (local)

XML
<dependency>
    <groupId>com.github.ben-manes.caffeine</groupId>
    <artifactId>caffeine</artifactId>
</dependency>
YAML
spring:
  cache:
    type: caffeine
    cache-names: products,rates
    caffeine:
      spec: maximumSize=1000,expireAfterWrite=10m

With Caffeine on the classpath Boot picks it automatically. maximumSize keeps memory bounded by evicting rarely used entries; expireAfterWrite is the TTL. This one is the right default for a single instance: no network, microsecond reads. The weakness is that each instance has its own copy, so after a write on instance A, instance B serves the old value until its TTL runs out.

Redis (shared)

XML
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
YAML
spring:
  cache:
    type: redis
    redis:
      time-to-live: 10m
      key-prefix: "shop::"
      cache-null-values: false
  data:
    redis:
      host: localhost

Every instance reads and writes the same entries, so an eviction on one is seen by all, and the cache survives restarts. The costs are a network hop (around a millisecond) and serialization: by default values are stored with Java serialization, so cached objects must implement Serializable. Most teams define a RedisCacheConfiguration bean that uses JSON instead, which is easier to read and survives class changes. The time-to-live setting applies to all caches; a bean can give each cache its own TTL. More about the Redis client itself is in Spring Data Redis.

Always set a limit

Whatever you pick, choose a TTL and, for local caches, a maximum size. A cache with neither grows forever and serves data forever. The TTL is also your worst-case staleness budget: if you cache prices for ten minutes, a price change can take ten minutes to appear, even with perfect eviction on one instance.

Stale data and keeping the cache honest

  • Evict on write. Every method that changes cached data should @CacheEvict or @CachePut the matching key. Missing one is the usual cause of "users see old data".
  • Evict after commit. If an evicting method runs inside a transaction that later rolls back, the cache was cleared for nothing; if it evicts and a concurrent read repopulates from the not-yet-committed old data, you cache the stale row again. For critical data, evict from a @TransactionalEventListener(phase = AFTER_COMMIT).
  • Do not cache failures or empties by accident. Use unless = "#result == null" if "not found" may become "found" soon.
  • Cache immutable data in preference. Currency lists, country names and feature definitions are ideal. Frequently updated, per-user data is not.
  • Never cache secrets or permissions for long. A revoked permission that stays valid for ten minutes can be a security bug.

The cache stampede

Imagine a hot key: the home page data that a thousand requests per second ask for. Its entry expires. In the instant before one request refills it, hundreds of requests all see a miss, and all hundreds hit the database with the same expensive query. The database slows down, the refills take longer, more requests miss, and the pile-up gets worse. This is a cache stampede (or thundering herd).

@Cacheable(sync = true) is the first remedy: for a given key, only one caller computes the value and the others wait for it. It works with providers that support it, such as Caffeine, and applies per instance. Other remedies include refreshing popular entries before they expire (Caffeine's refreshAfterWrite), adding a little random jitter to TTLs so keys do not all expire together, and serving a slightly stale value while one thread refreshes.

The second stand-in forces a stampede on purpose. A barrier makes eight threads reach the loader at the same moment, so the naive "check, load, put" version loads eight times. The synchronized version uses the map's atomic computeIfAbsent, which is what sync = true does in spirit.

Java Eight threads, one hot key

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

What is real: the race itself, which is how an expired hot key behaves under load. What is the stand-in: the barrier replaces real query latency to make the result repeatable, and computeIfAbsent stands in for Spring's sync = true handling, which delegates to the provider's loading support.

Testing and troubleshooting

  • Verify the cache is used. Assert in a test that a mock repository was called once after two service calls. If it was called twice, check @EnableCaching, that the call goes through the proxy, and that the key is what you think.
  • Isolate tests. Because a cache keeps state, one test can affect the next. Clear it in a @BeforeEach with cacheManager.getCache("products").clear() or disable caching with spring.cache.type=none in the test profile.
  • Look at the numbers. Expose cache.gets (hit and miss) through Micrometer; a cache with a low hit ratio is only costing memory.
  • Measure first. Cache the proven bottleneck, not every method. A cache you cannot explain is a future bug.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You annotated a method with @Cacheable, but it runs on every call. What should you check first?

    Without @EnableCaching the annotation is ignored, and a call from inside the same class bypasses the proxy, so nothing is cached.
  2. 2. What does @CachePut do that @Cacheable does not?

    CachePut never skips the call; it refreshes the cache entry with the return value, which suits update methods.
  3. 3. Why is a Caffeine cache risky with three application instances behind a load balancer?

    A local cache is per process. Use a short TTL, accept the staleness, or use a shared cache such as Redis.
  4. 4. What is a cache stampede and which setting helps?

    When a popular entry expires, every concurrent request misses and queries the database. sync = true serializes the loading per key.
  5. 5. What must a cache key include?

    A key that omits an input makes different callers share one entry and leaks wrong or private data.

Summary

  • Add spring-boot-starter-cache and @EnableCaching; then @Cacheable, @CachePut and @CacheEvict control reads, updates and removals.
  • Caching works through a proxy, so self-invocation and non-public methods skip it.
  • Caffeine is a fast in-process cache; Redis is shared across instances; the default map has no expiry.
  • Always set a TTL and a maximum size, evict on every write path, and put everything the result depends on into the key.
  • Protect hot keys from stampedes with sync = true, refresh-ahead and TTL jitter.

Next: Spring Data MongoDB, Redis and Other Stores.