Gradle多模块项目Jacoco代码覆盖率报告生成指南

1. 问题背景与错误分析

在Gradle多模块项目中集成Jacoco以生成代码覆盖率报告时，开发者常常会遇到一个棘手的错误信息：“The value for this file collection is final and cannot be changed”。这个错误通常发生在尝试在任务的执行阶段（例如通过doFirst或doLast块）动态修改executionData、classDirectories或sourceDirectories等FileCollection类型的属性时。

Jacoco报告任务（JacocoReport类型）的这些属性，如executionData（Jacoco执行数据文件，通常是.exec文件）、classDirectories（待分析的编译后的类文件目录）和sourceDirectories（用于报告中源码链接的源代码目录），需要在Gradle的配置阶段进行设置。Gradle在配置阶段构建任务图，并在此阶段确定所有任务的输入和输出。一旦进入执行阶段，这些FileCollection属性的值就被视为最终确定，不允许再进行修改。

原始的错误示例中，尝试在doFirst块内使用executionData.setFrom(...)来设置执行数据，这正是导致此错误的原因。doFirst是任务执行生命周期的一部分，此时Gradle已经完成了配置，因此会抛出“final and cannot be changed”的错误。

2. 正确配置Jacoco多模块聚合报告

为了在Gradle多模块项目中正确生成聚合的Jacoco代码覆盖率报告，我们需要在根项目的build.gradle文件中定义一个聚合报告任务，并在配置阶段收集所有子模块的相关信息。

2.1 根项目 build.gradle 配置

在根项目的build.gradle文件中，首先确保应用了Java插件（如果根项目本身包含代码），然后为所有子项目应用Jacoco插件。

AI-Text-Classifier

OpenAI官方出品，可以区分人工智能书写的文本和人类书写的文本

59

查看详情

// root/build.gradle

plugins {
    id 'java' // 如果根项目也有Java代码，或者需要使用Java相关的任务
}

// 定义Jacoco工具版本，并应用于所有子项目
allprojects {
    apply plugin: 'jacoco'
    jacoco {
        toolVersion = "0.8.8" // 推荐使用最新稳定版本
    }
}

// 为所有子项目配置JacocoTestReport任务 (可选，用于生成独立的子模块报告)
subprojects {
    // 确保在生成报告前运行测试
    tasks.named('jacocoTestReport', JacocoReport) {
        dependsOn tasks.named('test')
        reports {
            html.enabled = true
            xml.enabled = true
            csv.enabled = false
        }
    }
}

// 定义一个聚合所有子模块覆盖率的Jacoco报告任务
task jacocoTotalReport(type: JacocoReport) {
    description = "Generates a combined Jacoco coverage report for all subprojects."

    // 确保所有子项目的 'test' 任务在生成聚合报告前运行
    // 这样才能生成 .exec 文件
    dependsOn subprojects.tasks.matching { it.name == 'test' }

    // 配置执行数据（.exec文件）
    // 收集所有子项目 build/jacoco 目录下的 test.exec 文件
    // 注意：这里的配置是在Gradle的配置阶段完成的
    executionData.setFrom(files(subprojects.collect { project ->
        file("${project.buildDir}/jacoco/test.exec")
    }).filter { it.exists() }) // 过滤掉不存在的文件，避免报错

    // 配置类文件目录
    // 收集所有子项目的 main sourceSet 编译后的类文件目录
    classDirectories.setFrom(files(subprojects.collect { project ->
        project.sourceSets.main.output.classesDirs
    }))

    // 配置源代码目录
    // 收集所有子项目的 main sourceSet 的所有源代码文件，用于报告中的源代码链接
    sourceDirectories.setFrom(files(subprojects.collect { project ->
        project.sourceSets.main.allSource
    }))

    // 配置报告输出格式和位置
    reports {
        html.enabled = true
        xml.enabled = true
        csv.enabled = false // 通常聚合报告不需要CSV格式
        html.destination file("${buildDir}/reports/jacoco/total/html")
        xml.destination file("${buildDir}/reports/jacoco/total/jacocoTotalReport.xml")
    }
}

2.2 settings.gradle 配置

确保您的settings.gradle文件正确包含了所有子模块：

// root/settings.gradle
rootProject.name = 'my-multi-module-project'
include 'module-a', 'module-b', 'module-c' // 根据您的实际模块名称进行添加

3. 代码说明与注意事项

1. allprojects 块: 在allprojects块中应用jacoco插件并设置toolVersion，确保所有子项目都能使用Jacoco。
2. subprojects 块 (可选): 在subprojects块中配置jacocoTestReport任务是可选的。如果需要为每个子模块生成独立的覆盖率报告，则可以保留此配置。dependsOn tasks.named('test')确保在生成报告前先运行了测试。
3. jacocoTotalReport 任务:
   • 类型: 必须是JacocoReport类型。
   • dependsOn: dependsOn subprojects.tasks.matching { it.name == 'test' } 是至关重要的一步。它确保在jacocoTotalReport任务执行之前，所有子模块的test任务都已运行，从而生成必要的.exec执行数据文件。
   • executionData.setFrom(...): 这是解决“final and cannot be changed”错误的关键。我们通过subprojects.collect在配置阶段迭代所有子项目，收集每个子项目生成的test.exec文件路径。filter { it.exists() }可以避免在某些子项目没有生成.exec文件时导致报告失败。
   • classDirectories.setFrom(...): 同样在配置阶段收集所有子模块的编译类文件目录。这些是Jacoco分析字节码的基础。
   • sourceDirectories.setFrom(...): 收集所有子模块的源代码目录。这使得Jacoco报告能够将覆盖率数据与源代码行进行关联，并在HTML报告中提供源码视图。
   • 报告输出: 配置reports块来指定生成HTML和XML格式的报告，并定义它们的输出路径。html.destination和xml.destination将报告统一输出到根项目的build/reports/jacoco/total目录下。
4. 执行命令: 要生成聚合报告，您只需在根项目目录下运行Gradle命令：

   ./gradlew jacocoTotalReport

   登录后复制

   这将首先执行所有子模块的测试，然后生成一个包含所有模块代码覆盖率数据的统一报告。

4. 总结

通过上述配置，我们成功地规避了“The value for this file collection is final and cannot be changed”的错误。核心思想是在Gradle的配置阶段，而非执行阶段，完成JacocoReport任务executionData、classDirectories和sourceDirectories等属性的设置。这种方法确保了Gradle能够正确地构建任务图，并在执行时拥有所有必需的输入，从而为多模块Java项目生成准确、完整的Jacoco代码覆盖率聚合报告。遵循这种专业的配置方式，将大大提升项目代码质量管理的效率和准确性。

以上就是Gradle多模块项目Jacoco代码覆盖率报告生成指南的详细内容，更多请关注php中文网其它相关文章！