概述

本篇指南严格依据官方文档整理而成，手把手教你在 Spring Boot 3.x 中集成 Caffeine 高性能缓存框架。拒绝花哨理论，只呈现实战干货，助你快速掌握缓存配置技巧。

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

1.1 基本集成

Spring Boot 的自动配置能力非常强大——只需在类路径中添加 Caffeine 依赖，并配合使用 @EnableCaching 注解，缓存基础设施便能自动搭建完成 [0†]。这一切的背后，是 spring-boot-starter-cache 启动器默默完成了 CaffeineCacheManager 的自动配置 [0†]。

1.2 依赖配置

首先将依赖引入项目：

    org.springframework.boot
    spring-boot-starter-cache


    com.github.ben-manes.caffeine
    caffeine
    3.2.3

1.3 启用缓存

在任意配置类上添加 @EnableCaching 注解，缓存功能即可生效：

@Configuration
@EnableCaching
public class CacheConfig {
}

1.4 缓存配置

Spring Boot 提供了多种方式来配置 Caffeine 缓存 [0†]：

1.4.1 使用缓存规范

最简洁的方式——直接在 application.properties 中定义：

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 cacheLoader() {
    return new CacheLoader() {
        @Override
        public Object load(Object key) throws Exception {
            // 加载逻辑
            return null;
        }
    };
}

1.5 缓存管理器自定义

通过 CacheManagerCustomizer 接口，能够进一步定制缓存管理器的行为，例如禁止缓存空值：

@Bean
public CacheManagerCustomizer 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

与 @Cacheable 不同，它只负责更新缓存，方法本身照常执行：

@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†]。其优势在于——你可以在不同缓存实现之间无缝切换，而无需修改业务代码。

3.2 Spring 集成

通过 JCache 这一抽象层，Caffeine 自然融入了 Spring 生态。自 Spring 4.3 和 Spring Boot 1.4 版本起，Spring Cache 就已原生支持 Caffeine [41†]。

3.3 配置示例

如果不想使用自动配置，也可以手动构建 CacheManager：

@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 是一个高性能的 Java 缓存库，其缓存命中率接近理论最优值 [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 {
}

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 findAll() {
        return productRepository.findAll();
    }
    
    @CachePut(key = "#product.id")
    public Product sa ve(Product product) {
        return productRepository.sa ve(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 常见问题

1. 缓存未生效
   • 确认 @EnableCaching 注解是否已正确添加
   • 检查缓存名称是否存在拼写错误
   • 验证方法参数是否与注解中的 key 表达式匹配
2. 内存泄漏
   • 为缓存大小设置一个合理的上限，防止数据无限膨胀
   • 监控缓存统计信息，确认逐出策略是否正常工作
   • 检查过期策略是否已生效
3. 性能问题
   • 分析缓存命中率，命中率偏低说明缓存未能达到预期效果
   • 尝试调整缓存容量和过期时间，找到最优配置
   • 对于冷点数据，考虑使用异步加载或直接绕过缓存

8.2 调试技巧

开启缓存统计后，可以通过监听缓存事件来快速定位问题：

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

总结

按照本指南的步骤操作，你应当能够顺利在 Spring Boot 3.x 项目中集成 Caffeine 缓存，从而显著提升应用响应速度与整体性能。关键在于：根据业务场景合理制定缓存策略，持续监控命中率指标，并依据实际运行数据不断调优。缓存优化并非一劳永逸，而是一个持续迭代、精益求精的过程。

更多详细内容请参考：

• Spring Boot 官方文档 - 缓存 [0†]
• Caffeine 官方 GitHub 仓库 [3†]
• Caffeine 官方 Wiki [26†]