Caffeine 缓存序列化代理审计指南：配置捕获完整性、往返一致性与安全边界

• 后端
• 缓存抽象

本指南聚焦 Caffeine 缓存库的序列化代理（SerializationProxy）机制，系统讲解如何审计"序列化/反序列化往返"的正确性与安全性。文中将逐条拆解审计清单的六个检查维度（代理完整性、状态转移、反序列化一致性、跨版本兼容、安全性、边界情况），并落到 SerializationProxy.java 等核心源码上印证实现细节；读完你可以独立完成一次序列化代理审计，并按照统一的缺陷报告格式输出带严重度评估的审计结论。

为什么 Caffeine 需要序列化代理：只存配置、不存数据

Caffeine 的缓存对象（Cache、LoadingCache、AsyncCache、AsyncLoadingCache）内部持有高度可变且并发的运行时状态：哈希表节点、频率草图（frequency sketch）、定时轮（timer wheel）、写缓冲区（write buffer）、权重计数器等。直接对这些对象做 Java 序列化既不现实也不安全——BoundedLocalCache的实现类节点（PS、WSSMS等）是生成代码，内部字段布局随版本演进，序列化形态极不稳定。

因此 Caffeine 采用了标准的serialization proxy pattern：真实缓存类只实现writeReplace()返回一个轻量的SerializationProxy，反序列化时由代理的readResolve()通过Caffeinebuilder 重建一个配置相同、数据为空的全新缓存。这个设计意图在SerializationProxy的类注释里写得很明确（SerializationProxy.java）：

Serializes the configuration of the cache, reconstituting it as a Cache, LoadingCache, AsyncCache, or AsyncLoadingCache using Caffeine upon deserialization. The data held by the cache is not retained.

数据不随序列化保留，这是整个审计工作的前提。审计的目标不是验证"缓存里的条目能否被还原"，而是验证"配置是否被完整、正确地捕获并还原"。

对应的源码证据链如下：

• 有界缓存的四类视图（手动、加载、异步、异步加载）都在 BoundedLocalCache.java 中实现了private Object writeReplace()返回makeSerializationProxy(cache)，并实现了readObject抛InvalidObjectException("Proxy required")，强制反序列化必须走代理路径，杜绝绕过代理直接反序列化缓存本体。
• 无界缓存系列在 UnboundedLocalCache.java 中有同样的writeReplace()/readObject()配对模式。
• 反序列化端由SerializationProxy.readResolve()统一收口：根据async标志与cacheLoader是否为空，分派到build()、build(loader)、buildAsync()、buildAsync(loader)四种构造路径（SerializationProxy.java）。

审计对象清单：BoundedLocalCache.java中的BoundedLocalManualCache/BoundedLocalLoadingCache/BoundedLocalAsyncCache/BoundedLocalAsyncLoadingCache，UnboundedLocalCache.java中的UnboundedLocalManualCache/UnboundedLocalLoadingCache/UnboundedLocalAsyncCache/UnboundedLocalAsyncLoadingCache，以及Weigher.java、WriteThroughEntry.java、Async.java、LocalAsyncCache.java中各自的writeReplace()实现。

检查维度一：代理完整性（Proxy completeness）

审计的首要问题：代理是否捕获了全部配置？遗漏任何一项配置都意味着反序列化后的缓存行为与原始缓存不一致，属于"静默的行为漂移"。

对照SerializationProxy的全部字段（SerializationProxy.java），逐项核对配置的捕获与还原：

源码侧的填充端在 BoundedLocalCache.makeSerializationProxy()：它把运行时状态反向读回代理字段，注意其中的条件分支——只有cache.expiresAfterAccess()为真才写expiresAfterAccessNanos，只有cache.evicts()为真才写maximumSize/maximumWeight等，这保证"未配置项不写入、反序列化时不误设"。

审计时重点核对以下几处容易出问题的映射：

• Caffeine.UNSET_INT哨兵语义：代理字段默认值就是UNSET_INT（对应Caffeine中的-1）。反序列化时通过!= UNSET_INT判断是否调用对应 builder 方法。若某处错误地把真实配置值写成了哨兵值，或把哨兵值当真实值传递，就会导致最大容量/过期时间静默丢失或误设。
• 监听器是对象而非标量：removalListener、evictionListener、ticker、weigher、expiry、cacheLoader都是用户提供的对象，它们本身必须可序列化。这些对象是否可序列化、序列化后语义是否等价，需要结合具体实现审计。
• 无界缓存的"轻量代理"：UnboundedLocalManualCache.writeReplace()只捕获isRecordingStats与removalListener（UnboundedLocalCache.java），无界缓存没有容量、过期、权重等配置，因此这是正确的裁剪；审计时要区分"有意不捕获"与"遗漏捕获"。

检查维度二：状态转移（State transfer）

第二个问题：序列化的是条目数据还是仅配置？如果是条目，如何处理各类特殊情况？

Caffeine 的答案是"仅配置、不含数据"（见类注释）。这让状态转移问题简化为三类衍生检查：

1. 条目是否被序列化：如果某个实现意外地把内部ConcurrentHashMap或节点对象卷入序列化图，就会破坏代理模式。审计方法是确认writeReplace()返回的是SerializationProxy而非缓存本体或内部数据结构。由于所有有界/无界缓存类都显式实现了readObject抛InvalidObjectException，任何绕过代理的直接反序列化都会失败——这是设计上的强制护栏。

2. 如果某个版本/分支确实序列化了条目，需要追问（对应技能清单）：

   • 已过期条目是否被过滤？若不过滤，反序列化出的缓存会带着"理论上已失效"的脏数据。
   • 异步值（CompletableFuture）是否被正确处理？序列化进行中的 future 会触发其内部状态机序列化，结果不可预期。
   • weak/soft 引用条目是否被解引用（dereference）？引用包装对象（如WeakValueReference）序列化后无法恢复引用语义。

3. 配置中携带的"可序列化但含状态"对象：ticker、weigher、expiry、cacheLoader若是带内部状态的自定义实现，其序列化副本在反序列化后可能携带了陈旧状态。从源码结构看，Caffeine 本身只负责把对象原样放进代理字段，对象自身的序列化语义由用户实现负责，这属于文档化边界，审计时应记录为"由用户实现承担的风险"。

检查维度三：反序列化一致性（Deserialized consistency）

反序列化得到的缓存是全新构造的，因此它的内部状态必须与"刚用同等配置构建的缓存"一致。审计关注以下内部结构的初始状态（SerializationProxy.readResolve() 直接走Caffeine.newBuilder()构建，不接触任何运行时结构）：

• 频率草图（frequency sketch）：readResolve()走 builder 新建，草图以初始容量分配，不携带任何历史访问频率。这是正确行为——配置级序列化不承诺保留频率历史；但若实现中误拷贝了旧草图，则会出现容量/哈希尺寸不匹配。
• 定时轮（timer wheel）：新建缓存的定时轮为空，所有过期条目不存在，因此expiresAfterAccessNanos、expiresAfterWriteNanos、expiry等只是"未来行为参数"，而不是"已排期事件"。审计应确认没有任何"排期中的过期任务"被序列化。
• drain status 与写缓冲区：drainStatus、写缓冲任务、deques（访问顺序/写入顺序队列）都是运行时易变结构，代理字段中不存在对应项；审计时确认它们没有被意外捕获。
• 权重计数器（weight counters）：weightedSize等计数器随条目数据一起归零，重建后从 0 开始累计——符合"仅配置"设计。
• 节点类型（node types）：有界缓存按配置组合生成不同的节点实现类（如PS、WSSMS），其序列化版本号（serialVersionUID）必须与代理版本兼容。审计时确认代理只依赖稳定字段，不依赖任何生成节点的内部布局。

检查维度四：跨版本兼容（Cross-version compatibility）

序列化代理是跨版本持久化的载体，因此必须回答：

1. serialVersionUID是否存在：SerializationProxy声明了private static final long serialVersionUID = 1（SerializationProxy.java），四个有界/无界缓存视图类同样声明了serialVersionUID = 1。审计应确认所有参与序列化的类（代理 + 视图类）都有显式版本号，避免依赖 JVM 按类结构推导的隐式版本号——后者在类结构变化时会直接抛InvalidClassException。
2. 旧代理能否被新版本反序列化：readResolve()只读取它认识的字段，新版本新增配置字段时，若采用"旧字段缺失时使用默认值"的策略，则旧代理流仍可被新代码读取。审计时核对所有!= UNSET_INT/!= null的判空分支是否都有合理的默认值兜底（UNSET_INT、false、null）。
3. 缺失字段的默认值是否正确：例如旧版本没有evictionListener字段，新版本反序列化旧流时该字段为null，recreateCaffeine()中的if (evictionListener != null)分支会跳过——行为正确，但语义上"旧缓存本来就没有驱逐监听器"，结果一致。

检查维度五：安全性（Security）

代理模式将序列化图收敛为白名单对象集合（SerializationProxy加少量配置对象），这天然缩小了攻击面，但仍需审计：

• 恶意构造的序列化流能否制造不一致状态：readResolve()中所有字段值都直接进入 builder 调用。需检查是否存在"通过字段组合触发非法配置"的路径，例如weakKeys与softValues的组合、maximumSize与maximumWeight同时设置（Caffeine builder 本身对互斥配置会抛IllegalStateException——审计时要确认这些校验在readResolve()路径上同样生效，因为反序列化绕过的是用户侧的 builder 调用链，但最终仍会调用Caffeine的字段赋值方法）。
• 输入是否被验证：代理字段中的maximumSize/maximumWeight/各*Nanos是原始long，恶意流可以写入任意值（包括负数或Long.MAX_VALUE）。审计需要确认 builder 的合法性校验（非负、非零等）覆盖反序列化路径，否则恶意流可能构造出"拒绝服务"级别的异常状态。
• 代理模式是否被正确实现：确认没有类同时暴露可序列化状态又未被writeReplace()拦截；确认readObject抛InvalidObjectException的护栏在全部视图类上存在。特别地，readResolve()返回的缓存对象是全新构建的，不含攻击者可控的运行时结构，这一点是有利的安全性质。

检查维度六：边界情况（Edge cases）

技能清单列出的四类边界情况，对应审计时的实际测试场景：

1. 序列化发生在操作进行中（in-flight operations）：Caffeine 的序列化路径只读取稳定的配置字段（makeSerializationProxy读取expiresAfterAccessNanos()、maximumAcquire()等），不触碰易变结构；但ticker、expiry、weigher、cacheLoader等用户对象在序列化瞬间可能处于被并发调用状态，若这些对象自身非线程安全，往返结果取决于对象的序列化实现。
2. 存在待处理的移除通知（pending removal notifications）：移除通知事件处于写缓冲区中，未被同步处理。由于序列化不携带数据与缓冲，这些事件在往返后自然丢失——审计应记录这一语义（不是缺陷，但需要文档化）。
3. LoadingCache携带不可序列化的CacheLoader：cacheLoader字段被直接写入代理（BoundedLocalCache.java、UnboundedLocalCache.java），若 loader 未实现Serializable，序列化会抛NotSerializableException。审计结论应标注为"使用约束"：只有 loader 可序列化时，LoadingCache 才能被序列化。
4. AsyncCache存在未完成的 future：底层存的是CompletableFuture，序列化仅配置、不含 future，因此未完成加载在往返后丢失；反序列化得到的是"空缓存 + 相同配置"，后续get会重新触发加载。审计确认 async 分支（proxy.async = true）与同步分支的还原语义各自正确即可（BoundedLocalCache.java）。

缺陷报告格式：字段、前后对照与严重度

审计发现的每个缺陷必须按统一格式输出，便于裁定与修复跟踪：

• 受影响字段/行为：明确是哪个代理字段或哪条还原路径（例如expiresAfterWriteNanos未在UnboundedLocalLoadingCache.writeReplace()中被继承捕获）。
• 往返前后对照（before/after）：序列化前的配置值 vs 反序列化后cache.policy()读出的实际值，用具体数值/布尔值表述差异。
• 严重度（severity）：按三类影响分级——
  • 数据丢失（data loss）：条目数据意外丢失或配置项静默消失（如maximumSize还原为未设置，导致缓存退化为无界）；
  • 错误行为（incorrect behavior）：配置错配导致行为漂移（如过期时间纳秒单位换算错误、async标志错位导致还原出错误缓存类型）；
  • 安全风险（security risk）：恶意序列化流可构造不一致状态或绕过校验（如负容量、互斥配置组合未被 builder 拦截）。

例如一次真实审计的模板化输出：

审计方法论补充：证据边界与置信度标注

一次合格审计不应只停留在静态阅读，还应在流程上对齐 auditor.md 中沉淀的审计纪律：

• 先分析、后裁定：先基于源码独立得出结论，再对照.claude/rules/与.claude/docs/design-decisions.md等设计文档做裁定，避免"已知设计决策"过早解释掉真实缺陷。
• 置信度三分法：高置信度发现、中等置信度怀疑（不得静默丢弃，须单独列出）、以及"从源码看属于设计如此但无法单独确认"的条目，三者分别标注。
• 高/严重级发现必须可复现：仅靠阅读源码得出的"高危/严重"结论是不够的，应构建可运行的证人测试（JUnit 方法或jshell片段，编译运行caffeine/build/libs/caffeine-*.jar），实际执行一次序列化往返并测量结果；无法复现的发现上限为中等严重度。
• 现有测试是意图证据而非正确性证据：CacheTest.java 中存在序列化相关测试，审计时应阅读它们覆盖的具体场景（例如是否只覆盖了强引用值而遗漏弱引用值、是否只验证了配置还原而没验证恶意流），若测试未触及缺陷路径，不能以此驳回发现。

总结：序列化代理审计的最终检查表

一次完整的audit-serialization审计，最终应能对以下问题逐项给出结论：

1. writeReplace()是否覆盖所有视图类，且readObject是否全部抛出InvalidObjectException？
2. 代理是否捕获了SerializationProxy全部 17 个字段对应的配置（容量/权重、三种过期、刷新、强弱软引用、监听器、ticker、统计、loader、async）？
3. 确认仅序列化配置、不序列化数据；若存在条目序列化分支，过期过滤、异步值、弱软引用是否被正确处理？
4. 反序列化后缓存内部结构（草图、定时轮、队列、权重计数）是否与"新建等价配置缓存"完全一致？
5. serialVersionUID显式存在，旧流在新版本下的字段缺失均有正确默认值兜底？
6. 恶意流不能构造非法配置、不能绕过 builder 校验？
7. 四个边界场景（in-flight、pending removal、不可序列化 loader、未完成 future）的语义是否被记录和验证？
8. 每个发现的缺陷是否带上了字段、往返前后对照与严重度分级？

按此清单逐项核查并输出结构化报告，即可完成对 Caffeine 序列化代理正确性与往返安全性的完整审计。

• 后端
• 缓存抽象