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.version0.8.12/jacoco.version /properties build pluginManagement plugins plugin groupIdorg.jacoco/groupId artifactIdjacoco-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 groupIdorg.apache.maven.plugins/groupId artifactIdmaven-surefire-plugin/artifactId version3.2.5/version configuration argLine{argLine}/argLine !-- 集成测试走 failsafe不能混进 surefire -- excludes exclude**/*IT.java/exclude /excludes /configuration /plugin plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-failsafe-plugin/artifactId version3.2.5/version executions execution goals goalintegration-test/goal goalverify/goal /goals /execution /executions configuration argLine{argLine}/argLine includes include**/*IT.java/include /includes /configuration /plugin plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId executions !-- 探针准备绑定到 verify 阶段之前初始化 agent 参数 -- execution idprepare-agent/id goals goalprepare-agent/goal /goals configuration destFile${project.build.directory}/jacoco.exec/destFile propertyNamesurefire.argLine/propertyName /configuration /execution !-- 为集成测试生成独立的探针 -- execution idprepare-agent-integration/id goals goalprepare-agent/goal /goals configuration destFile${project.build.directory}/jacoco-it.exec/destFile propertyNamefailsafe.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目录下要生成一份全项目的覆盖率总览需要一个聚合的地方。通常有三种做法单独建一个aggregate模块依赖所有业务模块只聚合不做业务。使用父 POM 作为一个聚合入口在父 POM 里声明 JaCoCo 聚合报告。直接在 CI 里用脚本调用jacoco:merge和jacoco:report。我个人推荐第一种——单独建聚合模块原因在于它职责单一、不污染其它模块的构建并且后续如果某个模块不想被统计直接从这个聚合模块里剔除依赖就行。缺点是多一个工程目录但这个代价在覆盖率统计的清晰度面前我认为完全可以接受。聚合模块的构建配置关键点是把各模块的定向依赖关系和 JaCoCo 的报告生成目标绑定好。下面是一份核心配置dependencies dependency groupIdcom.example/groupId artifactIdweb/artifactId version${project.version}/version /dependency dependency groupIdcom.example/groupId artifactIdservice/artifactId version${project.version}/version /dependency dependency groupIdcom.example/groupId artifactIddal/artifactId version${project.version}/version /dependency dependency groupIdcom.example/groupId artifactIdcommon/artifactId version${project.version}/version /dependency /dependencies build plugins plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId executions execution idreport-aggregate/id phaseverify/phase goals goalreport-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 includecom/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→testSurefire跑单测 →integration-testFailsafe跑集成测试 →verify。JaCoCo 的prepare-agent目标通常绑定在initialize阶段可以保证探针参数在测试运行之前就准备好了。你要特别注意的是集成测试的触发时机。Failsafe 的integration-test目标绑定在生命周期中的integration-test阶段单元测试跑完之后才轮到它。如果你在 CI 里只执行了mvn test集成测试不会运行jacoco-it.exec也根本不会生成。所以不管是在本地还是在 CI 上跑全量测试并且生成覆盖率报告建议统一执行下面这条命令mvn clean verifyclean保证没有上一个构建周期的残留数据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 idmerge-results/id phaseverify/phase goals goalmerge/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 idcoverage-check/id phaseverify/phase goals goalcheck/goal /goals configuration dataFile${project.build.directory}/jacoco-all.exec/dataFile rules rule elementBUNDLE/element limits limit counterINSTRUCTION/counter valueCOVEREDRATIO/value minimum0.80/minimum /limit limit counterLINE/counter valueCOVEREDRATIO/value minimum0.70/minimum /limit limit counterBRANCH/counter valueCOVEREDRATIO/value minimum0.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 自动生成的代码标注为GeneratedJaCoCo 会默认排除带该注解的代码。这个配置一般放在父 POM 的属性里properties lombok.addLombokGeneratedAnnotationtrue/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.javaFailsafe 根本不会识别到它更不会为它启动探针。你自己以为跑了集成测试实际上它要么被 Surefire 当单元测试吞了要么压根没跑。方案很简单规范命名所有集成测试统一使用*IT.java后缀。问题三聚合报告里只有一部分模块的数据。这个场景很常见尤其是你给模块配了不同的 JaCoCo 执行计划的时候。排查的关键是先看聚合报告里缺了哪一个模块的类。report-aggregate会把所有直接依赖和间接依赖的模块都扫进来但如果你想看到某个模块的报告必须确认这个模块在聚合模块的dependencies里。如果你用的是父 POM 聚合所有模块那么把某些模块标记为optionaltrue/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 的配置思路做迁移会比较顺手因为核心原理没变分路采集、集中合并、统一报告。希望这篇实践总结对你有所启发也欢迎在实际配置中继续摸索出更适合你自己项目节奏的方案。