Spring Boot Caching with Redis: From Concept to Production

<dependencies>
    <!-- Redis client and template support -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>
    <!-- Cache abstraction — @Cacheable, @CachePut, @CacheEvict -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-cache</artifactId>
    </dependency>
    <!-- Actuator for /actuator/caches and /actuator/metrics/cache.gets -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <!-- Configuration metadata for IDE autocomplete on @ConfigurationProperties -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

package io.thecodeforge.cache.service;

import io.thecodeforge.cache.model.Product;
import org.springframework.cache.annotation.CacheEvict;
import org.springframework.cache.annotation.CachePut;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;

@Service
public class ForgeProductService {

    /**
     * condition gates entry into caching logic entirely — evaluated BEFORE method execution.
     * Negative condition means: if id <= 0, skip the cache check AND skip storing the result.
     *
     * unless filters the result AFTER method execution.
     * unless = "#result == null" means: execute the method, but if it returned null, do not cache it.
     *
     * Both can and should be used together when the input domain has invalid ranges
     * AND the output can legitimately be absent.
     */
    @Cacheable(
        value = "products",
        key = "#id",
        unless = "#result == null",
        condition = "#id > 0"
    )
    public Product getProductById(Long id) {
        simulateDatabaseRoundTrip();
        return new Product(id, "Forge Industrial Drill", 149.50);
    }

    /**
     * @CacheEvict removes the cached entry for this product ID.
     * The next read for this ID will be a cache miss and will re-fetch from the database.
     * Use when write cost is low and you are comfortable with one post-update cache miss.
     */
    @CacheEvict(value = "products", key = "#product.id")
    public void updateProduct(Product product) {
        persistToDatabase(product);
    }

    /**
     * @CachePut always executes the method AND updates the cache with the return value.
     * The next read for this ID is a guaranteed cache hit — zero miss penalty after update.
     * More expensive on write than @CacheEvict, but the right choice in read-heavy systems.
     */
    @CachePut(value = "products", key = "#product.id", unless = "#result == null")
    public Product updateAndRefreshProduct(Product product) {
        persistToDatabase(product);
        return product;
    }

    /**
     * allEntries = true is a nuclear option — evicts everything in the products namespace.
     * Use only for admin-triggered bulk invalidations, not on hot paths.
     * Every subsequent read until the cache warms up will be a DB hit.
     */
    @CacheEvict(value = "products", allEntries = true)
    public void clearAllProductCache() {
        // Method body intentionally empty — the annotation does all the work.
    }

    private void simulateDatabaseRoundTrip() {
        try {
            Thread.sleep(2000);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    private void persistToDatabase(Product product) {
        // Database persistence logic
    }
}

package io.thecodeforge.cache.config;

import org.springframework.cache.CacheManager;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.cache.RedisCacheConfiguration;
import org.springframework.data.redis.cache.RedisCacheManager;
import org.springframework.data.redis.connection.RedisConnectionFactory;
import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer;
import org.springframework.data.redis.serializer.RedisSerializationContext;
import org.springframework.data.redis.serializer.StringRedisSerializer;
import java.time.Duration;
import java.util.HashMap;
import java.util.Map;

@Configuration
@EnableCaching
public class ForgeRedisConfig {

    @Bean
    public CacheManager cacheManager(RedisConnectionFactory factory) {
        /*
         * Base configuration applied to all caches unless explicitly overridden.
         * Key serializer: String (human-readable in Redis CLI)
         * Value serializer: JSON (human-readable, cross-platform, tolerates schema evolution)
         * Null values: disabled — prevents caching the absence of data
         * Default TTL: 2 hours — safety net for caches not explicitly configured below
         */
        RedisCacheConfiguration defaultConfig = RedisCacheConfiguration.defaultCacheConfig()
            .entryTtl(Duration.ofHours(2))
            .disableCachingNullValues()
            .serializeKeysWith(
                RedisSerializationContext.SerializationPair.fromSerializer(
                    new StringRedisSerializer()
                )
            )
            .serializeValuesWith(
                RedisSerializationContext.SerializationPair.fromSerializer(
                    new GenericJackson2JsonRedisSerializer()
                )
            );

        /*
         * Per-cache TTL overrides.
         * Each entry creates a named cache with its own expiry window.
         * Caches not listed here use the defaultConfig TTL of 2 hours.
         *
         * TTL rationale:
         *   products     — 30 min: changes infrequently but reads are very high volume
         *   categories   — 6 hours: nearly static, catalog restructuring is rare
         *   userSessions — 15 min: must reflect permission changes quickly for security
         *   searchResults — 5 min: high variability, acceptable to serve slightly stale
         */
        Map<String, RedisCacheConfiguration> cacheConfigs = new HashMap<>();
        cacheConfigs.put("products",      defaultConfig.entryTtl(Duration.ofMinutes(30)));
        cacheConfigs.put("categories",    defaultConfig.entryTtl(Duration.ofHours(6)));
        cacheConfigs.put("userSessions",  defaultConfig.entryTtl(Duration.ofMinutes(15)));
        cacheConfigs.put("searchResults", defaultConfig.entryTtl(Duration.ofMinutes(5)));

        return RedisCacheManager.builder(factory)
            .cacheDefaults(defaultConfig)
            .withInitialCacheConfigurations(cacheConfigs)
            .transactionAware()  // Cache writes roll back when the surrounding DB transaction rolls back
            .build();
    }
}

package io.thecodeforge.cache.service;

import io.thecodeforge.cache.model.Product;
import io.thecodeforge.cache.model.ProductSummary;
import org.springframework.cache.annotation.CacheConfig;
import org.springframework.cache.annotation.CacheEvict;
import org.springframework.cache.annotation.CachePut;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.cache.annotation.Caching;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.stream.Collectors;

/**
 * @CacheConfig declares the default cache name for all annotations in this class.
 * Eliminates the value = "products" repetition on every annotation.
 * Methods can still override with an explicit value when needed.
 */
@Service
@CacheConfig(cacheNames = "products")
public class ForgeProductServiceAdvanced {

    // Read: check cache first, skip method on hit
    @Cacheable(key = "#id", unless = "#result == null")
    public Product getProductById(Long id) {
        return fetchFromDatabase(id);
    }

    // Read: cache the entire list under a fixed key
    // unless condition prevents caching an empty list that may be a transient state
    @Cacheable(key = "'list:all'", unless = "#result == null || #result.isEmpty()")
    public List<ProductSummary> getAllProducts() {
        return fetchAllFromDatabase().stream()
            .map(p -> new ProductSummary(p.getId(), p.getName()))
            .collect(Collectors.toList());
    }

    // Update: always execute, update detail cache — zero miss penalty on next detail read
    // Does NOT touch the list cache — use updateProductAndClearList when list must also be fresh
    @CachePut(key = "#product.id")
    public Product updateProduct(Product product) {
        saveToDatabase(product);
        return product;
    }

    /**
     * The correct update pattern when an entity appears in multiple cache namespaces:
     * - @CachePut on the detail cache: next detail read is a guaranteed hit
     * - @CacheEvict on the list cache: next list read re-fetches from DB (list is rebuilt fresh)
     *
     * Why evict the list instead of put? Rebuilding a list cache entry requires fetching
     * all items from the database — too expensive to do on every single product update.
     * Accept one list cache miss per update; pay the DB cost once to get a fresh list.
     */
    @Caching(
        put = { @CachePut(key = "#product.id") },
        evict = { @CacheEvict(key = "'list:all'") }
    )
    public Product updateProductAndClearList(Product product) {
        saveToDatabase(product);
        return product;
    }

    // Delete: remove detail cache entry, let next read re-fetch or confirm absence
    @CacheEvict(key = "#id")
    public void deleteProduct(Long id) {
        deleteFromDatabase(id);
    }

    // Nuclear option: clears the entire products namespace
    // Every subsequent read is a DB hit until the cache warms up — use with intent
    @CacheEvict(allEntries = true)
    public void clearEntireCache() {
        // Intentionally empty — annotation handles the eviction
    }

    private Product fetchFromDatabase(Long id) {
        return new Product(id, "Forge Industrial Drill", 149.50);
    }

    private List<Product> fetchAllFromDatabase() {
        return List.of(
            new Product(1L, "Forge Drill", 149.50),
            new Product(2L, "Forge Wrench", 29.99)
        );
    }

    private void saveToDatabase(Product product) { /* persistence logic */ }
    private void deleteFromDatabase(Long id) { /* deletion logic */ }
}

package io.thecodeforge.cache.config;

import org.springframework.cache.interceptor.KeyGenerator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.lang.reflect.Method;
import java.util.Arrays;
import java.util.stream.Collectors;

@Configuration
public class ForgeKeyGeneratorConfig {

    /**
     * Custom key generator that prefixes every cache key with the class name and method name.
     * Prevents cache key collisions between methods that have identical parameter signatures.
     *
     * Key format: ClassName:methodName:[param1, param2, ...]
     * Example: ForgeProductService:getProductById:[42]
     *
     * Reference this generator in annotations: @Cacheable(keyGenerator = "forgeKeyGenerator")
     * Or set it as the global default in RedisCacheManager if you want it applied everywhere.
     */
    @Bean("forgeKeyGenerator")
    public KeyGenerator forgeKeyGenerator() {
        return (Object target, Method method, Object... params) -> {
            String className = target.getClass().getSimpleName();
            String methodName = method.getName();

            // Handle zero-parameter methods cleanly
            String paramsPart = (params == null || params.length == 0)
                ? "no-args"
                : Arrays.stream(params)
                    .map(p -> p == null ? "null" : p.toString())
                    .collect(Collectors.joining(",", "[", "]"));

            return className + ":" + methodName + ":" + paramsPart;
        };
    }
}

spring:
  cache:
    type: redis
  redis:
    host: ${REDIS_HOST:localhost}
    port: ${REDIS_PORT:6379}
    password: ${REDIS_PASSWORD:}
    timeout: 2000ms
    lettuce:
      pool:
        max-active: 16    # Increase from default 8 — exhausts fast under burst traffic
        max-idle: 8
        min-idle: 4
        max-wait: 2000ms  # Fail fast: threads wait max 2s for a connection, then get an exception

management:
  endpoints:
    web:
      exposure:
        # Expose the endpoints needed for cache observability
        include: caches, metrics, health, info
  metrics:
    cache:
      instrument: true  # Required to enable cache.gets, cache.puts, cache.evictions metrics
    export:
      prometheus:
        enabled: true   # Scrape-ready for Prometheus — pair with Grafana for dashboards
  endpoint:
    health:
      show-details: always  # Shows Redis connectivity status in health response

package io.thecodeforge.cache.service;

import io.thecodeforge.cache.model.Product;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.cache.Cache;
import org.springframework.cache.CacheManager;
import org.springframework.stereotype.Service;

/**
 * Demonstrates explicit cache interaction with graceful fallback.
 *
 * This pattern is used when you need finer control than @Cacheable provides —
 * for example, when you want to handle Redis failures differently per method,
 * or when you want to log cache miss reasons at different severity levels.
 *
 * For simpler cases, configure a CacheErrorHandler bean that Spring Boot
 * calls automatically on cache exceptions without removing the @Cacheable annotation.
 */
@Service
public class ForgeResilientProductService {

    private static final Logger log = LoggerFactory.getLogger(ForgeResilientProductService.class);
    private static final String PRODUCTS_CACHE = "products";

    private final CacheManager cacheManager;
    private final ForgeProductRepository productRepository;

    public ForgeResilientProductService(
        CacheManager cacheManager,
        ForgeProductRepository productRepository
    ) {
        this.cacheManager = cacheManager;
        this.productRepository = productRepository;
    }

    public Product getProductWithFallback(Long id) {
        try {
            Cache cache = cacheManager.getCache(PRODUCTS_CACHE);
            if (cache != null) {
                Cache.ValueWrapper wrapper = cache.get(id);
                if (wrapper != null && wrapper.get() != null) {
                    return (Product) wrapper.get();
                }
            }

            // Cache miss — fetch from database
            Product product = productRepository.findById(id).orElse(null);

            // Only cache non-null results — do not cache absence
            if (cache != null && product != null) {
                try {
                    cache.put(id, product);
                } catch (Exception writeEx) {
                    // Redis write failure should not fail the request
                    // The data was fetched successfully — return it even without caching
                    log.warn("Redis write failed for products::{} — serving DB result without caching",
                        id, writeEx);
                }
            }

            return product;

        } catch (Exception readEx) {
            // Redis is completely unreachable — skip cache, go directly to DB
            log.warn("Redis unavailable, falling back to direct DB access for product id={}",
                id, readEx);
            return productRepository.findById(id).orElse(null);
        }
    }
}

services:
  redis:
    image: redis:7.2-alpine  # Pin to a specific minor version — alpine for smaller image footprint
    ports:
      - "6379:6379"
    command: >
      redis-server
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
      --appendonly yes
      --appendfsync everysec
    volumes:
      - redis-data:/data  # Persist data across docker-compose restarts
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 5s

  redis-commander:
    # Web UI for browsing cached keys and inspecting JSON values during development
    # Remove from production — use RedisInsight or Grafana dashboard instead
    image: rediscommander/redis-commander:latest
    ports:
      - "8081:8081"
    environment:
      - REDIS_HOSTS=local:redis:6379
    depends_on:
      redis:
        condition: service_healthy  # Wait for Redis health check to pass before starting

volumes:
  redis-data:

package io.thecodeforge.cache.test;

import io.thecodeforge.cache.model.Product;
import io.thecodeforge.cache.service.ForgeProductService;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.cache.Cache;
import org.springframework.cache.CacheManager;

import static org.assertj.core.api.Assertions.assertThat;

/**
 * Integration tests for caching behavior.
 *
 * These tests run against a real Redis instance (local Docker or Testcontainers in CI).
 * Mocked cache managers do not catch serialization bugs, TTL bugs, or key format bugs.
 *
 * Test categories:
 *   1. Cache hit — second call returns cached value, method body not re-executed
 *   2. Eviction — update/delete operation correctly removes cache entry
 *   3. Null protection — null method results are not stored in Redis
 */
@SpringBootTest
class ForgeProductServiceCacheTest {

    @Autowired
    private ForgeProductService productService;

    @Autowired
    private CacheManager cacheManager;

    @BeforeEach
    void clearAllCaches() {
        // Isolation: start each test with an empty cache
        // Prevents one test's cache state from affecting another
        cacheManager.getCacheNames().forEach(name -> {
            Cache cache = cacheManager.getCache(name);
            if (cache != null) {
                cache.clear();
            }
        });
    }

    @Test
    @DisplayName("Second call should be served from cache — method body should not execute again")
    void shouldCacheProductAfterFirstCall() {
        // First call — cold cache, method body executes, result stored in Redis
        long start1 = System.currentTimeMillis();
        Product first = productService.getProductById(1L);
        long duration1 = System.currentTimeMillis() - start1;

        // Second call — warm cache, method body skipped, result from Redis
        long start2 = System.currentTimeMillis();
        Product second = productService.getProductById(1L);
        long duration2 = System.currentTimeMillis() - start2;

        assertThat(first).isNotNull();
        assertThat(second.getId()).isEqualTo(first.getId());

        // Cache hit should be at least 10x faster than DB call
        // Adjust threshold based on your simulated DB latency
        assertThat(duration2)
            .as("Cache hit should be significantly faster than DB call (first: %dms, second: %dms)",
                duration1, duration2)
            .isLessThan(duration1 / 10);

        // Verify the entry actually exists in Redis under the expected key
        Cache productsCache = cacheManager.getCache("products");
        assertThat(productsCache).isNotNull();
        Cache.ValueWrapper cached = productsCache.get(1L);
        assertThat(cached).isNotNull();
        assertThat(cached.get()).isInstanceOf(Product.class);
    }

    @Test
    @DisplayName("Cache entry should be absent after update triggers @CacheEvict")
    void shouldEvictCacheOnUpdate() {
        // Warm the cache
        Product product = productService.getProductById(1L);
        assertThat(cacheManager.getCache("products").get(1L)).isNotNull();

        // Trigger eviction
        productService.updateProduct(product);

        // Verify the entry is gone
        assertThat(cacheManager.getCache("products").get(1L)).isNull();
    }

    @Test
    @DisplayName("Null return values should not be stored in the cache")
    void shouldNotCacheNullResult() {
        // ID 999 does not exist — method returns null
        Product result = productService.getProductById(999L);

        assertThat(result).isNull();

        // Verify the cache entry does not exist — null should not be cached
        Cache.ValueWrapper cached = cacheManager.getCache("products").get(999L);
        assertThat(cached)
            .as("Null result should not be stored in cache — unless = '#result == null' should prevent it")
            .isNull();
    }

    @Test
    @DisplayName("@CachePut should update cache without requiring a subsequent cache miss")
    void shouldUpdateCacheWithCachePut() {
        // Initial fetch — cache miss
        productService.getProductById(1L);
        assertThat(cacheManager.getCache("products").get(1L)).isNotNull();

        // Update with @CachePut — cache should be updated, not evicted
        Product updated = new Product(1L, "Forge Updated Drill", 199.99);
        Product returned = productService.updateAndRefreshProduct(updated);

        // Cache entry should still exist — not evicted, updated
        Cache.ValueWrapper cached = cacheManager.getCache("products").get(1L);
        assertThat(cached).isNotNull();
        assertThat(((Product) cached.get()).getName()).isEqualTo("Forge Updated Drill");

        // Verify no extra DB call needed — next read is a cache hit
        long start = System.currentTimeMillis();
        Product afterUpdate = productService.getProductById(1L);
        long duration = System.currentTimeMillis() - start;
        assertThat(duration).isLessThan(50); // Should be a cache hit — sub-50ms
    }
}