Guides Platform

Appearance

JaCoCo：从字节码探针到覆盖率报告的 Java 源码解析 ​

当团队问“测试覆盖了多少代码”时，真正困难的不是计算百分比，而是在不改写业务代码的前提下，把一次 JVM 执行可靠地记录下来，再把记录和编译后的类、源文件对应起来。JaCoCo（Java Code Coverage Library）把这件事拆成可复用的 Java 库、Java Agent 和 Maven/Ant/CLI 集成：类加载时插入探针，运行期间只更新探针数组，进程退出或通过 TCP/JMX 收集执行数据，最后由分析器和报告访问器生成 HTML、XML 或 CSV。

这篇文章固定在提交 e069c5a，从源码地图下钻到一条完整的“准备 Agent → 运行测试 → 读取 jacoco.exec → 生成报告”链路。源码只做静态阅读；没有执行仓库代码或构建脚本，因此命令部分标为文档/构建文件给出的路径。

GitHub 仓库信息 ​

信息内容
项目标题JaCoCo：Java 代码覆盖率库
项目描述面向 Java 程序的免费代码覆盖率库，通过字节码插桩和运行时探针收集执行数据，并提供可编程的分析与报告能力。
GitHub 仓库jacoco/jacoco
官网地址www.jacoco.org/jacoco
主要开发语言Java 84.22%、HTML 9.18%、Kotlin 2.89%
开源许可证Eclipse Public License 2.0（EPL-2.0）
最近代码更新2026-09-14（GitHub pushed_at，核对日期：2026-09-15）

仓库结构与模块职责 ​

根 POM 只负责聚合，实际模块由 org.jacoco.build/pom.xml 按依赖顺序装配。下面的树只保留阅读主链所需的语义入口：

text
jacoco/
├── org.jacoco.core/          # 插桩、运行时抽象、exec 数据、覆盖率分析
├── org.jacoco.agent.rt/      # 嵌入被测 JVM 的轻量运行时
├── org.jacoco.agent/         # Java Agent 外壳与运行时打包
├── org.jacoco.report/        # HTML/XML/CSV 等报告访问器与源文件定位
├── jacoco-maven-plugin/      # prepare-agent、report、check、merge 等 Maven 目标
├── org.jacoco.ant/           # Ant 任务
├── org.jacoco.cli/           # 命令行报告、合并和转储入口
├── org.jacoco.examples/      # ReportGenerator 等端到端示例
├── org.jacoco.*.test/        # 单元测试、集成测试和多 JDK 验证项目
├── org.jacoco.doc/           # 官网文档源文件
└── org.jacoco.build/         # 聚合构建、依赖版本与发布配置
读者问题主要源码位置作用
怎样给 class 文件插入探针？Instrumenter基于 ASM 读取类、选择探针策略并写回字节码；归档文件递归处理。
探针运行时怎样拿到数组？RuntimeData 与 Agent按类 ID、类名和探针数取得共享数组，维护 session 和输出生命周期。
怎样把执行记录还原成覆盖率？Analyzer 与 CoverageBuilder读取 class 结构和 probe 命中情况，聚合到包、类、源文件层级。
怎样生成报告或接入 Maven？IReportVisitor、HTMLFormatter、AbstractAgentMojo把覆盖率模型交给具体格式输出，并将 Agent 参数注入测试 JVM。

核心机制 ​

插桩只改变类定义，命中状态留在运行时 ​

Instrumenter 先用 CRC64.classId(source) 为原始 class 计算稳定 ID，再通过 ASM 的 ClassReader 和 ClassWriter 进入 visitor 链。ClassProbesAdapter 分析标签与控制流、分配可复现的 probe ID，并把 probe 事件交给下游；ClassInstrumenter 创建 MethodInstrumenter 和 ProbeInserter，真正向 class 写入探针数组访问与更新指令。ProbeArrayStrategyFactory 决定探针数组如何初始化。处理 JAR 时，instrumentAll 递归识别 class、ZIP、GZIP 和 Pack200 内容，签名文件会按 SignatureRemover 规则过滤，因为改写 class 会使原有签名失效。

这个边界带来一个关键转折：业务线程不需要频繁创建覆盖率对象，插入代码只负责把对应的 boolean[] 位置设为已执行。分析阶段再用相同的 class ID 把数组与原始结构匹配；类文件和执行数据来自不同构建时，Analyzer 会把不匹配的类标记为 noMatch，而不是悄悄给出可信的百分比。

Agent 管理一个线程安全的执行数据容器 ​

agent.rt 的 Agent.getInstance(options) 创建单例并调用 startup()。启动过程设置 session ID、根据 output 选择 FileOutput、TcpServerOutput、TcpClientOutput 或 NoneOutput，必要时注册 JMX，并加入 JVM shutdown hook。默认 destfile 是工作目录下的 jacoco.exec，dumponexit 默认开启；AgentOptions 还定义 includes/excludes、端口、类加载器过滤和 class dump 目录等边界。

RuntimeData 用同步块保护 ExecutionDataStore。插桩代码通过 generateArgumentArray 组装 (classId, className, probeCount)，再借用 Object.equals(Object) 这个 JRE 方法入口调用 getProbes(Object[])。getProbes 没有直接返回数组，而是把共享 boolean[] 回写到参数数组的第一个位置；生成代码丢弃 equals 的布尔结果，再从参数数组取回并转换为 boolean[]。这种调用避免让每个被测类直接依赖一个额外接口，但类 ID、类名和探针数量仍必须保持一致。

执行数据的流式格式 ​

RuntimeData.collect 先写入 SessionInfo，再让 ExecutionDataStore 输出每个类的执行数据；ExecutionDataWriter 和 ExecutionDataReader 通过 block header、session-info 和 execution-data 三类块传输。读取器会校验 magic number 和格式版本，遇到未知 block 或版本不兼容时抛出错误。

ExecFileLoader 在这个格式之上提供文件级便利 API：可以读取多个 .exec，合并 session 和类数据，也可以在保存时对目标文件加文件锁，降低并发写入互相覆盖的风险。TCP 输出把“何时 dump”交给外部控制，文件输出则适合测试进程退出后由构建工具继续处理。

分析器和报告访问器刻意分离 ​

Analyzer 从 class 文件或目录、JAR、GZIP 等输入中提取类结构，查找对应执行数据，并把 ClassCoverageImpl 交给 ICoverageVisitor。CoverageBuilder 接收这些类节点，延迟构建包、类和源文件层级，最后产生 IBundleCoverage。这个中间模型让同一份执行数据可以被不同报告格式复用。

报告端采用 visitor 契约。IReportVisitor.visitInfo 接收 session 和执行数据，visitBundle 接收覆盖率树与 ISourceFileLocator，visitEnd 完成输出。HTMLFormatter 将这些事件写成多页面 HTML；XML、CSV 和自定义格式可以实现同一组接口，而不需要改动核心分析器。

探针命中如何变成覆盖率计数 ​

probe 数组只回答“某个探针是否执行过”，覆盖率数字还需要重建方法的控制流。ClassAnalyzer 为每个方法创建 InstructionsBuilder 和 MethodAnalyzer；MethodAnalyzer 遍历 ASM 指令树，把顺序执行、跳转、switch 和带 probe 的边连接起来。InstructionsBuilder.addProbe 从 boolean[] 读取对应 probe ID 的状态，并把“已执行”标到控制流边上。

Instruction 沿前驱边传播已执行状态。每条字节码指令据此产生一个已覆盖或未覆盖的 instruction counter；只有至少有两条出边的指令才产生 branch counter，覆盖分支数取已命中出边的数量。源码行来自 class 调试信息，多个指令的计数按行聚合；没有行号时仍能得到指令和分支信息，却无法映射到源文件行。

编译器可能为 switch、协程、默认参数、record 或 try-with-resources 生成用户没有直接编写的分支。Filters.all() 先组合通用、Java 和 Kotlin 过滤器，MethodCoverageCalculator 随后应用 ignore、merge 与 branch replacement，最后把指令和分支计数写入 MethodCoverageImpl。因此报告中的行覆盖率不是直接读取 probe，也不是简单统计源码行；行覆盖率来自控制流传播、编译器过滤与按行聚合。

源码环境与最短有效体验 ​

从固定提交准备源码 ​

仓库的根 POM 是聚合入口，org.jacoco.build/pom.xml 声明模块顺序、ASM 9.10.1、JUnit 4.13.2 和 Maven 编译设置；Maven 插件模块 POM 声明 Maven 3.0 为最低前置版本，并以 Java 8 目标编译。源码本身没有常驻服务，最小环境是 Git、JDK、Maven Wrapper 或 Maven。

bash
git clone https://github.com/jacoco/jacoco.git
cd jacoco
git checkout e069c5a417e378053f7f8c9facde5918138e55ca
./mvnw -f org.jacoco.build/pom.xml verify

上面的构建命令来自聚合 POM 的静态结构推导，本次没有执行；真实成功信号应是 Maven 以 BUILD SUCCESS 结束，并在各模块 target/ 下生成构件和测试报告。JDK 与 class-file 版本不匹配、Javadoc 对高版本 JDK 的参数变化、或未能下载 Maven/ASM 依赖，都会在构建阶段失败。

用 Maven 接入一次测试覆盖率 ​

仓库 README 将 Maven 集成指向官方 Maven 文档；源码中的 AgentMojo 注解表明 prepare-agent 默认绑定 initialize 阶段，ReportMojo 默认绑定 verify 阶段。一个最小配置可以写成：

xml
<plugin>
  <groupId>org.jacoco</groupId>
  <artifactId>jacoco-maven-plugin</artifactId>
  <version>0.8.15</version>
  <executions>
    <execution>
      <goals><goal>prepare-agent</goal></goals>
    </execution>
    <execution>
      <id>report</id>
      <phase>verify</phase>
      <goals><goal>report</goal></goals>
    </execution>
  </executions>
</plugin>

然后在项目根目录运行：

bash
mvn verify

预期结果是测试 JVM 的 argLine 带上 JaCoCo Agent，项目 target/ 下出现 jacoco.exec 和 site/jacoco/index.html（实际路径随 Maven 报告配置变化）。如果项目已经自定义 Surefire 的 argLine，要保留 @{argLine} 或把 JaCoCo 生成的属性拼接进去；AgentMojo 的文档给出了 late property evaluation 配置，AbstractAgentMojo 则确认默认属性是 argLine，Eclipse test plugin 使用 tycho.testArgLine。这些步骤是仓库文档和 Mojo 配置支持的使用路径，本文没有运行被测项目。

整体架构与启动链 ​

Mermaid 流程图
查看源码
flowchart LR
  A[Maven prepare-agent / -javaagent] --> B[Agent startup]
  B --> C[ClassFileTransformer]
  C --> D[Instrumenter + ASM]
  D --> E[带 probe 的 class]
  E --> F[RuntimeData / ExecutionDataStore]
  F --> G{输出模式}
  G -->|file| H[jacoco.exec]
  G -->|tcpserver/tcpclient| I[TCP dump]
  G -->|jmx| J[JMX 控制]
  H --> K[ExecFileLoader]
  I --> K
  K --> L[Analyzer / ClassAnalyzer]
  L --> M[控制流传播 + Filters]
  M --> N[指令 / 分支 / 行计数]
  N --> O[CoverageBuilder / IBundleCoverage]
  O --> P[HTML/XML/CSV visitor]

启动入口有两个层次。Maven prepare-agent 在构建生命周期中计算 Agent JAR 和参数，并把参数写入项目属性；真正进入被测 JVM 后，Agent 才负责创建 RuntimeData、输出控制器和 shutdown hook。类加载器触发插桩，业务代码命中 probe，测试结束时输出执行数据；报告目标随后在另一个 Maven 阶段读取 class 文件和 .exec。

阶段入口关键状态失败或观察点
参数准备AgentMojo.executeMojoargLine/tycho.testArgLine自定义 JVM 参数覆盖属性会导致 Agent 未加载。
Agent 启动Agent.getInstance → startupsession、输出模式、JMX端口占用、输出初始化异常会阻止启动。
类插桩Instrumenter.instrumentAllclass ID、probe 策略、签名过滤不支持或损坏的 class/归档会产生带位置的 IOException。
运行时记录RuntimeData.getProbes、collectprobe 数组、session 时间戳同一 ID 下名称或探针数量不兼容会抛出 IllegalStateException。
报告生成ExecFileLoader → Analyzer → IReportVisitor执行数据、覆盖率树、源文件定位缺少 debug 信息时源码高亮不可用；class 与 exec 不对应时报告不完整。

核心链路矩阵 ​

链路入口与交接输出/副作用关键失败位置
生命周期Agent.getInstance → startup → shutdown hook → shutdown初始化输出、退出时 dump输出初始化、JMX 注册或关闭阶段 IOException
在线插桩Instrumenter → ClassInstrumenter → 带 probe 的 class改写 class 字节码，必要时移除 JAR 签名class/归档读取失败或不支持的字节码结构
探针访问生成参数数组 → RuntimeData.getProbes → ExecutionDataStore通过参数数组取回共享 boolean[]，按类累计命中同一 ID 下类名或探针数量不兼容
文件数据RuntimeData.collect → ExecutionDataWriter → ExecFileLoader.exec session 与 execution-data blocksmagic number、格式版本、文件锁或 I/O 错误
覆盖率计算ClassAnalyzer → MethodAnalyzer → Instruction → MethodCoverageCalculator控制流上的 probe 状态变成指令、分支和行计数编译器生成代码过滤、debug 行号或 class 版本差异
报告Analyzer → CoverageBuilder → IReportVisitorHTML/XML/CSV 等报告class 与 exec 不匹配、源文件或 debug 信息缺失
Maven 集成prepare-agent → 测试插件 argLine → report将 Agent 接入测试生命周期并在 verify 生成报告argLine 未传入测试 JVM 或数据/类目录不存在

正常链路之外，以下条件会改变数据采集或分析结果：

分流条件行为失败、恢复或观测入口
output=fileJVM 退出时按 dumponexit 写入 destfile检查输出目录权限、append 配置和进程是否正常触发 shutdown hook。
output=tcpserver / tcpclient由监听端或连接端交换 dump 命令和执行数据检查地址、默认端口 6300、连接方向；重新连接后再发起 dump。
output=none保留运行时数据但不建立输出通道需要通过 JMX 或嵌入 API 读取，否则进程结束后没有持久化结果。
includes / excludes / 类加载器选项在转换阶段缩小或扩大插桩范围用 classdumpdir 观察 Agent 实际处理的 class，按类名通配符修正过滤。
module-info / package-infoAnalyzer 主动跳过这两类定义属于确定性分析分支，不应当作覆盖率丢失。
同名 class 的 ID 不匹配Analyzer 在按当前 ID 找不到数据、但 store 中存在同名类时标记 noMatch用同一构建的 class 与 exec 重跑报告，必要时读取 getNoMatchClasses()。
同一 ID 下名称或探针数量不兼容ExecutionData.assertCompatibility 抛出 IllegalStateException清除旧 exec 或停止混合不同构建的数据，再重新采集。

源码能确认这些分支的入口和错误传播，但本文没有启动 TCP/JMX 服务，也没有验证各 JDK 的实际兼容矩阵。

设计取舍与扩展入口 ​

JaCoCo 的主要设计选择是“运行时轻、分析时重”。probe 数组和紧凑的二进制执行数据把运行期间的工作压缩到布尔标记与一次 dump，源码结构、源文件映射和多格式渲染延后到报告阶段。这适合 CI 中大量短生命周期测试，也允许一个 .exec 合并多个模块；代价是报告端必须拿到匹配版本的 class 文件和源文件，构建产物清理或混用版本会降低结果可信度。

第二个选择是用 visitor 契约连接核心模型与输出格式。要增加一种报告格式，优先从 IReportVisitor、IReportGroupVisitor 和 ISourceFileLocator 开始；要支持新的构建工具，参考 Maven 插件的 AbstractAgentMojo/AbstractReportMojo，把 Agent 参数和报告目标接入宿主生命周期。需要排查插桩问题时，进入 org.jacoco.core.internal.instr；需要排查“有 exec 但没有覆盖率”时，先检查 CRC64 class ID、类文件版本、过滤规则和 CoverageBuilder.getNoMatchClasses()。

JaCoCo 也有明确边界：字节码处理依赖 ASM 对目标 class-file 版本的支持，JDK 新版本通常先在 Release 中提供实验性兼容；对动态生成类、特殊类加载器和 bootstrap 类的覆盖需要额外过滤与参数；jacoco.exec 只记录探针命中，不等于测试质量，也不会替代变异测试、集成测试或生产流量分析。

适用场景与替代方向 ​

JaCoCo 适合已经使用 JVM 构建工具、希望把覆盖率作为 CI 门禁或代码审查信号的 Java/Kotlin 团队。Maven/Ant/CLI 集成、离线插桩和多种输出模式覆盖了从单模块测试到多模块聚合的常见路径。对只需要黑盒接口指标、无法控制被测 JVM，或主要运行在非 JVM 语言上的系统，接入成本会高于收益。

直接替代品可以按同一组维度比较。以下维护快照核对于 2026-09-15，只说明仓库活动，不证明质量或兼容性：

工具定位与插桩构建集成维护信号采用成本
JaCoCoJava Agent 在线插桩，也支持离线插桩；输出 exec 后独立分析Maven、Ant、CLI，Gradle 由 Gradle 插件集成0.8.15 发布于 2026-06-05，主仓库持续更新运行期开销较轻，但报告必须匹配 class、源码和执行数据
OpenCloverClover Core 与 IDE/Ant 集成，覆盖率工作流与 JaCoCo 不同README 列出 Ant、Eclipse、IDEA，并链接独立 Maven 与 Gradle 插件仓库固定提交 e4948ce；仓库未归档，2026-08-19 仍有推送迁移需评估既有插件、配置、报告与 Apache-2.0 许可边界
Cobertura免费 Java 覆盖率报告工具，保留既有 Cobertura 格式生态固定 README 提供 Maven 依赖与独立 CLI 分发路径固定提交 0ff9632；仓库未归档，最近推送为 2023-05-29对新 JDK/class-file 的支持需单独验证，主体为 GPL-2.0 许可

PIT 不属于同类替换。PIT 修改代码并检查测试能否识别这些变化，回答的是测试断言是否有效；JaCoCo 回答哪些指令和分支被执行。固定 README 将 PIT 定位为 JVM 变异测试系统，并记录 Maven/插件相关能力。团队可以先用 JaCoCo 找覆盖盲区，再用 PIT 检查高覆盖代码是否仍有薄弱断言，但要接受更多测试运行成本。

构建、调试与常见问题 ​

报告为空或覆盖率全为 0。 先确认测试 JVM 实际收到 -javaagent，再检查 .exec 是否由同一轮测试生成；Maven 的 argLine 被覆盖是常见的集成断点。随后检查 Analyzer 的 class 输入是否与执行数据来自同一构建。

出现 no-match 类。 Analyzer 以 class ID 匹配执行数据。重新生成 class 和 .exec，避免把不同版本的 target/classes、缓存报告或合并文件混在一起；CoverageBuilder.getNoMatchClasses() 可用于定位这类问题。

抛出 Incompatible execution data。 ExecutionData.assertCompatibility 会分别核对 ID、类名和 probe 数量。同一 ID 下的名称或数组长度不一致会抛出 IllegalStateException；这与报告阶段的 no-match 标记不是同一种状态，应清除或隔离旧执行数据后重新采集。

源码高亮缺失。 ReportGenerator 的注释要求被测 class 带 debug information；报告端还必须能通过 DirectorySourceFileLocator 找到与包路径对应的源文件。只有 exec 文件而没有源目录时，仍可生成结构化报告，但不能期待源码行级展示。

TCP 输出无法 dump。 AgentOptions 默认端口为 6300；tcpserver 必须绑定可用端口，tcpclient 必须能连接目标地址。容器或 CI 环境中还要检查网络命名空间和端口暴露，不能把本机可达性当作远端可达性。

升级 JDK 后构建或运行失败。 根构建 POM 固定 ASM 版本和编译目标，Release notes 以版本为单位声明新 class-file 支持。先按目标 JDK 对照对应 Release，再确认 Maven/Javadoc 插件配置；不要仅凭旧版本经验推断 Java 25/26/27 的兼容性。

总结与后续阅读 ​

JaCoCo 的核心不是一张 HTML 百分比表，而是一条阶段清晰的数据流水线：ASM 插桩建立探针，Agent 在 JVM 内维护布尔数组，exec 格式把运行记录带到进程外，Analyzer 再用匹配的 class 还原覆盖率结构，报告 visitor 最后决定输出形式。运行时轻量与分析期解耦适合 CI 和构建工具集成；相应代价是 class、源码、exec 和工具版本必须保持一致。覆盖率适合作为发现盲区与设置门禁的信号，不能单独证明测试有效。

想扩展报告格式，从 org.jacoco.report 的 IReportVisitor 和 HTMLFormatter 开始；想理解覆盖率为何会“错配”，沿 Instrumenter 的 CRC64.classId、RuntimeData.getProbes 和 Analyzer.createAnalyzingVisitor 走一遍；想把 JaCoCo 接入另一个构建系统，参考 Maven 插件如何生成 Agent 参数并把属性交给测试宿主。真正需要验证某个 JDK、类加载器或 TCP 拓扑时，再建立隔离环境运行对应的仓库测试和最小示例。

参考资料 ​

全部公开文章由同一个站点构建和发布。

Guides Platform