企业官网建设流程全解析

1. 多模块项目的覆盖率困局与整体思路

1.1 为什么多模块项目会让JaCoCo统计变得如此拧巴

先抛一个很多人在实际开发中都会遇到的场景：你手头维护着一个标准的Maven多模块Spring Boot项目，结构大概是这样的——父工程下面挂着几个业务模块，比如web、service、dal，另外还有一个common公共模块。每个模块都有对应的单元测试，随着业务深入，也开始补集成测试。一切看起来都很正常，直到某天你打开了CI流水线上的覆盖率报表，才发现问题一大堆。

每个模块各自跑出来的覆盖率数字看起来都不错，但你想看整个项目的整体覆盖率，却根本找不到一份汇总报告。更麻烦的是，你辛辛苦苦写了几个真正有价值的大集成测试——比如从Controller一直打到数据库那种，在报表里却一点影子都看不到。你翻了一圈JaCoCo的文档，直觉告诉你它肯定支持多模块合并，但配置起来就是各种不生效。说实话，我第一次折腾这个配置的时候也踩了不少坑，网上的资料要么只讲单模块，要么只讲Maven插件的某一个配置项，很难找到一条完整的链路把它串起来。

这个问题之所以普遍，根源在于JaCoCo本身的工作机制。JaCoCo通过Java Agent在JVM加载类的时候动态注入探针，以此记录每行代码有没有被真实执行到，然后生成一个.exec格式的数据文件。注意，.exec文件是按“JVM实例”来记录的，一个测试进程跑完，产出一个独立的.exec文件。多模块项目里，每个模块的测试都是各自独立的Maven生命周期，最终会在Maven仓库或者各模块的target目录下，留下分散在各处的覆盖率数据文件。这些文件之间没有关联，如果不能把它们合并成一份完整的数据，那覆盖率报告自然就是一张碎片化拼图。

1.2 集成测试与单元测试：覆盖率统计里最容易被混淆的两个维度

在多模块项目的覆盖率统计里，还存在一个非常隐蔽的误区——很多人把单元测试和集成测试的覆盖率混为一谈。等你真正动手配了JaCoCo，就会发现这两者其实是完全独立的两条数据链路。

单元测试通常由Maven的maven-surefire-plugin驱动，对应的是src/test/java目录下的测试类，测试过程中会启动自主的Spring Boot上下文进行测试。集成测试则不同，它通常由maven-failsafe-plugin驱动，测试类放在src/integration-test/java目录下，文件命名一般是*IT.java，固定以IT结尾。集成测试往往会启动完整的Spring Boot应用——真正的内嵌Tomcat、真实的数据源、可能还连了测试库，跑完整个业务链路。

这两者的关键区别在于：它们的exec数据文件是分别生成的，而且Failsafe插件的执行阶段在Surefire之后。如果你只在父POM里配了一套JaCoCo配置，那通常只覆盖到了单元测试的数据，集成测试的数据根本没有被收集。更隐蔽的问题是，有时候你以为自己在跑集成测试，实际上因为命名不规范，测试类被Surefire插件给"误吞"了，或者反过来——用了*Test.java这样太宽泛的命名，导致Failsafe插件一个测试都没匹配上，白白跑了个寂寞。

这篇文章就是要把这条链路理清楚。你可以把整个配置方案理解成三个动作的组合：各模块分散收集、全量数据合并、聚合报告生成。三个动作各管一段，配上正确的插件声明和阶段绑定，就能让多模块项目的单元测试+集成测试覆盖率数据像拼图一样严丝合缝地拼到一起。

2. JaCoCo的核心工作机制：从探针到数据文件再到报告的完整链路

2.1 on-the-fly模式：默认方案为什么值得信任

JaCoCo的Java Agent在JVM启动时，会通过ClassFileTransformer对加载进内存的Class文件做插桩。说得直白一点，Agent会在你写好的源码字节码里"埋线"，每一条指令相当于装了一个计数器。当某行代码被真实执行到，计数器就加一；JVM关闭时，Agent把计数器里的数据写入.exec文件。这个模式叫on-the-fly，也是JaCoCo官方默认推荐的方式。

为什么官方推荐on-the-fly而不是offline？因为on-the-fly不需要预先修改类文件，Agent随时挂载、随时移除，不影响构建产物的纯净性。offline模式则不同，它要求你在编译阶段就对Class文件做一次物理插桩，命令会变成java -javaagent:jacocoagent.jar=...或者用jacoco:instrument目标预先处理。offline模式最大的优势是覆盖范围更广一些，能够覆盖到通过自定义类加载器加载的类，但缺点也很明显——需要和构建流程做额外集成，而且如果你在插桩后修改了Class文件，插桩就被破坏了。在实际的多模块Spring Boot项目里，除非遇到非常特殊的需求，否则我强烈建议你直接采用on-the-fly模式，让JaCoCo的官方Agent在JVM层面完成全部工作。这也是它在CI流水线里最可靠、最省心的一种方式。

Agent和扩展的架构需要再说得细一点。JVM在启动时会加载jacocoagent.jar，这个Agent内部有一个Agent类，它会注册一个Runtime实例并挂载到org.jacoco.agent.rt这个包下。插桩后的代码通过org.jacoco.agent.rt.internal_*包里的接口与Agent通信。每次类加载时，ClassFileTransformer就会把指令计数器注入类的每个方法。

2.2 exec文件与报告的关系：一个数据，三种表现

理解了Agent的插入原理之后，你需要对exec文件有一个明确的认知。exec文件是一个二进制文件，存储的是每条指令的执行次数和覆盖状态。它本身是"源数据"，不是人类可以直接阅读的报告。JaCoCo之后用report目标读取这些exec文件，结合源码和编译后的Class文件，生成三种形态的报告：HTML、XML和CSV。

• HTML报告适合人肉眼查看，浏览器里逐行标记绿、黄、红。
• XML报告是给CI系统或代码质量平台消费的，比如SonarQube，它通过读取XML来计算质量门禁。
• CSV报告适合在表格里做数据透视和趋势分析。

在多模块场景里，这个"数据源"与"报告"的关系值得强调一遍：一份报告必须对应一份合并后的完整数据源。模块各自的exec文件再完整，也只是整个故事的一部分，只有把它们合并成一个统一的data文件，报告才能展现出"全局视图"。这也是我接下来在配置环节要把merge目标和report-aggregate目标单独拎出来讲的原因。

2.3 数据合并的原理：为什么会丢数据，怎么才能不丢

合并多个.exec文件的核心动作是"去重累加计数"，对应JaCoCo的merge目标。你可以把这个过程理解成拼图：两个exec文件都记录了同一段类的执行情况，但执行次数可能不同，合并时简单的做法就是把次数加在一起；如果一个类只在A模块的exec文件里有，另一个文件里没有，那就把A模块的数据原样保留。重点是，JaCoCo的合并不是物理复制，而是逻辑上的"数据相加"，所以它在数学上能保证：只要每个文件的探针ID一致，合并结果就不会出问题。

但是这里隐藏着一个让很多人百思不得其解的问题：为什么我两个模块的exec文件合并后，报告里还是只有其中一个模块的数据？大部分情况下都是因为扫描路径不对。JaCoCo的report/report-aggregate目标在生成报告时，会根据classFiles和sourceFiles的位置去解析类。如果你的子模块Class文件路径写错了，或者用了相对路径，JaCoCo就找不到目标类，自然生不出对应模块的覆盖率。多模块场景下路径关系复杂，我就见过程序员辛辛苦苦在聚合模块里配好了一切，却因为Class路径指向了全空目录，报告上只有一个孤零零的模块。所以记住一句话：报告生成依赖的是编译产物，不是源码，Class文件在哪，JaCoCo才能在哪报告。

3. 多模块Spring Boot项目的JaCoCo配置实战

3.1 父POM的统一版本管理与插件声明

现在开始实际配置。一条合理的原则是：父POM只负责指定版本和管理插件的公共配置，真正的报告合并放到聚合模块里去完成。为什么？因为Maven的插件配置是会被子模块继承的，父POM如果你直接声明JaCoCo插件的执行，子模块都会跟着跑同一套逻辑，这在多模块里未必是好事——有些模块（比如纯工具类common）你可能希望它不参与覆盖率统计，配上父级继承你反而要去逐个排除。

我的做法是，在父POM的pluginManagement里声明好JaCoCo插件的版本和公共属性，但不在build/plugins里塞执行目标。具体配置如下：

<properties> <jacoco.version>0.8.12</jacoco.version> </properties> <build> <pluginManagement> <plugins> <plugin> <groupId>org.jacoco</groupId> <artifactId>jacoco-maven-plugin</artifactId> <version>${jacoco.version}</version> </plugin> </plugins> </pluginManagement> </build>

这里我选择0.8.12这个版本，是因为它兼容当前主流使用的 JDK 8 到 JDK 21 的字节码版本。如果你正在使用比较新的 JDK 17 或 21，低于0.8.7的版本在解析新字节码特性时经常会报出类似Unsupported class file major version的异常。这个版本的插件在 Spring Boot 3.2 和 Maven 3.6.3 以上的组合里我都实测过，能跑通。

3.2 业务模块的探针数据收集配置

父POM只做版本管理，具体的探针数据收集在每个业务模块里配置。核心思路是：为 Surefire（单元测试）和 Failsafe（集成测试）分别设置独立的 JaCoCo 探针任务，分别生成各自的 exec 数据文件，互不干扰。

以下是一份可以直接"抄作业"的模块级配置。我把这段配置放到需要统计覆盖率的各个业务模块的pom.xml里：

<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>3.2.5</version> <configuration> <argLine>@{argLine}</argLine> <!-- 集成测试走 failsafe，不能混进 surefire --> <excludes> <exclude>**/*IT.java</exclude> </excludes> </configuration> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-failsafe-plugin</artifactId> <version>3.2.5</version> <executions> <execution> <goals> <goal>integration-test</goal> <goal>verify</goal> </goals> </execution> </executions> <configuration> <argLine>@{argLine}</argLine> <includes> <include>**/*IT.java</include> </includes> </configuration> </plugin> <plugin> <groupId>org.jacoco</groupId> <artifactId>jacoco-maven-plugin</artifactId> <executions> <!-- 探针准备：绑定到 verify 阶段之前，初始化 agent 参数 --> <execution> <id>prepare-agent</id> <goals> <goal>prepare-agent</goal> </goals> <configuration> <destFile>${project.build.directory}/jacoco.exec</destFile> <propertyName>surefire.argLine</propertyName> </configuration> </execution> <!-- 为集成测试生成独立的探针 --> <execution> <id>prepare-agent-integration</id> <goals> <goal>prepare-agent</goal> </goals> <configuration> <destFile>${project.build.directory}/jacoco-it.exec</destFile> <propertyName>failsafe.argLine</propertyName> </configuration> </execution> </executions> </plugin> </plugins> </build>

这段配置里有两个细节我特意做了处理，很多人就是栽在它们手上。

细节一：argLine使用了@{argLine}占位符。这个语法是给 Maven Surefire/Failsafe 的late property replacement特性准备的，它会让插件延迟解析这个属性值，确保 JaCoCo 探针先完成属性写入、测试插件再读取属性。如果你用${argLine}硬编码，在某些版本组合下，属性解析顺序错乱会导致 agent 参数根本没有传给测试 JVM，覆盖率数据为零，且没有任何报错提示。你要是团队里多个成员在用不同版本的 Maven，更要重视这个细节。

细节二：prepare-agent-integration为集成测试单独生成了一个jacoco-it.exec文件。为什么要单独一个文件？因为单元测试和集成测试的进程是分开的，探针数据也必须分开采集。如果你把单元测试和集成测试的探针指向同一个destFile，不会真的产生错误，但第二次运行会直接覆盖第一次的数据，最后你得到的只有最后跑的那种测试的数据，另一个维度的覆盖率就丢了。这是多模块统计中最容易踩的坑，务必分开存放。

3.3 聚合模块与全量报告的生成

各模块的数据分散在各自的target目录下，要生成一份全项目的覆盖率总览，需要一个"聚合"的地方。通常有三种做法：

1. 单独建一个aggregate模块，依赖所有业务模块，只聚合不做业务。
2. 使用父 POM 作为一个聚合入口，在父 POM 里声明 JaCoCo 聚合报告。
3. 直接在 CI 里用脚本调用jacoco:merge和jacoco:report。

我个人推荐第一种——单独建聚合模块，原因在于它职责单一、不污染其它模块的构建，并且后续如果某个模块不想被统计，直接从这个聚合模块里剔除依赖就行。缺点是多一个工程目录，但这个代价在覆盖率统计的清晰度面前，我认为完全可以接受。

聚合模块的构建配置关键点是把各模块的定向依赖关系和 JaCoCo 的报告生成目标绑定好。下面是一份核心配置：

<dependencies> <dependency> <groupId>com.example</groupId> <artifactId>web</artifactId> <version>${project.version}</version> </dependency> <dependency> <groupId>com.example</groupId> <artifactId>service</artifactId> <version>${project.version}</version> </dependency> <dependency> <groupId>com.example</groupId> <artifactId>dal</artifactId> <version>${project.version}</version> </dependency> <dependency> <groupId>com.example</groupId> <artifactId>common</artifactId> <version>${project.version}</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.jacoco</groupId> <artifactId>jacoco-maven-plugin</artifactId> <executions> <execution> <id>report-aggregate</id> <phase>verify</phase> <goals> <goal>report-aggregate</goal> </goals> <configuration> <dataFileIncludes> <dataFileInclude>${project.build.directory}/jacoco.exec</dataFileInclude> <dataFileInclude>${project.build.directory}/jacoco-it.exec</dataFileInclude> </dataFileIncludes> <outputDirectory>${project.reporting.outputDirectory}/jacoco-aggregate</outputDirectory> <includes> <include>com/example/**</include> </includes> </configuration> </execution> </executions> </plugin> </plugins> </build>

这里有一个关键点：report-aggregate目标会自动把依赖树中所有模块编译后产生的 class 文件和 source 文件带进来，生成报告时会把各依赖模块的target/jacoco.exec和target/jacoco-it.exec数据源自动搜集进来。最贴心的一点是，JaCoCo 在报告的每个类标题栏里会标注该类的来源模块，站在全局视角看代码覆盖时非常清晰。

dataFileIncludes这里的配置是正确的做法：它明确指定了只收集每个模块的 default 和 it 两个数据文件。但是注意，聚合报告并不是靠这个配置直接去"找"数据文件的，它是把每个依赖模块的 target 目录下的数据文件做了一层"枚举扫描"。也就是说，你在这个配置里指定的路径，影响的是后续合并时数据文件的来源集合，而真正的作用机制是report-aggregate会自己递归分析。

3.4 用integration-test阶段串联完整流水线

在我的经验中，光是配好探针、聚合报告还不够，必须把整个执行顺序理清楚。Maven 生命周期中，测试的执行顺序大致是：test-compile→test（Surefire跑单测） →integration-test（Failsafe跑集成测试） →verify。JaCoCo 的prepare-agent目标通常绑定在initialize阶段，可以保证探针参数在测试运行之前就准备好了。

你要特别注意的是集成测试的触发时机。Failsafe 的integration-test目标绑定在生命周期中的integration-test阶段，单元测试跑完之后才轮到它。如果你在 CI 里只执行了mvn test，集成测试不会运行，jacoco-it.exec也根本不会生成。所以不管是在本地还是在 CI 上，跑全量测试并且生成覆盖率报告，建议统一执行下面这条命令：

mvn clean verify

clean保证没有上一个构建周期的残留数据，verify则会走完包括集成测试在内的全部测试阶段，并且触发聚合模块的report-aggregate目标。这是非常干净的一条全量管线。如果你执行的是mvn jacoco:report这种直接命令式执行，它只是让它执行单个目标的绑定，不会自动跑依赖的测试任务，对于多模块项目来说，这种黑盒行为往往会导致报告出来但数据是空的。

还有一个细节是 JDK 与 Maven 版本之间的搭配。我测试下来，JDK 17 + Maven 3.9.x 是目前多模块 Spring Boot 项目下 JaCoCo 兼容性最稳的组合。低于 Maven 3.6.3 的旧版本，late property replacement的支持不够完善，会遇到@{argLine}占位符失效，让整个测试链路跑不动。

4. 覆盖率数据的准确性保障与进阶配置

4.1 数据文件合并：必须合并，但不是无脑合并

聚合报告的生成已经帮我们把所有依赖模块的数据做了合并，但有一种更"裸"的场景你可能也会遇到：想直接操作多个 exec 文件、合并后生成自定义的报告，用于更细粒度的数据分析和门禁判断。这时候需要用 JaCoCo 的merge目标。

下面是一个可选的合并流程：

<execution> <id>merge-results</id> <phase>verify</phase> <goals> <goal>merge</goal> </goals> <configuration> <fileSets> <fileSet> <directory>${project.basedir}/target/jacoco-merged</directory> <includes> <include>**/*.exec</include> </includes> </fileSet> </fileSets> <destFile>${project.build.directory}/jacoco-all.exec</destFile> </configuration> </execution>

这里需要明确一个关键前提：merge只做数据文件的单纯合并，如果 exec 文件列表不一致或者格式不兼容，它不会给你任何明确的报错，只会把这个文件默默去掉。更严重的是，当你把单元测试的 exec 和集成测试的 exec 合并到同一个文件后，如果两份数据来自同一个类但不同测试进程，合并后计数器并不会做"更深层次的逐行运算"，它只是简单地做累加。所以如果 exec 文件之间不仅路径不同、连探针ID也开始有差异，就会出现覆盖率奇怪的“反向回落”——明明两个测试都跑了这个类，报告里的覆盖率却只有一半。

我的建议是：如果你不需要做细粒度的自定义报告，就直接用report-aggregate；如果真的需要合并数据源做二次开发，再引入merge。引入merge的时候留意一个细节：合并用的 exec 文件应当集中收集到一个目录，然后让 merge 从这个目录里遍历。如果你东放一个、西放一个，遍历顺序错乱，合并结果就可能不稳定。

4.2 覆盖率质量门禁：阈值的计算方法与配置陷阱

覆盖率统计出来不是为了贴在墙上看的，真正让团队纪律性提升的，是把覆盖率阈值作为硬性门禁写进构建流程。JaCoCo 通过check目标来校验覆盖率是否达标，不达标直接令 Maven 构建失败，是 CI 里一把好用的"质量锁"。

先给出我常用的配置模板：

<execution> <id>coverage-check</id> <phase>verify</phase> <goals> <goal>check</goal> </goals> <configuration> <dataFile>${project.build.directory}/jacoco-all.exec</dataFile> <rules> <rule> <element>BUNDLE</element> <limits> <limit> <counter>INSTRUCTION</counter> <value>COVEREDRATIO</value> <minimum>0.80</minimum> </limit> <limit> <counter>LINE</counter> <value>COVEREDRATIO</value> <minimum>0.70</minimum> </limit> <limit> <counter>BRANCH</counter> <value>COVEREDRATIO</value> <minimum>0.60</minimum> </limit> </limits> </rule> </rules> </configuration> </execution>

这段配置的意思是：以整体（BUNDLE）为单位，要求每个维度必须达到阈值——指令覆盖率 80%、行覆盖率 70%、分支覆盖率 60%。一旦任一指标不达标，整条mvn verify就会在check目标处失败，杜绝带病合入。

这里有几个值得展开说的点：

第一，element设置为BUNDLE这里需要注意，在多模块聚合场景下，如果你把这个规则放在聚合模块里，它的统计范围是整个聚合工程所有模块的合并结果。如果你希望每个模块各自门禁，那就在模块级配check。我的实践是，两级都配：模块级设置一个宽松的门禁（比如 60%），聚合模块设置严格的门禁（比如 80%），这样既能让新模块先跑起来，又能在整体质量上守住底线。

第二，COVEREDRATIO的计算方式是“被覆盖元素数 / 总元素数”。INSTRUCTION是字节码指令覆盖，LINE是行覆盖，BRANCH是分支覆盖。如果你的代码里有大量 Lombok 自动生成的 getter/setter，这些代码默认也是要参与覆盖率统计的，这会把覆盖率数字拉高不少。但如果你感到虚高，可以通过lombok.addLombokGeneratedAnnotation参数让 Lombok 自动生成的代码标注为@Generated，JaCoCo 会默认排除带该注解的代码。这个配置一般放在父 POM 的属性里：

<properties> <lombok.addLombokGeneratedAnnotation>true</lombok.addLombokGeneratedAnnotation> </properties>

这个参数在 Lombok 1.18.4 及以后版本中默认会被打开，但如果你用的版本较老，还是显式声明一下稳妥。

第三，check目标使用的数据文件要想清楚是用模块自己的 exec 还是合并后的全量 exec。如果希望聚合模块做门禁校验，那必须在聚合模块里把依赖模块的 exec 都合并好，再喂给check。所以合并目标的执行顺序通常要排在check之前，即merge→check→report-aggregate。

4.3 排除与包含：不统计的代码，要主动划清界限

覆盖率数字过高也不一定是好事，尤其是当你把一些本身就没有测试价值的代码也统计进去的时候，团队会把精力浪费在追逐毫无意义的数字上。我习惯在一开始就通过配置把几类代码“划出”统计范围：

• 启动类：比如*Application.java，它就是一行SpringApplication.run()，对测试没有直接价值。
• DTO/VO/领域模型：纯数据载体，一般由框架自动完成字段映射，不需要人为测试。
• 配置类：如@Configuration下的大段 Bean 定义。
• 生成的代码：如 MyBatis 生成的 Mapper 实现类、Swagger 自动生成的相关类。

这些类的排除可以放在 JaCoCo 的 report 相关配置里，通过excludes声明，例如：

<configuration> <excludes> <exclude>**/*Application.class</exclude> <exclude>**/dto/**/*.class</exclude> <exclude>**/config/**/*.class</exclude> <exclude>**/*Mapper.class</exclude> </excludes> </configuration>

注意排除的是.class文件路径，不是源码路径，路径分隔符用的是斜杠而非点号。很多第一次配的人会在这里栽跟头，写成了**/*Application.java，结果发现排除完全没有生效。这里的生效原则是：JaCoCo 报告生成时是通过 class 文件的路径来做匹配的，所以你要写 class 文件路径。

用系统化的眼光看，统计覆盖率的目的不是把数字做到好看，而是帮助团队知道哪些代码在复杂业务逻辑变动后没有得到回归验证。把不该算的排除掉，数字才会表达真实的风险。

5. 实操中的踩坑实录与排查速查

5.1 大量真实项目中我遇到过的典型问题

把配置框架搭好之后，真实世界里的工程问题远比配置本身丰富得多。我在不同的项目里来回折腾过很多次，有些问题极具代表性。

问题一：生成覆盖率数据的服务器上，报告全是0。

这个现象在本地跑的时候一切正常，一到 CI 流水线就归零。排查的起点，应该是检查 CI 用的是哪条 Maven 命令。如果 CI 执行的是mvn test，那报告目标根本没有被绑定到生命周期上，报告自然不存在。就算你强行指定了mvn test jacoco:report，由于 report 目标要求先有测试执行，而 mvn test 跑不了集成测试，集成测试的覆盖率也绝对是0。解决方法是把 CI 命令切到mvn clean verify，让生命周期完整跑完。

问题二：集成测试跑完了，jaCoCo-it.exec 文件存在，但聚合报告里没有集成测试的代码覆盖。

这个坑通常出在命名上。Failsafe 插件默认只会匹配以IT开头或结尾的测试类——标准是*IT.java、IT*.java、*ITCase.java这些模式。如果你的集成测试类命名为OrderServiceIntegrationTest.java，Failsafe 根本不会识别到它，更不会为它启动探针。你自己以为跑了集成测试，实际上它要么被 Surefire 当单元测试吞了，要么压根没跑。方案很简单：规范命名，所有集成测试统一使用*IT.java后缀。

问题三：聚合报告里只有一部分模块的数据。

这个场景很常见，尤其是你给模块配了不同的 JaCoCo 执行计划的时候。排查的关键是先看聚合报告里缺了哪一个模块的类。report-aggregate会把所有直接依赖和间接依赖的模块都扫进来，但如果你想看到某个模块的报告，必须确认这个模块在聚合模块的<dependencies>里。如果你用的是父 POM 聚合所有模块，那么把某些模块标记为<optional>true</optional>或从依赖中排除，它就会在你的聚合报告里消失。

问题四：@Generated 标记的代码被统计进去了。

Lombok 的@Generated注解在 JaCoCo 的过滤规则里默认是排除的，但如果你用了 MapStruct 来生成映射器，MapStruct 生成的实现类默认是不带@Generated的，所以它会参与覆盖率统计。这个现象不算 bug，但是会显著拉低实际项目覆盖率统计的"纯净度"。如果你不希望生成代码干扰数字，就需要在上节提到的excludes里手动加一行，把生成逻辑类的路径排除掉。

5.2 从实战中总结的四个避坑锦囊

除了上面这些具体问题，我还想总结几个总被低估的实战原则。这些建议不是什么教科书里的规范，而是我实际踩过坑之后领悟出来的经验。

第一，不要在生产代码目录里手动触发 JaCoCo 报告。JaCoCo 目标是 Maven 插件，它依赖测试生命周期产生的数据文件。你手动执行mvn jacoco:report只是把当前 target 目录下已有的 exec 文件制作为报告，如果上一次测试没有产生这些数据文件或者数据过期了，报告内容就是错误的。尽量不单独跑报告命令，让它挂在生命周期里自然触发。

第二，集成测试和单元测试的 destFile 一定要分开。这个问题我在前面提到多次，它造成的失败是静默的——你不会看到任何报错，只会发现报告数据少了一半。这两个文件分别由两套探针 config 控制，如果你省掉其中一个 config，那对应测试维度的覆盖率必定残缺。

第三，CI 的构建产物保留制度要设计好。JaCoCo 的 exec 文件和最终 HTML 报告都属于构建产物，CI 系统里要保留至少一个周期的报告，方便开发者回溯变更前后的覆盖率走势。我在实践里一般把报告同步到某个内部网页入口，并保留历史版本，这样每一个 MR 的覆盖率变化都有了可追溯性。

第四，本地开发环境与 CI 环境的数据隔离问题。本地跑测试产生的 exec 文件和 CI 上产生的 exec 文件，只要不在同一个 target 目录里，就不会有冲突，但如果你把 CI 的目标目录挂载到了共享存储，就要小心多个流水线并发写同一个目标路径。这时记得把 JaCoCo 的 destFile 集中到每个构建特有的工作目录下。

5.3 一个推荐的完整构建串联模板

最后，把整篇文章的所有配置拧成一股绳，给出一份多模块聚合场景下推荐的完整串联模板。假设你的工程里有一个聚合报告模块叫coverage，那你最终应该期望看到这样的流水线执行过程：

mvn clean verify -> 各模块单元测试运行时，jacoco agent 往 target/jacoco.exec 写数据 -> 各模块集成测试运行时，jacoco agent 往 target/jacoco-it.exec 写数据 -> coverage 模块中 merge 目标将所有 exec 合并为 target/jacoco-all.exec -> coverage 模块中 check 目标按规则校验整体覆盖率 -> coverage 模块中 report-aggregate 目标生成全局 HTML/XML/CSV 报告

这个顺序是经过实战检验的稳定链路。如果你在配置过程中发现某个阶段的报告位置不在你预期的地方，优先检查对应阶段的配置项：聚合模块里的 outputDirectory 用的是project.reporting.outputDirectory，那么报告默认在coverage/target/site/jacoco-aggregate下，而不是聚合模块根目录。

整个配置的关键点可以压缩成三句话：探针分两路，单测和集成测试单独产数据；聚合先合并，再校验，最后报告；Class 路径和测试命名是两条最容易出错的线，务必慢工出细活。

6. 写在最后的实操心得

作为一个在多个多模块主干项目里折腾过覆盖率统计的人，我再透露几个只有自己实测过才敢写的体会。

第一个体会是，不要在项目刚启动的时候就把阈值定得太高。覆盖率质量门禁是个需要逐步养成的机制，比如第一轮可以先定 60% 的指令覆盖率，团队习惯节奏之后再往上调。一上来就卡 80% 很容易引发逆反心理，大家为了达标开始堆大量无脑断言，反而破坏了测试的价值。

第二个体会是，覆盖率报告生成之后一定要被人看到。如果你只是让 CI 跑完生成一堆 HTML 放哪不管，那这个覆盖率系统的价值会大打折扣。至少要让每个 MR 的提交者知道，这次改动把项目的整体覆盖率从 76% 拉到了 74%，他会认真思考是否需要给自己的改动补几个测试。这个反馈机制，比任何制度都有效。

第三个体会是关于 execludes 和 includes 的具体边界。我在不同项目里见过两种极端：一种是啥都不过滤，启动类和 DTO 全部统计，覆盖率虚高到 90% 以上，团队自信心爆棚；另一种是过滤太狠，把核心业务逻辑都挡住了一半。我的判断标准很简单：凡是契约性和声明性的代码都不统计，凡是包含分支判断和业务规则逻辑的代码必须统计。严格按这个标准配一次 excludes，覆盖率数字才有指导价值。

最后一个体会可能有点反直觉——聚合报告的价值不在于数字本身，而在于你能够一眼看出哪些模块是短板。我之前在做技术分析和团队规划的时候，从聚合报告里直观地发现某个基础模块的覆盖率连 30% 都不到，而没有聚合报告之前，这个模块的孱弱是被其它模块的高覆盖率掩盖掉的。所以如果你想推动团队质量建设，先把这个聚合链路打通，让数据说话，比开会喊口号管用得多。

这套配置在 JDK 17、Spring Boot 3.x、Maven 3.9.x 的组合下稳定运行了很长时间，无论你是在本地开发还是 CI 流水线里执行，只要严格按照上面的顺序和细节来调配，它都能正确地输出你要的覆盖率报告。如果后续你引入了更复杂的构建场景，比如 Gradle 多模块、边缘接口测试、代码生成器等，再基于这份 Maven 的配置思路做迁移会比较顺手，因为核心原理没变：分路采集、集中合并、统一报告。希望这篇实践总结对你有所启发，也欢迎在实际配置中继续摸索出更适合你自己项目节奏的方案。