SpringBoot3.x集成Caffeine缓存框架官方指南

作者：袖梨 2026-06-10

概述

本指南基于官方文档，详细说明如何在 Spring Boot 3.x 中集成和使用 Caffeine 缓存框架。

1. Spring Boot 官方文档中关于 Caffeine 缓存的集成指南

1.1 基本集成

Spring Boot 自动配置缓存基础设施，只要启用缓存支持并使用 @EnableCaching 注解即可 [0†]。

如果类路径中存在 Caffeine，Spring Boot 会自动配置 CaffeineCacheManager（由 spring-boot-starter-cache 启动器提供）[0†]。

1.2 依赖配置

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-cache</artifactId>
</dependency>
<dependency>
    <groupId>com.github.ben-manes.caffeine</groupId>
    <artifactId>caffeine</artifactId>
    <version>3.2.3</version>
</dependency>

1.3 启用缓存

在配置类上添加 @EnableCaching 注解：

@Configuration
@EnableCaching
public class CacheConfig {
}

1.4 缓存配置

Spring Boot 允许通过多种方式配置 Caffeine 缓存 [0†]：

1.4.1 使用缓存规范

通过 spring.cache.caffeine.spec 属性配置：

spring.cache.cache-names=cache1,cache2
spring.cache.caffeine.spec=maximumSize=500,expireAfterAccess=600s

1.4.2 自定义 Bean

定义 CaffeineSpec Bean：

@Bean
public CaffeineSpec caffeineSpec() {
    return CaffeineSpec.parse("maximumSize=1000,expireAfterWrite=5m");
}

1.4.3 配置 CacheLoader

如果定义了 CacheLoader Bean，它会自动关联到 CaffeineCacheManager：

@Bean
public CacheLoader<Object, Object> cacheLoader() {
    return new CacheLoader<Object, Object>() {
        @Override
        public Object load(Object key) throws Exception {
            // 加载逻辑
            return null;
        }
    };
}

1.5 缓存管理器自定义

通过 CacheManagerCustomizer 接口自定义缓存管理器行为：

@Bean
public CacheManagerCustomizer<ConcurrentMapCacheManager> cacheManagerCustomizer() {
    return (cacheManager) -> cacheManager.setAllowNullValues(false);
}

2. 核心注解使用

2.1 @Cacheable

用于标记方法的结果应该被缓存 [8†]：

@Service
public class UserService {
    
    @Cacheable(value = "users", key = "#id")
    public User findById(Long id) {
        // 查询逻辑
        return user;
    }
}

2.2 @CachePut

更新缓存但不阻止方法执行：

@CachePut(value = "users", key = "#user.id")
public User updateUser(User user) {
    // 更新逻辑
    return user;
}

2.3 @CacheEvict

从缓存中移除条目：

@CacheEvict(value = "users", key = "#id")
public void deleteUser(Long id) {
    // 删除逻辑
}

3. Caffeine 官方文档中关于 Spring Boot 集成的说明

3.1 JCache 集成

Caffeine 提供 JSR-107 (JCache) 标准接口的实现 [41†]。通过 JCache，可以在不同缓存实现之间轻松切换。

3.2 Spring 集成

Caffeine 通过 JCache 提供了对 Spring 的集成支持。Spring Cache 从 4.3 版本和 Spring Boot 1.4 版本开始支持 Caffeine [41†]。

3.3 配置示例

@Configuration
@EnableCaching
public class CaffeineCacheConfig {
    
    @Bean
    public CacheManager cacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
        cacheManager.setCaffeine(Caffeine.newBuilder()
            .maximumSize(1000)
            .expireAfterWrite(Duration.ofMinutes(5))
            .recordStats());
        return cacheManager;
    }
}

4. 官方 GitHub 仓库相关信息

4.1 Caffeine 项目信息

Caffeine 是一个高性能的缓存库，提供了接近最优的命中率 [3†]。

主要特性：

自动加载条目到缓存
基于大小和时间的驱逐策略
异步刷新支持
统计信息收集

4.2 项目地址

GitHub 仓库：https://github.com/ben-manes/caffeine
官方文档：https://github.com/ben-manes/caffeine/wiki

4.3 集成支持

Caffeine 提供了多种框架集成：

Spring Cache（从 Spring 4.3 和 Boot 1.4 开始）
JCache (JSR-107)
Guava 适配器 [3†]

5. 完整示例

5.1 实体类

@Entity
public class Product {
    @Id
    @GeneratedValue
    private Long id;
    private String name;
    private BigDecimal price;
    // getters and setters
}

5.2 Repository 层

public interface ProductRepository extends JpaRepository<Product, Long> {
}

5.3 Service 层

@Service
@CacheConfig(cacheNames = "products")
public class ProductService {
    
    @Autowired
    private ProductRepository productRepository;
    
    @Cacheable(key = "#id")
    public Product findById(Long id) {
        return productRepository.findById(id).orElse(null);
    }
    
    @Cacheable(key = "'all'")
    public List<Product> findAll() {
        return productRepository.findAll();
    }
    
    @CachePut(key = "#product.id")
    public Product save(Product product) {
        return productRepository.save(product);
    }
    
    @CacheEvict(key = "#id")
    public void deleteById(Long id) {
        productRepository.deleteById(id);
    }
}

5.4 应用配置

# application.properties

# 启用缓存
spring.cache.type=caffeine

# 配置缓存名称
spring.cache.cache-names=products,users

# Caffeine 特定配置
spring.cache.caffeine.spec=maximumSize=1000,expireAfterWrite=10m,recordStats

6. 高级配置

6.1 多缓存配置

@Configuration
@EnableCaching
public class AdvancedCacheConfig {
    
    @Bean
    public CacheManager cacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
        
        // 配置产品缓存
        cacheManager.registerCache("products", Caffeine.newBuilder()
            .maximumSize(1000)
            .expireAfterWrite(Duration.ofMinutes(10))
            .recordStats()
            .build());
        
        // 配置用户缓存
        cacheManager.registerCache("users", Caffeine.newBuilder()
            .maximumSize(500)
            .expireAfterAccess(Duration.ofMinutes(5))
            .recordStats()
            .build());
        
        return cacheManager;
    }
}

6.2 缓存统计

启用统计功能以监控缓存性能：

@Bean
public CacheManager cacheManager() {
    CaffeineCacheManager cacheManager = new CaffeineCacheManager();
    cacheManager.setCaffeine(Caffeine.newBuilder()
        .maximumSize(1000)
        .expireAfterWrite(Duration.ofMinutes(5))
        .recordStats());  // 启用统计
    return cacheManager;
}

6.3 条件缓存

@Cacheable(value = "products", condition = "#id != null && #id > 0")
public Product findById(Long id) {
    return productRepository.findById(id).orElse(null);
}

7. 最佳实践

7.1 缓存一致性

对于可能被多个实例修改的数据，考虑使用分布式缓存
使用适当的缓存失效策略确保数据一致性

7.2 性能优化

根据访问模式调整缓存大小和过期策略
监控缓存命中率，优化缓存配置
对于高并发场景，考虑使用异步加载

7.3 错误处理

实现适当的异常处理机制
考虑缓存失败时的降级策略

8. 故障排除

8.1 常见问题

缓存未生效
- 确认 @EnableCaching 已启用
- 检查缓存名称是否配置正确
- 验证方法参数是否正确
内存泄漏
- 确保缓存大小有合理上限
- 监控缓存统计信息
- 检查缓存过期策略
性能问题
- 分析缓存命中率
- 调整缓存大小和过期时间
- 考虑异步加载策略

8.2 调试技巧

启用缓存统计以监控性能：

@Component
public class CacheMonitor {
    
    @EventListener
    public void onCacheEvent(CacheEvent event) {
        // 监控缓存事件
        System.out.println("Cache event: " + event.getType());
    }
}