Caffeine 是一个高性能、接近最优的 Java 本地缓存库，由 Ben Manes 开发，作为 Google Guava Cache 的继任者而广受欢迎。它在设计上融合了现代缓存算法（如 Window TinyLFU）、低开销并发控制和丰富的功能特性，被广泛应用于 Spring Boot、Hibernate、Kafka 等主流框架中。

下面从核心特性、工作原理、使用方式、最佳实践四个维度为你系统介绍 Caffeine。

一、为什么选择 Caffeine？（vs. Guava / ConcurrentHashMap）

💡结论：Caffeine 是Guava Cache 的现代化替代品，性能更强、功能更全、维护更活跃。

二、核心特性详解

1.智能淘汰策略：Window TinyLFU

• 结合LFU（频率） + LRU（新鲜度），解决传统 LFU “冷数据长期驻留” 和 LRU “扫描攻击易失效” 的问题。
• 实测命中率比 LRU 高 20%~50%，尤其适合有“热点数据”的场景（如用户会话、API 响应缓存）。

2.多种过期策略

Caffeine.newBuilder().expireAfterWrite(10,TimeUnit.MINUTES)// 写入后10分钟过期.expireAfterAccess(5,TimeUnit.MINUTES)// 最后访问后5分钟过期.expireAfter(newExpiry<String,Object>(){publiclongexpireAfterCreate(Stringkey,Objectvalue,longcurrentTime){returnTimeUnit.MINUTES.toNanos(10);}// 可实现 per-entry 动态过期时间})

3.容量控制

• maximumSize(n)：最多缓存 n 个条目（基于数量）
• maximumWeight(n)+weigher：按权重（如对象大小、内存占用）控制总容量

  .maximumWeight(100_000).weigher((Stringkey,Datavalue)->value.sizeInBytes())

4.异步加载（AsyncLoadingCache）

AsyncLoadingCache<String,String>cache=Caffeine.newBuilder().buildAsync(key->fetchDataFromDB(key));// 返回 CompletableFutureCompletableFuture<String>future=cache.get("userId");future.thenAccept(data->System.out.println(data));

5.监听器与统计

Caffeine.newBuilder().removalListener((key,value,cause)->{System.out.println("Removed: "+key+" due to "+cause);}).recordStats()// 启用统计.build();// 查看命中率System.out.println(cache.stats().hitRate());// 如 0.85

三、基本使用方式

1.手动缓存（Manual Cache）

适用于需要显式put/get的场景（如你的文件上传去重）：

Cache<String,Object>cache=Caffeine.newBuilder().expireAfterWrite(10,TimeUnit.MINUTES).maximumSize(10_000).build();cache.put("key","value");Objectval=cache.getIfPresent("key");cache.invalidate("key");// 删除

2.自动加载缓存（Loading Cache）

适用于“按需加载 + 自动缓存”的场景（如数据库查询缓存）：

LoadingCache<String,User>userCache=Caffeine.newBuilder().maximumSize(1000).expireAfterWrite(10,TimeUnit.MINUTES).build(key->loadUserFromDB(key));// 自动加载函数Useruser=userCache.get("user123");// 若不存在，自动调用 loadUserFromDB

3.异步加载缓存（AsyncLoadingCache）

适用于 I/O 密集型操作（如远程 API 调用）：

AsyncLoadingCache<String,Profile>profileCache=Caffeine.newBuilder().buildAsync(this::fetchProfileAsync);// 返回 CompletableFuture<Profile>

四、高级技巧与最佳实践

✅ 1.线程安全无需担心

• 所有 Caffeine 缓存都是线程安全的，内部使用Striped Lock / Non-blocking design，高并发下性能优异。

✅ 2.避免在 mappingFunction 中做耗时操作阻塞其他请求

• LoadingCache的load函数是同步且串行化 per-key的：
  • 同一 key 的多个并发请求，只有一个会触发 load，其余等待结果。
  • 但不同 key 之间完全并行。
• 如果 load 很慢，考虑用AsyncLoadingCache。

✅ 3.合理设置 maximumSize

• 不要盲目设大，否则可能 OOM。
• 建议：根据QPS × 平均缓存停留时间估算所需容量。

  例：每秒 1000 请求，缓存保留 10 分钟 → 理论最大条目 ≈ 1000 × 600 = 60 万

✅ 4.结合 Spring Cache 使用

@Configuration@EnableCachingpublicclassCacheConfig{@BeanpublicCacheManagercaffeineCacheManager(){CaffeineCacheManagercacheManager=newCaffeineCacheManager();cacheManager.setCaffeine(Caffeine.newBuilder().expireAfterWrite(10,TimeUnit.MINUTES).maximumSize(1000));returncacheManager;}}@ServicepublicclassUserService{@Cacheable("users")publicUsergetUser(Stringid){returndb.findById(id);}}

✅ 5.监控与调优

• 启用.recordStats()，定期打印cache.stats()：

  CacheStatsstats=cache.stats();doublehitRate=stats.hitRate();// 命中率longevictionCount=stats.evictionCount();// 淘汰次数

• 若命中率 < 70%，考虑增大容量或延长过期时间。

五、典型应用场景

六、依赖引入（Maven）

<dependency><groupId>com.github.ben-manes.caffeine</groupId><artifactId>caffeine</artifactId><version>3.1.8</version><!-- 检查最新版 --></dependency>

📌 官网：https://github.com/ben-manes/caffeine
📚 文档：https://github.com/ben-manes/caffeine/wiki

总结

Caffeine 是Java 本地缓存的事实标准，它：

• ✅性能顶尖（优于 Guava、Ehcache 本地模式）
• ✅API 简洁（Manual / Loading / Async 三种模式覆盖所有场景）
• ✅功能强大（智能淘汰、动态过期、权重控制、统计监控）
• ✅生态完善（Spring、Micronaut、Quarkus 原生支持）

对于你的文件上传去重、接口幂等、热点数据缓存等需求，Caffeine 是轻量、高效、可靠的首选方案。

如需具体场景的代码模板（如分布式锁+本地缓存二级去重），可继续提问！