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

Attribute	Meaning
value	Cache name
key	Custom cache key (SpEL expression)
condition	Cache only if condition is true
unless	Skip caching if condition is true
sync	Prevent cache stampede

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

Feature	Caffeine (Local Cache)	Redis (Distributed Cache)
Location	Inside JVM memory	External server
Shared Across Services	No	Yes
Speed	Ultra-fast (no network call)	Very fast (network-based)
Best For	Single service optimization	Scalable microservices

---

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.