Spring Cache Annotations – Deep Dive

Caching is one of the most effective ways to improve performance in modern Spring Boot applications. Instead of writing manual cache logic, the Spring Framework provides a powerful cache abstraction that lets you control caching behavior using simple annotations.

What Is Spring Cache?

Spring Cache is a caching abstraction provided by the Spring Framework that helps you add caching to your application without mixing caching logic into your business code.

It allows you to:

• Separate caching from business logic
• Work with multiple cache providers
• Use annotations for declarative configuration

Spring itself does not store cache data. It only provides the abstraction layer.

It integrates with providers like:

• Redis – Distributed cache (shared across services)
• Caffeine – Local in-memory cache (inside JVM)
• EhCache
• Hazelcast

You only configure the provider. Your annotations remain the same.

How Spring Cache Works Internally

Spring caching is built on AOP (Aspect-Oriented Programming).

Spring creates a proxy around your bean. That proxy intercepts method calls and decides whether to:

• Return cached data
• Or execute the method

Execution Flow

Important concepts:

• Spring creates a proxy around your bean.
• The proxy intercepts methods annotated with cache annotations.
• On cache hit → method is NOT executed.
• On cache miss → method runs → result stored in cache.

Self-invocation does not trigger caching because proxy is bypassed.

Enable Caching in Spring Boot

If you're using Spring Boot, enabling caching is very simple.

Step 1: Add Dependency

For Redis (Distributed Cache)

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

For Caffeine (Local Cache)

<dependency>
  <groupId>com.github.ben-manes.caffeine</groupId>
  <artifactId>caffeine</artifactId>
</dependency>

Step 2: Enable Caching

@Configuration
@EnableCaching
public class CacheConfig {
}

That’s it. Spring caching is now active.

Core Spring Cache Annotations

When working with caching in Spring Boot, you mainly use four powerful annotations provided by the Spring Framework caching abstraction.

1. @Cacheable – Cache Method Results

Used mainly for read operations.

Behavior

• Checks cache first
• If value exists → return it
• If not → execute method → store result → return

Example

@Cacheable(value = "products", key = "#id")
public Product getProductById(Long id) {
    System.out.println("Fetching from DB...");
    return productRepository.findById(id).orElse(null);
}

What Happens?

First call:

Fetching from DB...

Second call:

No log printed. Returned directly from cache.

Important Attributes

Conditional Caching

Cache only when ID > 10:

@Cacheable(value = "products", condition = "#id > 10")

Avoid caching null results:

@Cacheable(value = "products", unless = "#result == null")

2. @CachePut – Always Update Cache

Used for update operations.

• Method always executes.
• Cache is updated with new value.

Example

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

Keeps cache synchronized after updates.

3. @CacheEvict – Remove Data from Cache

Used when:

• Deleting data
• Forcing refresh
• Invalidating stale data

Remove Specific Entry

@CacheEvict(value = "products", key = "#id")
public void deleteProduct(Long id) {
    productRepository.deleteById(id);
}

Clear Entire Cache

@CacheEvict(value = "products", allEntries = true)
public void clearCache() {
}

Evict Before Execution

@CacheEvict(value = "products", key = "#id", beforeInvocation = true)

Setting beforeInvocation = true ensures cache removal even if the method fails.

4. @Caching – Multiple Operations Together

Used when combining multiple cache behaviors in one method.

@Caching(
    put = @CachePut(value = "products", key = "#product.id"),
    evict = @CacheEvict(value = "productList", allEntries = true)
)
public Product updateProduct(Product product) {
    return productRepository.save(product);
}

Cache Key Strategy (Critical for Production)

When working with caching in Spring Boot, cache key design is one of the most important decisions you’ll make. A bad key strategy can silently break your system.

Poor key design leads to:

• Key collisions (different data stored under same key)
• Stale or overwritten data
• Difficult debugging in distributed systems
• Inconsistent behavior across environments

Default Key Behavior

If you don’t define a key manually, Spring generates one automatically.

• Single parameter → That parameter becomes the key
• Multiple parameters → Spring creates a SimpleKey object
• No parameters → SimpleKey.EMPTY

Example

@Cacheable("users")
public User getUser(String username, String role) {
    return userRepository.find(username, role);
}

Internally, Spring creates:

SimpleKey [username, role]

This works — but it’s not human-readable in Redis and harder to debug.

Custom Key (Recommended for Production)

Using SpEL (Spring Expression Language) gives you full control.

Example

@Cacheable(value = "users", key = "#username + '_' + #role")

Generated key:

users::john_ADMIN

Even Better (Business Prefixing)

@Cacheable(value = "users", key = "'user:' + #username + ':' + #role")

Generated key:

users::user:john:ADMIN

Custom Key Generator (Advanced Control)

If you want organization-wide key standardization:

@Bean
public KeyGenerator customKeyGenerator() {
    return (target, method, params) ->
            method.getName() + "_" + Arrays.toString(params);
}

Then use it:

@Cacheable(value = "users", keyGenerator = "customKeyGenerator")

When Should You Use This?

• Complex parameter objects
• Shared cache across microservices
• Large teams needing consistent naming
• Enterprise-level architecture standards

Preventing Cache Stampede

Cache stampede happens when:

• A cache entry expires
• Multiple requests hit the same endpoint
• All requests go to the database simultaneously
• Database gets overloaded

Very common in high-traffic e-commerce systems.

Spring Solution: sync = true

@Cacheable(value = "products", key = "#id", sync = true)
public Product getProduct(Long id) {
    return repository.findById(id).orElse(null);
}

This ensures only one thread loads data.

TTL Configuration (Provider Level)

Spring annotations do not control expiration. TTL is configured in the cache provider.

Example: Redis TTL

@Bean
public RedisCacheManager cacheManager(RedisConnectionFactory factory) {
    RedisCacheConfiguration config =
        RedisCacheConfiguration.defaultCacheConfig()
            .entryTtl(Duration.ofMinutes(10));

    return RedisCacheManager.builder(factory)
        .cacheDefaults(config)
        .build();
}

Best Practice for TTL

• Avoid infinite TTL for dynamic data
• Add small randomness (TTL jitter) to prevent mass expiration
• Tune TTL based on business logic (not guesswork)

Real-World Microservice Example

E-commerce Product Service

@Service
public class ProductService {

    @Cacheable(value = "products", key = "'product:' + #id", sync = true)
    public Product getById(Long id) {
        return repository.findById(id).orElse(null);
    }

    @CachePut(value = "products", key = "'product:' + #product.id")
    public Product update(Product product) {
        return repository.save(product);
    }

    @CacheEvict(value = "products", key = "'product:' + #id")
    public void delete(Long id) {
        repository.deleteById(id);
    }
}

Flow

• User requests product
• Cache checked
• Cache miss → DB hit → Result cached
• Product updated → Cache refreshed
• Product deleted → Cache entry removed

Common Mistakes to Avoid

When using Spring Boot, avoid these mistakes:

• Forgetting @EnableCaching – caching won’t work
• No TTL configuration (especially with Redis)
• Caching highly dynamic data
• Not evicting cache on update/delete
• Self-invocation (proxy bypass issue)
• No monitoring of hit/miss ratio

Best Practices for Production

• Use @Cacheable for read-heavy methods
• Use @CachePut for updates
• Use @CacheEvict on delete
• Configure proper TTL
• Use clear cache names
• Monitor performance metrics
• For scalable systems, combine Caffeine (local) + Redis (distributed)

Local vs Distributed Cache in Spring

Conclusion

Spring Cache Annotations provide a clean and powerful way to implement caching in Spring Boot applications.

Using @Cacheable, @CachePut, and @CacheEvict, you can improve performance, reduce database load, and keep data synchronized with minimal code.

When paired with providers like Caffeine (local) or Redis (distributed), Spring caching becomes production-ready and scalable.