spring-boot-cache

Spring Boot 缓存抽象

概述

在 Spring Boot 3.5+ 应用中启用缓存抽象、配置提供程序（Caffeine、Redis、Ehcache）、为服务方法添加注解并验证行为的 6 步工作流。读取时使用 @Cacheable，写入时使用 @CachePut，删除时使用 @CacheEvict。配置 TTL/驱逐策略，并通过 Actuator 暴露指标。

适用场景

• 为服务方法添加 @Cacheable、@CachePut 或 @CacheEvict。
• 配置 Caffeine、Redis 或 Ehcache 的 TTL 和容量策略。
• 为过期数据实现驱逐策略。
• 排查缓存未命中或失效问题。
• 通过 Actuator 或 Micrometer 暴露命中/未命中指标。

操作说明

1. 添加依赖 — spring-boot-starter-cache 加上一种提供程序：

   • Caffeine：caffeine starter
   • Redis：spring-boot-starter-data-redis
   • Ehcache：ehcache starter

2. 启用缓存 — 为 @Configuration 类添加 @EnableCaching 注解，并定义 CacheManager Bean。

3. 为方法添加注解 — 读取时使用 @Cacheable，写入时使用 @CachePut，删除时使用 @CacheEvict。

4. 配置 TTL/驱逐策略 — 设置 spring.cache.caffeine.spec、 spring.cache.redis.time-to-live 或 spring.cache.ehcache.config。

5. 构造键 — 在 key 属性中使用 SpEL；通过 condition/unless 控制是否进行缓存。

6. 验证设置 — 运行集成测试，确认第二次调用命中缓存；检查 GET /actuator/caches 以验证缓存管理器已注册；查询 GET /actuator/metrics/cache.gets 以获取命中/未命中比率。

示例

示例 1：基本的 @Cacheable 用法

@Service
@CacheConfig(cacheNames = "users")
class UserService {

    @Cacheable(key = "#id", unless = "#result == null")
    User findUser(Long id) { ... }
}

First call → cache miss, repository invoked
Second call → cache hit, repository skipped

示例 2：使用 SpEL 进行条件缓存

@Cacheable(value = "products", key = "#id", condition = "#price > 100")
public Product getProduct(Long id, BigDecimal price) { ... }

// Only expensive products are cached

示例 3：缓存驱逐

@CacheEvict(value = "users", key = "#id")
public void deleteUser(Long id) { ... }

如需循序渐进的场景示例（基本产品缓存、多级驱逐、Redis 集成），请加载 references/cache-examples.md。

高级选项

• 对于倾向于使用 JSR-107 互操作性的提供程序，可使用 JCache 注解（@CacheResult、@CacheRemove）；避免在同一方法上混用 Spring 注解。
• 缓存响应式返回类型（Mono、Flux）或 CompletableFuture 值。
• 通过 REST 暴露缓存响应时，应用 HTTP CacheControl 标头。
• 对有时限的缓存使用 @Scheduled 定期驱逐。
• 创建 CacheManagementService，以编程方式调用 cacheManager.getCache(name)。

故障排查

如果添加 @Cacheable 后仍持续出现缓存未命中：

1. 确认 @Configuration 类上存在 @EnableCaching。
2. 确认方法是 public，且从类外部调用（Spring 使用代理；类内自调用会绕过缓存）。
3. 验证 SpEL 键表达式能正确解析。
4. 确认缓存管理器 Bean 已注册为 cacheManager，或通过 cacheManager = "myCacheManager" 显式引用。

参考资料

• references/spring-framework-cache-docs.md： Spring Framework Reference Guide 精选摘录。
• references/spring-cache-doc-snippet.md： Spring 文档中的概述说明。
• references/cache-core-reference.md： 注解参数、依赖矩阵和属性目录。
• references/cache-examples.md： 包含测试的端到端示例。

最佳实践

• 优先使用构造函数注入，并为缓存条目使用不可变 DTO。
• 按聚合划分缓存名称（users、orders），以简化驱逐操作。
• 仅在 debug 级别记录缓存命中/未命中；通过 Micrometer 推送指标。
• 根据数据可接受的过期程度调整 TTL；在代码中说明原因。
• 对存储 PII 或凭据的缓存进行加密保护，或避免缓存此类数据。
• 让缓存驱逐与事务边界保持一致，以防止脏读。

限制与警告

• 避免缓存依赖于开放持久化上下文的可变实体。
• 不要在同一个方法上混用 Spring 缓存注解和 JCache 注解。
• 在服务实例之间缓存时，验证序列化兼容性。
• 监控内存占用，防止内存存储导致 OOM。
• Caffeine + Redis 多级缓存需要发布/订阅失效通道。

相关技能

• ../spring-boot-rest-api-standards
• ../spring-boot-test-patterns
• ../unit-test-caching