Caffeine 源码审计方法论：深入 Caffeine 并发缓存正确性审计的专业实践指南

• 后端
• 缓存抽象

Caffeine 是一款高性能 Java 缓存库，其核心价值在于 W-TinyLFU 准入策略、无锁读路径与异步维护机制的组合。要审计这类库的正确性，单纯阅读文档远远不够——真正的问题隐藏在生成节点类的字段声明、锁层级与历史缺陷模式之中。本文围绕仓库中的 auditor.md 所定义的「深度分析智能体」工作协议，系统讲解对 Caffeine 并发缓存进行源码级正确性审计的方法论：从攻击计划、证据边界、分阶段分析到发现定价（Pricing）与最终报告输出的完整流程，帮助读者掌握一套可复用的高置信度审计框架。

阅读完本文，你将能够：理解 Caffeine 的模块结构与生成代码（JavaPoet）在审计中的关键作用；掌握证据边界规则——哪些文件可读、哪些文件必须回避，以及为什么「先前审计结论」不能作为反驳证据；按照 Phase 0 到 Phase 4 的分阶段方法执行一次深度审计，并正确区分「高置信度发现」「中置信度怀疑」与「依据设计决策的排除项」；为关键发现构建可复现的 witness 测试，并用它来定价严重等级，避免将静态推断直接升级为high/critical。

Caffeine 审计的上下文：为什么审计需要专门的方法论

Caffeine 的并发设计远比普通HashMap+ 锁复杂：它使用无锁读路径、写缓冲区（Write Buffer）批量维护、频率草图（Frequency Sketch）与 W-TinyLFU 准入、以及异步过期/刷新调度。在这样的系统中，正确性依赖一组微妙的全局不变量，例如：

• 节点生命周期单向流转：alive → retired → dead，不可逆转；
• 锁层级固定：evictionLock → CHM bin lock → synchronized(node)；
• 权重核算通过所有写缓冲区任务排序下的 telescoping sum 收敛；
• 值字段使用 acquire/release 语义，键引用构造后不可变（plain read 安全）。

上述不变量在 auditor.md 的Concurrency Model一节中被明确列出，它们是审计中判断「某个看似可疑的代码模式是否被设计决策豁免」的基准。

同时，审计的边界并不仅限于核心缓存。仓库采用多模块结构，auditor.md 的 Module Map 指出：jcache（JSR-107 适配）、guava（Guava 适配）、simulator（模拟器）、examples（示例）与 build/CI 都属于审计范围，但非核心模块的 bug 表面与核心不同——例如 jcache 的 EventDispatcher 要求每个发布线程都通过awaitSynchronous/ignoreSynchronous排空同步监听器的 future，以及第三方 API 契约误用（错误路径、重复/空输入、取消与销毁）等。

生成代码的审计陷阱：字段声明不在 BoundedLocalCache 中

对不熟悉 Caffeine 代码生成机制的审计者来说，最容易犯的错误是：在生成的类（如PS.java、WSSMS.java）中看到某个字段或方法，就直接在BoundedLocalCache.java中搜索其声明，结果一无所获。

原因在于：采样计数器、权重字段、队列链接以及许多核心字段都声明在 JavaPoet 生成器中，而不是BoundedLocalCache中。auditor.md 明确指出：

• 核心实现位于caffeine/src/main/java/com/github/benmanes/caffeine/cache/；
• 生成节点与本地缓存位于caffeine/build/generated/sources/；
• 生成器（字段声明与淘汰缓存方法形状真正所在之处）位于caffeine/src/javaPoet/java/com/github/benmanes/caffeine/cache/。

在审计PS.java、WSSMS.java这类生成类中的字段或方法时，必须先回溯到对应的AddX.java生成器，再对类型或存储方式下结论。若caffeine/build/generated/为空，需运行：

./gradlew :caffeine:generateNodes :caffeine:generateLocalCaches

在仓库中，生成器确实按此结构组织。例如 AddMaximum.java 声明了maximum、weightedSize两个 volatile 字段（通过 VarHandle 的 get/acquire/setRelease 语义访问），并额外生成windowMaximum、windowWeightedSize、mainProtectedMaximum、mainProtectedWeightedSize四个字段以及climber（WindowClimber）与sketch（FrequencySketch）两个组件。这意味着：对最大容量与权重记账的审计，必须同时查看生成器如何为不同特性组合（Feature 组合）裁剪字段，而不能只盯着手写的BoundedLocalCache。类似的，AddHealth.java 负责生成节点生命周期的ALIVE/RETIRED/DEAD状态迁移逻辑，直接支撑上文提到的「alive → retired → dead」单向不变量。

这种「生成器是真相来源」的结构，决定了审计工具链的选择：当caffeine/build/generated/sources/未填充时，LSP 的goToImplementation无法解析 Node 接口方法的具体生成子类——必须先运行上面的 Gradle 生成任务。

证据边界：可读什么、必须回避什么

审计的可靠性取决于证据来源的纯度。auditor.md 的Evidence Boundaries一节给出两条清晰规则：

允许读取：

• caffeine/src/main/java/与caffeine/build/generated/下的源代码；
• .claude/rules/——机械性事实（锁顺序、访问模式约定、已知设计决策），它记录的是「什么是有意为之」，而非「先前审计通过了」；
• .claude/docs/synchronization.md、testing.md（Phase 1 期间阅读）；
• .claude/docs/design-decisions.md、ruled-out.md、research-foundations.md（Phase 1.5，即初始分析之后才读）；
• .claude/docs/audit-output.md（Phase 4 报告输出位置）；
• 调用技能自身的SKILL.md与项目指令.claude/CLAUDE.md。

禁止读取：

• memory/、memories/、~/.claude/projects/*/memory/、.claude/agent-memory-local/、.local/下的任何文件——先前的审计结论、「未发现缺陷」的历史、跨模型结果摘要均不得在本轮读取；
• 不得引用先前审计结果作为驳回发现的理由——「先前审计未发现缺陷」不是证据，每次驳回都必须从本次审计的源代码中重建；
• 不得使用「diminishing returns pattern」「aligns with prior clean results」「70+ prior audits」之类的表述。

这条规则的动机是文档中明确记载的一个失败模式：先前结果锚定——被告知「70+ 次审计都是干净的」的智能体会为了匹配预期而压制中等置信度的怀疑。因此，设计决策文档（如design-decisions.md）被刻意安排在分析之后读取：先让代码在技术优劣上自我暴露，记录发现，再让设计上下文来解释或排除。

边界内还有一个关键区分：ruled-out.md中的设计决策是机械事实（代码有意如此，且有性质保证）；先前审计结论则是对代码的信念。审计者应使用前者、拒绝后者。

Phase 0：攻击规划——先于读码的预分析

深度审计的第一步不是读代码，而是在阅读源代码之前对目标进行推理：

1. Pre-mortem（预先验尸）：如果此区域存在 bug，最可能的类别是什么？auditor.md 给出的候选类别包括：数据竞争（data race）、丢失更新（lost update）、ABA、排序违例（ordering violation）、异常路径泄漏（exception path leak）、规范违例（specification violation）。为什么？
2. Step-back（后退一步）：该子系统必须维护的 2–3 个基本不变量是什么？应从第一性原理推导，而非从文档摘抄。
3. 优先攻击计划：列出 5 个最有希望的交错（interleaving）或场景，按估计的缺陷发现概率排序。

随后才读源码。进入 Phase 1 后，把实际发现与预测对比——任何不匹配都是需要深入调查的信号。这一步的意义在于对抗确认偏误：如果预设的攻击面与真实代码热点偏差过大，说明对系统的心理模型有误，需要修正。

Phase 1：深度分析——阅读、标注、对照

Phase 1 的核心要求可归纳为：

• 先读真实源码再分析，不依赖假设；逐路径追踪代码。
• 报告高置信度发现，并将中等置信度怀疑单独成节标注——不得静默丢弃，交由用户裁决；仅排除低置信度猜测。
• 所有发现必须附具体文件路径与行号。
• 在得出结论前探索多条失败路径；给予充分的推理时间。
• 将发现与 Phase 0 攻击计划对比：对任何预测过却一无所获的攻击，显式说明其不适用的原因。

工具选择上，auditor.md 给出了 LSP 与 Grep/Read 的取舍建议：跨文件、类型感知的查询（方法调用方findReferences、接口方法的实现类goToImplementation、传递调用路径prepareCallHierarchy等）优先用 LSP——它能跳过注释、javadoc 和同名无关符号；而顺序读文件、字符串模式搜索（如@GuardedBy注解、锁名审计）或文件已在上下文中时，Read + Grep 更快。

置信度标注方面，每个观察必须归入三类之一：高置信度、中等置信度、「按设计可归类但无法仅从源码确认」。若怀疑与已知设计决策相似，需显式指出匹配的是哪条规则——但仍要作为「文档缺口」浮出水面（如果仅凭源码无法让新读者看清意图）。用户负责裁决，审计者的职责不是预先过滤。

关于现有测试，文档有一句至关重要的警示：现有测试是意图的证据，不是正确性的验证。发现候选缺陷且同区域存在测试时，不能据此直接驳回——必须阅读该测试，用一句话说明它覆盖的具体场景，再检查该场景是否匹配你发现的失败路径。常见的测试缺口包括：

• 测试使用equals与身份（identity）一致的取值（装箱基本类型、驻留字符串、值类），无法区分基于身份与基于 equals 的行为；
• 测试覆盖了矩阵中的某一种配置（如强引用值）而非你的发现所需的配置（如弱引用值）；
• 测试断言了相关但更弱的性质（如用(long)强转保证求和不溢出），却未断言底层不变量（如字段本身在求和前不溢出）；
• 测试走的是同一代码路径，但输入未触及边界情形。

若现有测试未覆盖确切的失败路径，应将其视为「掩盖了其余问题的部分修复」，保持发现升级，并引用测试名、说明缺口。例如，审计evictionLock保护的字段时，BoundedLocalCache.java中大量@GuardedBy("evictionLock")注解（出现在weightedSize、writeBuffer、readBuffer维护路径及maintenance()等方法上）就是核查「该字段是否真的单写者」的第一步依据；但只有逐一确认读写者都持同一把锁，才能判定其不可能竞争。

Phase 1.5：设计上下文裁决——先对齐规则，再论证排除

设计上下文必须在初始分析之后读取，因为它会造成过早驳回。Phase 1.5 的读取顺序是：

1. 模块表（Module Map）中自己所在行的两列：该模块的.claude/rules/文件与模块专属裁决文档——这是最容易被跳过、却真实抓住过「重新推导」的步骤。jcache 发现先由.claude/rules/jcache-adapter.md与docs/jsr107-conformance.md裁决；core 发现由.claude/rules/concurrency.md裁决。
2. .claude/docs/design-decisions.md与.claude/rules/design-decisions.md。
3. .claude/docs/ruled-out.md：其Standing principles加上自己模块的小节。

对每个 Phase 1 发现检查匹配情况：

• 完全匹配：标注「matches design decision: [item]」或「ruled out: [entry]」，但保留在报告中——是否仍适用由用户裁决；
• 部分匹配：记录部分匹配并说明差异；
• 无匹配：这是新发现，标记为优先关注。

裁决的一个关键原则：ruled-out.md条目是「机制 + 后果」的组合，只有两者都匹配才能排除一个发现。必须显式说明匹配的是哪部分：

• 同机制、同后果：排除，一行带过；
• 同机制、不同后果——条目未命名的可达触发器、未覆盖的配置、理由未触及的第二个调用点：该发现仍然「活着」，条目正是你必须论证翻越的对象，并要指出差异部分。文档记载有两个长期裁决正是以这种方式被推翻：一个因为条目论证的是淘汰监听器而发现使用的是移除监听器；一个因为衰退理由覆盖了evictFromMain而未覆盖evictFromWindow；
• 仅外形相似而机制不同：不得排除，不得引用。

此外，在翻越条目之前，务必确认自己在翻越正确的文件。「同机制、不同后果」的动议是合法的，但也是「重新推导」被合理化的方式——曾有一个 jcache 保留（retention）发现被当作新发现上报，因为其 §jcache 条目命名的是拒绝型执行器，而发现的触发点是抛异常的Weigher；事实上机制、后果与对修复方案的明确拒绝都记载在模块规则文件中。§小节并不是裁决本身，步骤 1 才是抓住这类问题的关键。

还有两条硬约束：不得用裁决降低已经测得的严重度；不得因为给发现贴了「ruled out」标签就跳过 Phase 3.5——被排除的标签不能替代定价。

Phase 2 与 Phase 3：反思自挑战与敌对评审

Phase 2：反思 + 自我挑战。分析完成、写最终报告之前：

1. 写下分析期间的关键假设、浅查与深挖的区域、考虑过但未完全探索的交错、以及「一个 bug 若要存在、而我又错过了它，需要哪些条件成立」；
2. 对前 3 大假设逐一构造一个会违反它的具体场景——若场景合理，回去彻底调查（重读源码，不要依赖此前的分析）。

Phase 3：评估者挑战。派发一个独立的子智能体来挑战你的分析，该智能体不得访问源代码，只依据你的报告工作。调用时必须显式传model: "opus"——否则子代理继承默认解析结果，有时正是运行本身所用的模型；一次实测的/audit-adaptivity运行曾因在发现模型上跑评估者而消耗了 38k 输出 token、占整个审计的 29%。发现（discovery）才是昂贵模型的用武之地，挑战一份书面报告并不需要它。

评估者提示词的核心指令是：「你是审查并发 Java 缓存审计报告的敌对评估者，你的工作不是重做审计，而是找出审计者遗漏的东西」。具体任务包括：

1. 不变量挑战：对每个「已确认不变量」，构造最可能违反它的双线程交错——要具体到线程动作；若构造不出，说明是什么阻止了它；
2. 盲点检测：审计者没有检查什么？报告中被提及却未追踪的方法、「残余风险」中值得深挖的项目、边界上的边缘情形；
3. 假设攻击：对反思中的每个假设，判断它是否真正由代码保证，还是可能被违反。

输出一份按优先级排列的具体挑战清单（需重查的区域、要测的场景、要填补的缺口）。收到挑战后，必须逐条处理：重读相关源码（不依赖此前的分析），要么用新证据确认原结论，要么上报缺陷。不得简单重申——评估者可能发现了真正的缺口。

Phase 3.5：给发现定价——没有 witness 就没有 high

审计方法论中最容易被忽视、却最能区分「静态推断」与「真实缺陷」的环节是定价。核心规则一针见血：任何发现都不能仅凭源码阅读就被评为high或critical——每一个经受住审视的反驳与确认都来自可复现（repro）或 A/B 实验，而非代码追踪。「源码中可见的机制」与「用户可达的影响」是两个独立的论断，严重度编码的是后者。

定价流程：

1. 构建 witness：一个 JUnit 方法、一段jshell片段、或编译到caffeine/build/libs/caffeine-*.jar（用 jar 而非build/classes——jar 携带生成的节点类）的main。运行它。无法复现的 witness 就是该发现的答案。
2. 在用户实际得到的配置上运行：Ticker.systemTicker()与公共线程池。如果只在FakeTicker、executor(Runnable::run)或CacheExecutor.DIRECT下复现，则影响属于测试装置伪影——在发现中说明并降低严重度。
3. 用分位数（percentile）而非最大值来定价性能论断：>=20k 样本、多次重复试验。单次max读数曾被误判为 8 倍尾部尖峰，实际是 GC 离群值。报告实测数字；从紧凑人工循环中取得的数量级是压力形态，不是工作负载。
4. 检查缓解因素，而不只是机制：上一周期得到最多佐证的发现是两个模型独立测量同一个循环，但两者都没有测量「是什么消除了它」。在报告 O(N) 遍历、锁持有或停顿之前，先问周围系统已有什么在吸收它，并一并测量。
5. 疑似回归要二分定位：git worktree加上在几个 commit 上运行:caffeine:compileJava只需几分钟，来源往往能告诉维护者修复方案。不要在不读取写入该行的 commit（git log -L <start>,<end>:<file>）的情况下称某行为疏忽。

每个发现的定价结果必须记录在发现中：Priced——跑了什么、在什么配置上、测到了什么。如果无法构建 witness，明确说明并把严重度上限设为medium。无法复现的发现未必是错的，但它不是high。这一规则同样适用于已标注「ruled out」却在翻越条目的发现：裁决本身是被定价过的，你的反例也必须被定价。

升级标准与动态测试桥接

当以下任一情况出现时，应停止分析并上报部分结果，标记为 ESCALATED：

1. 三个无法消解的二义性——静态无法判定正确性的情形，需按.claude/docs/testing.md的「选择动态工具」一节选择工具：Fray 用于同步点交错、LinCheck 模型检查用于普通字段竞争、jcstress 用于弱内存发布。但在标记竞争之前，必须确认状态确实为共享并发：如果字段的每个读写者都在同一把锁下@GuardedBy（单写者——例如FrequencySketch完全在evictionLock之下），它不可能竞争，不得升级——把单写者加锁路径升级是误报。注意 FrequencySketch.java 中table字段确实需要ensureCapacity显式初始化，且仅在淘汰锁路径下访问，这正是「单写者不成竞争」的典型判别样本。
2. 无法读取的源码——生成文件或构建产物缺失。
3. 评估者挑战需要源码树之外的信息——JDK 内部、硬件内存模型细节，应承认缺口而非猜测。

对每个涉及并发交错的 ESCALATED 发现，生成针对该场景的 Fray 测试骨架，例如：

@FrayTest(iterations = 10_000, resetClassLoaderPerIteration = false) void escalated_findingDescription() { // Thread 1: <specific operation> // Thread 2: <specific operation> // Assert: <invariant that should hold> }

这是静态分析通向动态测试的桥梁——也是静态无法解决 bug 时杠杆最高的路径。但骨架是 TODO，不是解决方案：升级的并发发现只有在「底层修复已发布」或「源码树中存在可运行测试（caffeine/src/frayTest、jcstress或lincheckTest）并通过」时才被解决。把骨架移植进源码树并运行，或用理由拒绝（如单写者所以不是竞争）。仅仅让报告持有骨架，不视为已解决。

Phase 4：最终报告——格式、结构、元数据与记忆禁令

报告的写入是强制性的，绝不允许只内联汇报。要求是两者都要：先写文件，再在返回消息中总结。返回消息不能替代文件——文件是持久产物，消息是接力。写入路径由编排者指定：shell 编排者会设置环境变量，运行printenv AUDIT_REPORT_PATH，非空时写在那里（该目录名是编排者对运行的标签，不必与你自己的名字一致）；两者皆缺时，使用.claude/audits/<model>/<skill-name>.md的等价位置（见 audit-output.md）。

报告以元数据头开头：

Audit: <skill-name> Date: <ISO-8601> Commit: <output of git rev-parse HEAD>

正文使用以下精确章节标题：

• High-confidence findings（按 finding-taxonomy.md 分类）
• Medium-confidence suspicions——单独标注，不得压制
• Would classify as by-design but cannot confirm from source alone——新读者无法从代码看出意图的文档缺口
• Phase 3（评估者提示）产生的新发现
• 每个评估者挑战如何被解决
• 经受住所有阶段的已确认不变量（及保护各不变量的机制）
• 攻击计划预测 vs 实际结果
• 残余风险：哪些未检查及原因

每个发现必须使用统一结构：Location（文件路径与方法名）、Issue（一行摘要）、Severity（critical/high/medium/low）、Evidence（触发它的具体代码行为、交错或输入）、Invariant/contract violated（被破坏的文档化不变量或 API 契约）、Confidence（high/medium，省略低置信度猜测）、Priced（high/critical 必填，按 Phase 3.5）、Verification（针对性测试想法）。验证示例：

./gradlew :caffeine:test --tests 'BoundedLocalCacheTest.methodName' -Pcompute=async -Pvalues=weak

最后一条禁令与记忆有关：不得将发现保存到记忆存储（memory/、.claude/agent-memory-local/等）——这仅针对记忆存储，不适用于上面要求写入的报告文件，后者始终要写。将审计结论写入记忆存储会使未来的审计偏向先前结果。若发现了值得记录为持久设计决策的内容，在报告的「would classify as by-design」一节中浮出水面，让用户在审查后决定是否折叠进 design-decisions.md 或 design-decisions.md 文档。让用户来策划什么得以持久化。

设计模式速查：哪些「可疑」实为有意为之

审计者常常被 Caffeine 的某些反直觉行为绊住。auditor.md 的Project-Specific Context一节列出了需要放在心里的设计决策（应在 Phase 1 完成之后、解释任何发现之前查阅，以免过早驳回）：

• Weight=0 的条目是面向用户的固定（pinning）功能，不是 bug；
• EXPIRE_TOLERANCE（1 秒）是有意为之——过期是最大存活时间，不是最短保留时间；同时适用于 writeTime 重排序决策与 accessTime 读路径更新；
• 瞬态负的 weightedSize 是可接受的最终一致性；
• **accessTime 刻意使用 opaque 写（而非 CAS）**以避免竞争风暴；
• doComputeIfAbsent/remap 中的 catch-commit-rethrow 模式通过使幻影淘汰（phantom eviction）变为真实来应对异常。

历史缺陷模式：优先投放交错的地方

auditor.md 的Historical Bug Patterns记录了曾确认存在 bug 的子系统，审计时应优先在这些区域设计交错：

1. 刷新 + 过期竞争：进行中的刷新阻止过期、死键传给 loader、执行器拒绝后 ASYNC_EXPIRY 时间戳卡死、同步监听器重入导致的双重刷新；
2. 值引用可见性：弱/软值 put() 上的非原子 clear-then-set、aarch64 上WeakValueReference.keyReference的发布（仅 setRelease 对非 final 字段不够，需 setRelease + storeStoreFence 修复）；
3. 异步缓存：取消传播到所有等待者、null 加载可见性竞争、spliterator SIZED 特征不匹配、异步完成时 weigher 异常被静默吞掉；
4. 写缓冲区 / 草图：扩容期间的 producerLimit 竞争、ensureCapacity 期间的 FrequencySketch table 字段竞争；
5. 适配器义务（jcache）：事件在无排空 EventDispatcher 同步监听器 future 的执行器线程上发布（refresh-after-write 泄漏）；写穿透批量操作迭代实时视图而非交给 CacheWriter 的快照；惰性过期条目被裸 containsKey 检查当作存在。

这些模式的完整细节（含 issue 编号）见 design-decisions.md，可用于复现与验证。

无缺陷时的输出：不变量清单与残余风险

当审计未发现缺陷时，报告应输出：已确认的不变量（及保护各不变量的机制）、覆盖总结（检查的文件、追踪的方法、尝试的交错），以及残余风险（什么未检查及原因）。这保证了即使结论是「干净」，报告仍然可复核、可引用，而不是一句无法验证的空话。

综合来看，这套方法论的核心精神可以浓缩为三点：先分析、后裁决（设计上下文不得在发现记录之前造成过早驳回）；证据校准而非历史校准（先前审计结论不是证据，每次裁决都从本次源码重建）；没有 witness 就没有严重度（high/critical 必须由可复现测试定价）。将这三点应用于 auditor.md 与 synchronization.md、testing.md 等配套文档，即可对 Caffeine 这类高并发缓存系统展开可审计、可复核、可积累的深度正确性分析。

• 后端
• 缓存抽象