为什么 Caffeine 的 get 方法默认不阻塞写入
因为 Caffeine 把“缓存未命中 + 异步加载”和“同步计算 + 阻塞等待”做了明确分离。它默认走的是 get(key, mappingFunction) 这条路径，而这个方法在 key 不存在时，会用你传的 mappingFunction 同步计算值并写入，**期间其他线程对同一 key 的 get 调用会各自触发计算，不共享 loading 过程**——也就是常说的“缓存击穿”风险点。
常见错误现象：get(key, () -> heavyIoCall()) 在高并发下导致后端被压垮，日志里看到几十次重复的 heavyIoCall 执行。
- 真正想做“只加载一次、其余线程等待”的行为，得显式启用
refreshAfterWrite或配合asMap().computeIfAbsent+ 手动锁，但后者破坏了缓存语义 -
build().get(key, ...)是无状态的，不维护 loading 中的状态；AsyncLoadingCache才提供真正的异步 load + 共享CompletableFuture - 如果你依赖 Spring 的
@Cacheable，底层用 Caffeine 时默认仍是同步加载，需配sync = true（Spring Boot 2.7+）才启用轻量级本地锁
maximumSize 和 maximumWeight 别混用
二者不可共存，Caffeine 构建时会直接抛 IllegalStateException: maximumSize and maximumWeight cannot both be set。选哪个取决于你关心的是“条目数量上限”还是“内存权重上限”。
使用场景：API 响应体大小差异极大，比如有的返回 1KB JSON，有的返回 5MB 图片 base64，这时用 maximumWeight 更合理；若缓存都是固定结构的 DTO，且数量可控，maximumSize 更直观。
立即学习“Java免费学习笔记（深入）”；
将后端 Java 接口文档转换为前端 TypeScript 类型定义（interface / type）。输入：飞书文档、Spring Boot 接口文档、Swagger/OpenAPI、手写 API 文档等。输出：包含请求参数与响应结果的 .md 文件，含完整 JSDoc 注释。触发关键词：Java 转 TS、接口转换、生成前端类型、接口文档转 TypeScript、DTO/VO/BO 转 interface、后端文档转前端类型、生成接口类型、类型定义生成。
-
weigher函数必须是纯函数，不能有副作用，也不能依赖外部状态（比如调用System.currentTimeMillis()） - 权重不是字节数，而是你定义的抽象单位；Caffeine 不做内存测量，只累加你返回的 long 值
- 设置
maximumWeight=10000但所有 entry weigher 都返回 0 → 缓存永不淘汰，容易 OOM
淘汰策略不是 LRU，而是 W-TinyLFU
Caffeine 默认不用传统 LRU，而是基于概率统计的 W-TinyLFU（Window Tiny Least Frequently Used），它用布隆过滤器 + 频率 sketch 做热点识别，在吞吐和命中率上比 LRU 更稳。但这意味着：你不能靠“最近访问”来预测淘汰顺序，尤其在冷热数据混合场景下。
常见错误现象：手动调用 cache.invalidateAll() 后，观察到部分刚 put 的 key 立即被踢出，以为是 bug，其实是 W-TinyLFU 的准入机制在起作用——新 key 需先通过 window cache 的热度验证，否则直接淘汰。
- 不支持切换回纯 LRU；想模拟 LRU 行为，只能设极小
recordStats()+ 自己统计访问时间，再手动清理 -
evictionListener触发时机是“确定淘汰前”，但 listener 内不能阻塞或耗时，否则拖慢整个 eviction 流程 - 压力测试时如果只压单个 key，W-TinyLFU 可能误判为“非热点”，导致命中率反低于预期
并发更新下 asMap() 的行为边界
cache.asMap() 返回的是一个线程安全的 ConcurrentMap 视图，但它**不保证原子复合操作**。比如 asMap().computeIfAbsent(key, k -> load(k)) 看似能防击穿，实际仍可能多次执行 load(k) —— 因为 computeIfAbsent 底层没用 Caffeine 的 loading 机制，只是普通 ConcurrentHashMap 的语义。
性能影响：频繁调用 asMap().get(key) 比原生 cache.get(key, ...) 慢 10%~20%，因为绕过了 Caffeine 内部的 fast-path 优化（如避免包装 Optional）。
- 不要用
asMap().put(key, value)替代cache.put(key, value)，前者不触发removalListener，也不参与权重/大小统计 -
asMap().replace(key, oldValue, newValue)是原子的，但 oldValue 必须严格等于当前值（引用相等 or equals），注意装箱类型陷阱 - 如果业务逻辑强依赖 Map 接口，建议封装一层适配器，把
cache.get(key, f)包装成类似 computeIfAbsent 的语义，而不是裸用 asMap
W-TinyLFU 的窗口期、weigher 的实现精度、以及 loading 过程是否可取消——这三个地方一旦配置不当，问题往往在线上压测时才暴露，而且很难复现。
