Spring Boot Caching — The Complete Production Guide

@SpringBootApplication
@EnableCaching  // Activates cache infrastructure via AOP proxies
public class ECommerceApplication { }

@CachePut(value = "products", key = "#product.id")
public Product updateProduct(Product product) {
    log.info("Updating product {} and refreshing cache", product.getId());
    return productRepository.save(product);  // Always executes
}

// Evict single entry
@CacheEvict(value = "products", key = "#productId")
public void deleteProduct(Long productId) {
    productRepository.deleteById(productId);
}

// Nuclear option — clear entire cache
@CacheEvict(value = "products", allEntries = true)
public void reloadProductCatalog() {
    log.info("Full catalog refresh — evicting all cached products");
}

// Evict BEFORE method executes (useful if method might throw)
@CacheEvict(value = "inventory", key = "#sku", beforeInvocation = true)
public void updateInventory(String sku, int quantity) {
    inventoryRepository.update(sku, quantity);  // might throw
}

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

@Service
@CacheConfig(cacheNames = "orders", cacheManager = "redisCacheManager")
public class OrderService {

    @Cacheable(key = "#orderId")          // inherits cache name "orders"
    public Order getOrder(Long orderId) { ... }

    @CacheEvict(key = "#orderId")         // inherits cache name "orders"
    public void cancelOrder(Long orderId) { ... }
}

// Direct parameter reference
@Cacheable(value = "users", key = "#userId")
public User getUser(Long userId) { ... }

// Object field access
@Cacheable(value = "users", key = "#request.email")
public User findByRequest(UserSearchRequest request) { ... }

// Composite key
@Cacheable(value = "orders", key = "#userId + ':' + #status")
public List<Order> findOrders(Long userId, OrderStatus status) { ... }

// Method name in key (avoid collisions)
@Cacheable(value = "analytics", key = "#root.methodName + ':' + #id")
public AnalyticsData getMetrics(Long id) { ... }

// Conditional key with ternary
@Cacheable(value = "search", key = "#query.length() > 50 ? #query.hashCode() : #query")
public SearchResults search(String query) { ... }

@Component("tenantAwareKeyGenerator")
public class TenantAwareKeyGenerator implements KeyGenerator {

    @Override
    public Object generate(Object target, Method method, Object... params) {
        String tenant = TenantContext.getCurrentTenant();
        String paramKey = Arrays.stream(params)
            .map(p -> p == null ? "null" : p.toString())
            .collect(Collectors.joining(":"));
        return tenant + ":" + method.getName() + ":" + paramKey;
    }
}

// Usage
@Cacheable(value = "products", keyGenerator = "tenantAwareKeyGenerator")
public List<Product> getTenantProducts(String category) { ... }

@Bean
public CacheManager cacheManager() {
    CaffeineCacheManager manager = new CaffeineCacheManager();
    manager.registerCustomCache("products",
        Caffeine.newBuilder()
            .maximumSize(10_000)
            .expireAfterWrite(Duration.ofHours(1))     // hard TTL
            .refreshAfterWrite(Duration.ofMinutes(45)) // soft refresh
            .recordStats()
            .build());
    return manager;
}

@Component
public class CacheStatsReporter {

    @Autowired private CacheManager cacheManager;

    @Scheduled(fixedRate = 60_000)
    public void reportStats() {
        cacheManager.getCacheNames().forEach(name -> {
            Cache cache = cacheManager.getCache(name);
            if (cache != null && cache.getNativeCache() instanceof com.github.benmanes.caffeine.cache.Cache<?,?> caffeineCache) {
                CacheStats stats = caffeineCache.stats();
                log.info("Cache [{}] hitRate={:.2f}% evictions={} size={}",
                    name, stats.hitRate() * 100, stats.evictionCount(), caffeineCache.estimatedSize());
            }
        });
    }
}

@Bean
public LettuceConnectionFactory redisConnectionFactory() {
    RedisClusterConfiguration clusterConfig = new RedisClusterConfiguration(
        List.of("redis-1:6379", "redis-2:6379", "redis-3:6379"));
    clusterConfig.setMaxRedirects(3);

    LettuceClientConfiguration clientConfig = LettuceClientConfiguration.builder()
        .commandTimeout(Duration.ofMillis(2000))
        .readFrom(ReadFrom.REPLICA_PREFERRED)  // Read from replicas for cache reads
        .build();

    return new LettuceConnectionFactory(clusterConfig, clientConfig);
}

@Service
public class ProductCatalogService {

    @Cacheable(value = "products", key = "#productId", unless = "#result == null")
    public Product getProduct(Long productId) {
        return productRepository.findById(productId).orElse(null);
    }

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

@Service
public class InventoryService {

    @CachePut(value = "inventory", key = "#sku")
    public InventoryLevel updateStock(String sku, int newQuantity) {
        InventoryLevel level = new InventoryLevel(sku, newQuantity, Instant.now());
        inventoryRepository.save(level);
        return level;  // This exact object goes into the cache
    }

    @Cacheable(value = "inventory", key = "#sku")
    public InventoryLevel getStock(String sku) {
        return inventoryRepository.findBySku(sku);
    }
}

@Service
public class EventTrackingService {

    private final BlockingQueue<UserEvent> writeQueue = new LinkedBlockingQueue<>(10_000);

    @CachePut(value = "userEvents", key = "#event.userId + ':' + #event.eventType")
    public UserEvent trackEvent(UserEvent event) {
        writeQueue.offer(event);  // Async — DB write happens later
        return event;
    }

    @Scheduled(fixedDelay = 5000)
    public void flushToDatabase() {
        List<UserEvent> batch = new ArrayList<>();
        writeQueue.drainTo(batch, 500);
        if (!batch.isEmpty()) {
            eventRepository.saveAll(batch);
            log.info("Flushed {} events to database", batch.size());
        }
    }
}

@Configuration
@EnableCaching
public class MultiLevelCacheConfig {

    @Bean
    @Primary
    public CacheManager cacheManager(RedisConnectionFactory redisFactory) {
        return new MultiLevelCacheManager(
            caffeineCacheManager(),
            redisCacheManager(redisFactory)
        );
    }

    private CaffeineCacheManager caffeineCacheManager() {
        CaffeineCacheManager manager = new CaffeineCacheManager();
        manager.setCaffeine(Caffeine.newBuilder()
            .maximumSize(1_000)
            .expireAfterWrite(Duration.ofMinutes(5))  // Short L1 TTL
            .recordStats());
        return manager;
    }

    private RedisCacheManager redisCacheManager(RedisConnectionFactory factory) {
        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
            .entryTtl(Duration.ofMinutes(60));  // Longer L2 TTL
        return RedisCacheManager.builder(factory).cacheDefaults(config).build();
    }
}

// Custom CacheManager that checks L1 then L2
public class MultiLevelCacheManager implements CacheManager {
    private final CacheManager l1;  // Caffeine
    private final CacheManager l2;  // Redis

    @Override
    public Cache getCache(String name) {
        return new MultiLevelCache(l1.getCache(name), l2.getCache(name));
    }

    // MultiLevelCache: get() checks L1 then L2, put() writes to both
}

// Redis: 30-minute TTL
RedisCacheConfiguration.defaultCacheConfig().entryTtl(Duration.ofMinutes(30));

// Caffeine: 10-minute TTL
Caffeine.newBuilder().expireAfterWrite(Duration.ofMinutes(10));

@Service
public class ProductService {

    @Cacheable("products")
    public Product getProduct(Long id) { return repo.findById(id).orElseThrow(); }

    @Caching(evict = {
        @CacheEvict(value = "products", key = "#product.id"),
        @CacheEvict(value = "productsByCategory", key = "#product.categoryId"),
        @CacheEvict(value = "productSearch", allEntries = true)
    })
    public Product updateProduct(Product product) { return repo.save(product); }
}

// Service A: Publishes product update event
@CachePut(value = "products", key = "#product.id")
public Product updateProduct(Product product) {
    Product saved = repo.save(product);
    kafkaTemplate.send("product-events", new ProductUpdatedEvent(saved.getId()));
    return saved;
}

// Service B: Listens and invalidates its local cache
@KafkaListener(topics = "product-events")
public void onProductUpdated(ProductUpdatedEvent event) {
    Cache cache = cacheManager.getCache("products");
    if (cache != null) {
        cache.evict(event.getProductId());
        log.info("Evicted product {} from local cache due to upstream update", event.getProductId());
    }
}

@Cacheable(value = "productPage", key = "#productId + ':v' + #version")
public ProductPageDTO getProductPage(Long productId, int version) {
    return buildExpensiveProductPage(productId);
}

public void evictByPattern(String pattern) {
    RedisConnection connection = redisTemplate.getConnectionFactory().getConnection();
    ScanOptions options = ScanOptions.scanOptions().match(pattern).count(100).build();
    Cursor<byte[]> cursor = connection.scan(options);
    while (cursor.hasNext()) {
        connection.del(cursor.next());
    }
}

// Evict all product-related caches for product 42
evictByPattern("ecommerce::product*42*");

@Service
public class OrderService {

    // BROKEN — cache is NEVER consulted here!
    public OrderSummary getOrderSummary(Long orderId) {
        Order order = getOrder(orderId);  // ← Direct call, bypasses proxy
        return buildSummary(order);
    }

    @Cacheable("orders")
    public Order getOrder(Long orderId) {
        return orderRepository.findById(orderId).orElseThrow();
    }
}

// BROKEN — Hibernate lazy proxy cannot be serialized
@Cacheable("orders")
public Order getOrder(Long id) {
    return orderRepository.findById(id).orElseThrow();
    // Order.customer is a lazy-loaded proxy → SerializationException!
}

// FIXED — Use DTOs, not entities
@Cacheable("orders")
public OrderDTO getOrder(Long id) {
    Order order = orderRepository.findById(id).orElseThrow();
    return OrderDTO.from(order);  // Eagerly maps all fields
}

// COLLISION — both use cache "data" with numeric key
@Cacheable(value = "data", key = "#id")
public User getUser(Long id) { ... }      // data::1 → User

@Cacheable(value = "data", key = "#id")
public Product getProduct(Long id) { ... } // data::1 → Product  CONFLICT!

// FIXED — separate cache names or prefixed keys
@Cacheable(value = "users", key = "#id")
public User getUser(Long id) { ... }

@Cacheable(value = "products", key = "#id")
public Product getProduct(Long id) { ... }

// RACE CONDITION — another thread reads between DB write and evict
public Product updateProduct(Product product) {
    productRepository.save(product);          // Step 1: DB updated
    // <-- Thread B reads stale cache here!
    cacheManager.getCache("products").evict(product.getId());  // Step 2: Cache evicted
    return product;
}

// BETTER — use @CachePut for atomic update or evict BEFORE DB write
@CachePut(value = "products", key = "#product.id")
public Product updateProduct(Product product) {
    return productRepository.save(product);  // Atomic: method returns, cache updates
}

// DANGEROUS — no size limit, no TTL
@Cacheable("searchResults")  // with SimpleCacheManager
public List<Product> search(String query) { ... }
// 10,000 unique queries = 10,000 cached result sets = OOM

// FIXED — always configure bounds
Caffeine.newBuilder()
    .maximumSize(1_000)           // Hard limit on entries
    .expireAfterWrite(Duration.ofMinutes(5))  // Hard limit on time
    .build();

// DOES NOTHING — private method, proxy can't intercept
@Cacheable("data")
private Data loadData(Long id) { ... }

// DOES NOTHING — void return, nothing to cache
@Cacheable("notifications")
public void sendNotification(Long userId) { ... }

// FIXED — public method with return value
@Cacheable("data")
public Data loadData(Long id) { ... }

// DANGER — cache updated even if transaction rolls back!
@Transactional
@Cacheable("accounts")
public Account getAccount(Long id) {
    Account account = repo.findById(id).orElseThrow();
    auditService.logAccess(id);  // If this throws → rollback, but cache has data
    return account;
}

// FIXED — use transaction-aware cache manager
RedisCacheManager.builder(factory)
    .transactionAware()  // Cache writes deferred until transaction commits
    .build();

@Component
@Slf4j
public class CacheWarmer {

    @Autowired private ProductService productService;
    @Autowired private ConfigService configService;

    @EventListener(ApplicationReadyEvent.class)
    public void warmCaches() {
        log.info("Starting cache warm-up...");

        Instant start = Instant.now();

        // Warm top 100 products (covers 80% of traffic)
        productService.getTopProducts(100).forEach(p -> 
            productService.getProduct(p.getId()));

        // Warm all configuration (small dataset, always needed)
        configService.getAllConfigs();

        Duration elapsed = Duration.between(start, Instant.now());
        log.info("Cache warm-up complete in {}ms", elapsed.toMillis());
    }
}

@Service
public class CacheRefreshService {

    @Autowired private ProductService productService;

    // Refresh 5 minutes BEFORE TTL expires (TTL = 60m, refresh at 55m)
    @Scheduled(fixedRate = 55 * 60 * 1000)
    public void refreshProductCache() {
        log.info("Pre-emptive cache refresh starting");
        productService.getHotProductIds().forEach(id -> {
            try {
                productService.evictProduct(id);
                productService.getProduct(id);  // Re-populates cache
            } catch (Exception e) {
                log.warn("Failed to refresh product {}: {}", id, e.getMessage());
            }
        });
    }
}

@Bean
public CacheManager cacheManager(MeterRegistry meterRegistry) {
    CaffeineCacheManager manager = new CaffeineCacheManager();
    manager.setCacheSpecification("maximumSize=10000,expireAfterWrite=10m,recordStats");
    // Spring Boot auto-binds Caffeine stats to Micrometer when recordStats is enabled
    return manager;
}

// Only consult cache for premium users (condition)
@Cacheable(value = "recommendations",
    key = "#userId",
    condition = "#userTier == T(UserTier).PREMIUM")
public List<Product> getRecommendations(Long userId, UserTier userTier) { ... }

// Cache the result unless it's an empty list (unless)
@Cacheable(value = "orders",
    key = "#userId",
    unless = "#result.isEmpty()")
public List<Order> getRecentOrders(Long userId) { ... }

// Combined: only cache for valid users, skip empty results
@Cacheable(value = "wishlist",
    key = "#userId",
    condition = "#userId != null",
    unless = "#result == null || #result.items.isEmpty()")
public Wishlist getWishlist(Long userId) { ... }