单位测覆盖率做到 80% 以上并不难，难的是把集成测试的覆盖率也拉起来，尤其是当被测服务部署在两台以上机器、流量还被网关打散的时候。很多人卡在集成测试篇的原因并不是不会写测试代码，而是数据收不齐：JaCoCo 的 exec 文件散落在各个节点上，SonarQube 上最终显示的覆盖率要么只有单元测试那一份，要么数据合并后报表完全失真。这篇是系列的第三篇，前面两篇把 SonarQube、Jenkins 和 JaCoCo 在单机上的“最小闭环”搭起来了，这篇专门解决集成测试阶段的覆盖率聚合问题。单节点怎么配、集群怎么配、合并 exec 文件的时候有哪些隐藏前提、SonarQube 显示的覆盖率到底该怎么解读，全部按实际落地的顺序讲清楚。
1. 集成测试覆盖率为什么和单元测试差这么远
先说一个容易混淆的点：很多人把“集成测试”理解成“在测试环境里用脚本调了一遍接口”，然后直接拿 JaCoCo agent 挂在服务上，跑完看 SonarQube 的覆盖率。这种做法在单节点上勉强能看，一旦上集群就没法解释数据了，根源在于 JaCoCo 的数据收集机制和集成测试的运行形态天然是矛盾的。
单元测试是进程内执行的，JaCoCo 通过 javaagent 把探针注进被测代码，测试方法跑完以后，覆盖率数据直接 dump 到某个 exec 文件，整个过程只有一个进程、一份数据、一次落盘。集成测试则完全不同：被测服务是独立进程，可能部署在两台、三台甚至更多的机器上；测试流量从网关进来以后，同一个接口可能被负载均衡打到不同节点，每个 JVM 各自维护自己的执行数据。如果你只在某一台机器上挂 agent，那从报表上看到的覆盖率天然就是残缺的，甚至只有某个节点的局部数据。
这就引出了集成测试覆盖率的第一个设计问题：到底谁产生覆盖率数据？答案是被测服务进程本身，不是测试代码。所以落地方案的第一步不是写测试，而是决定用什么方式挂 JaCoCo 探针、exec 文件写到哪里、最后怎么汇总。挂探针的方式有两种，on-the-fly（运行时插桩）和offline（离线插桩）。集成测试基本都用 on-the-fly，也就是用-javaagent参数在 JVM 启动时动态修改字节码；offline 需要构建阶段就把插桩后的 class 打进去，流程繁琐而且容易污染部署包，非特殊需求不建议碰。
另一个和第 1 篇不同的点：单元测试通常由 Maven Surefire 插件执行，集成测试则由Maven Failsafe 插件执行。很多人根本不知道还有第二个插件，于是把集成测试类命名成*Test交给 surefire，进程是跑起来了，但生成了两份混在一起的数据。规范做法是单元测试类用*Test结尾、集成测试类用*IT结尾，failsafe 默认匹配*IT.java。这样单测和集成测试的 exec 数据就能通过不同 phase 自然地区分开。
2. 单节点集成测试覆盖率的一条龙配置
先讲最简单的场景：被测服务就部署在一台机器上，Jenkins 在同一台机器上或通过 SSH 远程控制，测试流量只有一份。这个场景把配置理顺之后，集群模式的核心逻辑也就清晰了，因为集群只是“多复制几份单节点的数据再合并”。
2.1 pom 里最关键的两段配置：agent 参数与 Failsafe 绑定
要让 JaCoCo 在集成测试阶段收集数据，第一步是在被测服务的pom.xml里配置 agent 参数。这里我见过太多人直接把destfile指向target/jacoco.exec，结果和单元测试的数据写进了同一个文件，后面怎么合并都说不清。正确做法是给集成测试单独指定一个 exec 文件，比如target/jacoco-it.exec，并且把append设成true。append这个参数单独拎出来说，是因为如果你在同一台机器上分多轮跑集成测试，每轮 JVM 启动都会重新生成 exec，不设置 append 的话只有最后一轮数据能留下来。
<plugin> <groupId>org.jacoco</groupId> <artifactId>jacoco-maven-plugin</artifactId> <version>0.8.12</version> <configuration> <destFile>${project.build.directory}/jacoco-it.exec</destFile> <append>true</append> </configuration> <executions> <execution> <id>prepare-agent</id> <phase>pre-integration-test</phase> <goals> <goal>prepare-agent</goal> </goals> </execution> <execution> <id>report-integration</id> <phase>post-integration-test</phase> <goals> <goal>report</goal> </goals> </execution> </executions> </plugin>另一个容易忽略的问题是argLine 的传递链路。prepare-agent目标会把一段-javaagent:...参数写入 Maven 的argLine属性，但这个属性默认只对 surefire 和 failsafe 的 forked JVM 生效。如果你的 pom 里自己定义了<argLine>，就会把 JaCoCo 的那段参数覆盖掉，导致探针根本没挂上。我自己排查过最诡异的一个“零覆盖率”问题，最后就是项目里某次升级时加了一段${argLine}之前的-Dfile.encoding=UTF-8，把探针挤掉了。
2.2 从 exec 到 SonarQube 能识别的 XML 报告
exec 文件是 JaCoCo 的二进制格式，SonarQube 不能直接读，需要先生成 XML 报告。上面的report-integration执行会生成target/site/jacoco-it目录，里面有 HTML 和 CSV，但默认不输出 XML。要在 SonarQube 里看到集成测试覆盖率，必须让 report 目标输出 XML 格式的报告：
<configuration> <excludes>...</excludes> <outputEncoding>UTF-8</outputEncoding> </configuration>其实更实用的做法是用report-integration的完整配置，它继承report的默认行为，只需要额外指定格式。如果用的是 SonarQube 9 及以上版本，Sonar 扫描器会读取sonar.coverage.jacoco.xmlReportPaths指向的 XML 文件。这一步常见的坑是路径写错：单模块项目可以写成target/site/jacoco-it/jacoco.xml，多模块项目就必须注意每个模块自己的目标目录，不能一股脑指向根目录。
下面这个配置片段是集成测试报告生成后、进入 SonarQube 扫描前，Jenkins 里通常要做的事情：
# 进入被测服务的代码目录执行扫描 mvn sonar:sonar \ -Dsonar.host.url=http://sonarqube.example.com \ -Dsonar.projectKey=payment-service \ -Dsonar.projectName=payment-service \ -Dsonar.coverage.jacoco.xmlReportPaths=target/site/jacoco-it/jacoco.xml,target/site/jacoco/jacoco.xml这里写两个 XML 路径是有意为之：前者是集成测试覆盖率，后者是单元测试覆盖率。SonarQube 的展示规则比较特殊，它会把多个来源的 XML 报告做“行覆盖合并”，同一个类里单元测试覆盖到的行和集成测试覆盖到的行会叠加，而不是互相覆盖。理解了这一点，你就能解释为什么 SonarQube 上的总覆盖率会高于单一报告的覆盖率——这是正常的，两个阶段的执行路径拼起来才构成完整画像。
2.3 单节点部署场景的启动参数与数据回传
单节点集成测试还有一种常见形态：被测服务不是由 Maven 启动，而是通过 Docker 或者运维脚本独立启动的。这种情况下你不能依赖prepare-agent插件，得手动在服务启动命令里加上探针参数。注意观察整条参数的结构：
-javaagent:/opt/agent/org.jacoco.agent-0.8.12-runtime.jar=destfile=/data/jacoco-it.exec,append=true,includes=com.example.*三个关键的附加选项我逐个解释。includes限定要插桩的类，通常在大型项目里非常有用——如果不对类路径做限制，探针会尝试处理所有加载的类，包括第三方框架的内部类，产生的 exec 巨大且合并耗时。append=true保证同一台机器上多次重启服务时数据不丢。destfile必须写绝对路径，尤其是用 systemd 或容器启动时，相对路径解析到你根本想不到的位置，这是经典坑。
数据回传这一步，单节点最简单的方式是让 Jenkins 的构建机直接从被测节点拉取 exec 文件：
scp test-01:/data/jacoco-it.exec ./target/jacoco-it.exec mvn sonar:sonar -Dsonar.coverage.jacoco.xmlReportPaths=./target/site/jacoco-it/jacoco.xmlssh 打通之后，这条链路非常稳定。等 exec 拉回来后，你还要在本地生成 XML 报告，此时可以复用第 1 篇里已经配好的 jacoco 插件，在post-integration-test阶段手动调用：
mvn org.jacoco:jacoco-maven-plugin:0.8.12:report-integration \ -Djacoco.destFile=./target/jacoco-it.exec注意这里的jacoco.destFile参数名是插件约定的，指向你拉回来的 exec 文件。这一步跑完，本地target/site/jacoco-it/jacoco.xml就生成了，SonarQube 扫描直接用。
3. 集群集成测试的真正难点：exec 文件大会师
集群环境下的集成测试覆盖率，核心就一件事：把散落在每个节点上的 exec 文件收回来，合并成一个，再生成报告。这件事听上去简单，做起来却有不少隐藏前提，先讲清楚为什么不能直接各节点分别生成 XML 然后交给 SonarQube。
3.1 为什么不能把多份 XML 直接丢给 SonarQube
理论上 SonarQube 支持配置多个 XML 报告路径，所以有同事会想，那我每台节点分别生成 jacoco.xml，然后sonar.coverage.jacoco.xmlReportPaths=node1/jacoco.xml,node2/jacoco.xml不就行了？实际跑下来经常出两类问题。
第一类问题是类和行的归属。同一个类在 node1 的 XML 里覆盖了第 20 行，在 node2 的 XML 里覆盖了第 20 行和第 30 行，SonarQube 是否知道这是同一个类？如果两个 node 部署的 jar/war 包版本一致，类名和行号一致，大概率能合并；但如果版本不一致，类结构发生过变化，行号错位，SonarQube 就会把两个“不同版本”的同一个类当成两个对象处理，结果要么重复统计要么覆盖率为 0。第二类问题是性能，集群规模一上来，几十份 XML 逐份解析的耗时和内存开销明显增加，扫描日志会变得非常难看，排查问题时也搞不清数据从哪来的。
3.2 推荐的汇聚方式：先合并 exec，再生成一份 XML
所以集群模式的正确顺序是：每个节点只负责产生 exec 二进制文件，集中到一个地方先 merge，merge 完再生成 XML，最后交给 SonarQube 扫描。
JaCoCo 官方提供了 merge 工具。推荐做法是准备一台数据汇聚机，把所有 exec 文件放到同一个目录下，然后执行：
java -jar /opt/jacoco/org.jacoco.cli-0.8.12-nodeps.jar merge \ exec/*.exec \ --destfile /data/merged-it.execmerge 命令的原理是逐条读入每个 exec 里的类执行记录，同一个类 ID 的指令执行次数做累加。这里有个概念必须先搞清楚：JaCoCo 在执行数据里记录的并不是类名，而是类 ID，也就是对类字节码结构做哈希后得到的一个数值。只有两个节点的被测类字节码完全一致，类 ID 才会相同，merge 才能把数据正确叠加；如果字节码有差异，即使类名相同，在 JaCoCo 眼里也是两个不同的类，最终报表里会出现同一个类出现两次、覆盖数据互不相关。
这就引出了集群集成测试覆盖率的第一条铁律：参与测试的所有节点，必须部署由同一个构建产物生成的包。如果某个节点是手动部署的、用了上一版本的 jar，或者构建环境里引入了时间和路径相关的元数据导致字节码不一致，merge 出来的数据基本上就是错的，而且表面上看不出来。
3.3 三种 exec 汇聚方案的对比与取舍
除了“集中 merge”，集群场景还有两种常见的汇聚思路：共享存储直写和远程端口 dump。把三者的区别列出来，方便你根据实际条件选型。
| 方案 | 原理 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|---|
| 共享存储直写 | 每节点 agent 的 destfile 直接指向 NFS/分布式文件系统，exec 天然汇集 | 配置简单，实时收数 | 多节点同时 start/append 时并发写文件，存在竞争风险 | 节点数少、并发可控的中小型集群 |
| 集中 merge | 每节点 exec 写本地，测试结束后统一拉取再 merge | 数据隔离好、合并逻辑可控 | 多一个拉取和 merge 的步骤 | 节点多、测试分批执行、对准确性要求高的场景 |
| 远程端口 dump | agent 开放address和port，由汇聚端远程抓取 dump | 不需要共享目录 | 每个节点都要暴露端口，配置繁琐且服务生命周期管理变复杂 | 极少用于标准集成测试，更多是故障现场的临时诊断 |
我个人的倾向非常明确：常规集成测试一律用“集中 merge”，也就是第二行这个方案。共享存储直写我在一个 5 节点的环境里踩过坑，问题在于 JaCoCo agent 的append=true只是打开文件后追加写，两个节点同时写同一份 destfile 时，文件锁机制管理不好，数据错乱的情况会出现，而且这种错乱非常隐蔽，报表看起来正常但数据总量不对。集中 merge 虽然多一步，但每个节点的 exec 都是独立完整的，合并的可控性最好。
4. 集群集成测试的完整落地：从收集到聚合的 Pipeline 设计
方案定了之后，剩下的就是把它落进 Jenkins Pipeline。这个环节我建议直接写一个独立的 stage，不要混在测试 job 里顺手处理，因为 exec 收集失败和测试失败的失败原因、重试策略都不一样，拆开更便于排错。
4.1 Pipeline 里的收集阶段怎么设计
一个标准的两段式设计是这样的：先有一个测试执行 job，在测试结束后把各个节点的 exec 归档到 Jenkins 的 workspace 里；再有一个覆盖率聚合 job，负责 merge、报告和 SonarQube 扫描。当然也可以合在一个 Pipeline 里，但至少 stage 要分开。
下面是一个 Pipeline 的简化版，可以看到我在收集节点数据时用到了archiveArtifacts，而不只是拉回当前机器的目录，这样即使测试 job 跑挂了，exec 文件也已经归档，后续还能手动补跑。
pipeline { agent any stages { stage('Run Integration Tests') { steps { // 触发集成测试，这里可以是脚本或另一个 job build job: 'integration-test-runner', wait: true } post { success { archiveArtifacts artifacts: 'exec/**/*.exec', allowEmptyArchive: false } } } stage('Merge JaCoCo Exec') { steps { sh ''' mkdir -p merged java -jar /opt/jacoco/org.jacoco.cli-0.8.12-nodeps.jar merge \ exec/**/*.exec \ --destfile merged/aggregated-it.exec ''' } } stage('Generate XML Report') { steps { sh ''' mvn org.jacoco:jacoco-maven-plugin:0.8.12:report-integration \ -Djacoco.destFile=merged/aggregated-it.exec \ -Djacoco.outputDirectory=merged/report ls -la merged/report ''' } } stage('SonarQube Analysis') { steps { sh ''' mvn sonar:sonar \ -Dsonar.host.url=http://sonarqube.example.com \ -Dsonar.projectKey=payment-service \ -Dsonar.coverage.jacoco.xmlReportPaths=merged/report/jacoco.xml ''' } } } }注意merge命令接收的是exec/**/*.exec，这个通配符由 JaCoCo CLI 自己处理，不是 shell 展开。有些 Launcher 环境里 shell 会把**展开成不同结果，保险起见建议先写全路径或者在脚本里用 find 收集文件列表，避免“明明文件在但 merge 结果为空”的情况。
4.2 构建一致性校验：避免 merge 出“两张皮”
为了保证 merge 有意义，我在 Pipeline 里加了一个看似多余的步骤：校验所有节点的 exec 文件本身没问题，并且各节点部署信息一致。具体做法是在测试执行 job 里让每个节点在跑完测试后输出一行部署元数据，比如构建号：
# 在被测节点上执行 echo "build_number=$(cat /data/deploy/build.info)" > node-${HOSTNAME}.info cat node-${HOSTNAME}.info汇聚 job 里再做一次简单比对，所有节点的 build_number 一致才继续 merge，否则直接 fail。这一步能拦住绝大多数因为混用版本造成的“假覆盖率”。有人会说这太麻烦了，我可以告诉你实际踩过的坑：有个环境曾经把 3 个节点的 exec 都合并得很漂亮，SonarQube 显示支付服务覆盖率从 31% 涨到了 86%，团队还庆祝了一波，后来代码审查时发现其中 1 个节点部署的是两周前的版本，类结构已经变了，覆盖率数据是错乱的，完全不能作为质量门禁依据。从那以后构建一致性校验就成为了固定环节。
4.3 多模块项目的聚合报告：单个模块报告与 aggregate 的区别
前面提到的report-integration目标默认只报告当前模块的代码。如果你的项目是多模块，比如支付服务拆成了payment-core、payment-api、payment-web，那么各模块 exec 里记录的类并不相同，需要分别生成报告再分别让 SonarQube 扫描。这种方式的问题是 SonarQube 的 project key 是单一的，扫描时只能指定一份 XML，多模块之间数据串联容易出错。
更省心的办法是用report-aggregate目标，它会在一个父模块下把各个子模块的 exec 数据汇总成一份报告。但这里有个隐藏依赖：report-aggregate只聚合“当前模块以及它依赖的子模块”，并且要求这些子模块是通过 Maven 依赖引入的。所以你要保证父模块的 pom 里声明了对所有需要聚合模块的依赖，或者用jacoco.destFile把所有 exec 先合并成一个再交给report-aggregate。我实际用下来，顺序是：先全局 merge 成一个 aggregated-it.exec，再在父模块执行report-aggregate，最后给 SonarQube 指到聚合出的 XML 上，逻辑最简单。
5. 踩坑实录：四类高频故障的完整排查链路
配置是一回事，真正跑起来以后出的问题才是重点。下面四个问题是我在这个系列落地过程中遇到最多次、也最典型的，每个都按“现象 → 排查 → 根因 → 解决”的链路写出来，你照着排查基本能少走两天弯路。
问题一：集成测试跑完后，SonarQube 覆盖率只有单元测试的数值，完全没有集成测试的部分。
最可能的根因是 XML 报告路径没有指向集成测试的报告目录。直接在 SonarQube 的 Scanner 日志里搜索coverage.jacoco.xmlReportPaths，可以看到扫描器实际读取的路径是什么。如果只有target/site/jacoco/jacoco.xml，说明集成测试的 XML 根本没进扫描参数。排查时先确认merged/report/jacoco.xml是否存在，再确认sonar.coverage.jacoco.xmlReportPaths里有没有拼写错误。另外注意 SonarQube 8.x 和 9.x 的参数名不一样，8 及以下用sonar.jacoco.reportPath（针对 exec），9 及以上用sonar.coverage.jacoco.xmlReportPaths（针对 XML）。两代参数混用也是常见的隐蔽问题。
问题二：覆盖率显示出来了，但数值极低，远低于集成测试应该达到的水平。
这个现象大概率是 exec 文件只收集到了部分节点。我在一次 6 节点的集群上看到覆盖率只有 30%，排查发现 load balancer 把 70% 的流量都转发到了 4 号节点，其他节点几乎没有执行到被测类。根因不是配置，而是测试流量分发不均衡。解决方式是在测试设计上做流量固定：要么用特定的测试入口绕开负载均衡直接打到每个节点，要么给每台节点设计独立的测试场景，保证每个被测实例都跑到了足够的请求。
另一个可能根因是includes参数过滤掉了大部分类。有人图省事写includes=com.example.*，但实际被测类在com.example.internal.*下，探针没进去，覆盖率自然低。排查时看 exec 文件大小，如果明显小于预期，八成是 includes 配置过窄。
问题三：merge 之后生成了报告，但 SonarQube 上同一个类出现了多次或覆盖率数据互相矛盾。
直接看报告目录里的 HTML 输出，搜同名类，如果出现两次，基本可以断定类 ID 不一致。解释这个现象要回到 merge 的原理：类 ID 是所有方法来签名、字段签名、常量池结构的综合哈希，只要类文件的字节码有任何不同，包括编译时 JDK 版本、Debug 信息开关、甚至编译器版本差异，类 ID 都会变。所以排查方向有两个：一是确认所有节点的部署包是不是同一个构建任务的产物；二是确认被测服务和依赖库的构建是否在干净环境里进行，如果构建时引入了本地路径，会导致同样的代码编译出不同的字节码。解决方式是把 Maven 构建的.m2缓存清干净、固定 JDK 版本，而且要保证部署包和测试包来自同一次构建，不要测试时重新编译。
问题四：多模块项目下，集成测试的覆盖率项目归属错乱。
表现是覆盖率数据出现在一个不相关模块下，或者 SonarQube 上项目总览的覆盖率没问题，但点进某个类后发现覆盖行根本不是被测代码。这个问题的根源通常在于扫描器对模块路径的识别。SonarQube 的sonar.sources和sonar.java.binaries必须明确指向编译后的 class 目录。多模块项目如果你只配置了根目录，扫描器会遍历到所有模块，但 exec 数据只覆盖了部分模块的类，两者不对齐就会产生错乱。排查时用 SonarQube 的 coverage 详情页查看每个类对应的 source 路径，确认 exec 里记录的类和你配置的sonar.sources是否在同一相对路径下。如果模块使用了自定义 source 布局，还要额外配置sonar.sources为具体模块名。
五、不一定写在文档里的个人体会
这套方案跑稳定之后，我有几个体会想留给你。
第一个体会是exec 文件的命名规范和收集策略要尽早定死，不要等到集群规模大了再改。我现在的规范是每台节点固定写/data/jacoco-it-${HOSTNAME}.exec，每轮测试结束后 Jenkins 按节点名拉取归档，这样哪台节点的数据缺失，看归档目录一目了然。以前用jacoco-it.exec这种通用名，节点一多就分不清谁是谁，排查问题时只能逐个 ssh 上去看。
第二个体会是覆盖率的增长要结合测试场景设计来看，不要只看总数值。集成测试覆盖率和单元测试不同，它高度依赖流量入口。如果你把大量场景都只打到一个节点上，报告上的总覆盖率即使过了 80%，也没有代表性，因为其他节点对应的部署环境依然没有被验证。质量门禁如果要卡这个指标，建议按“每节点最少覆盖率”来设，而不是只看聚合值。
第三个体会是合并 exec 的动作是幂等且无序的，但做这件事的 Pipeline 顺序必须串行。如果你的监控中心有多个 job 同时把 exec 拷贝到汇聚目录，尽量在文件级别做锁，或者把 concat 目录按 job 名建子目录，避免两个 job 同时 merge 同一批文件导致数据被清空。这个问题我在共享存储方案里遇到过，集中 merge 后基本没有再出现。
第四个体会是小技巧：merge 前可以先对 exec 做一次瘦身。集成测试跑完，每个 exec 里可能包含了大量无入库、无业务价值的框架类，这时用 merge 命令的--includes参数先过滤一遍，只保留你关心的业务包，生成的报告不仅更干净，扫描时间也会明显缩短。
集成测试覆盖率这件事，技术上并不复杂，复杂度主要来自数据生命周期管理。单元测试是“一个进程一份数据”，集成测试是“多进程多节点多份数据”，只要把 exec 的收集、合并、报告生成这三个环节拆清楚，集群再多也只是规模问题，不是方案问题。这一篇到这里，配合前两篇的内容，从单元测试到集成测试的覆盖率闭环应该已经完整了。如果后面你在多模块聚合或 SonarQube 质量门禁上遇到具体报错，欢迎带着现象和日志继续交流。
