SpringBoot 代码覆盖率统计：JaCoCo 配置与使用

.caixukun

1044人浏览 · 2026-04-08 17:30:00

.caixukun · 2026-04-08 17:30:00 发布

在 SpringBoot 项目开发中，我们写了单元测试、集成测试，但怎么判断测试用例写得够不够？哪些代码没被测试覆盖到？哪些分支逻辑遗漏了测试？

这时候就需要「代码覆盖率统计工具」来帮我们把关——而 JaCoCo（Java Code Coverage）就是 SpringBoot 项目中最常用、最易用的覆盖率统计工具，无需复杂配置，就能快速统计出测试用例对代码的覆盖情况，帮我们补全测试漏洞，提升代码质量。

一、什么是代码覆盖率？JaCoCo 能做什么？

很多同学对代码覆盖率有误解，觉得「覆盖率越高越好」，其实不然——先理清核心概念，再用工具才不会走偏。

1.1 什么是代码覆盖率？

代码覆盖率是指「被测试用例执行到的代码行数 / 总代码行数」的百分比，是衡量测试用例完整性的重要指标。但要注意：覆盖率高不代表测试质量高（比如只走了简单分支，没测异常场景），但覆盖率低，一定说明测试用例有遗漏。

日常开发中，我们追求的不是 100% 覆盖率，而是「关键业务代码 100% 覆盖」，非核心代码（如工具类辅助方法）可适当放宽。

1.2 JaCoCo 的核心作用

JaCoCo 是一款开源的 Java 代码覆盖率统计工具，核心优势的是：无侵入式集成（无需修改业务代码）、配置简单（SpringBoot 项目可快速集成）、报告直观（支持 HTML 可视化报告，清晰看到未覆盖代码）。

它支持多种覆盖率统计维度（日常重点关注前 3 种）：

• 行覆盖率（Line Coverage）：被执行到的代码行数 / 总代码行数（最常用，直观反映覆盖情况）；
• 分支覆盖率（Branch Coverage）：被执行到的代码分支 / 总分支数（比如 if-else、switch 分支，重点关注）；
• 方法覆盖率（Method Coverage）：被执行到的方法 / 总方法数；
• 类覆盖率（Class Coverage）：被执行到的类 / 总类数；
• 指令覆盖率（Instruction Coverage）：被执行到的字节码指令 / 总指令数（底层维度，一般不用关注）。

简单说：JaCoCo 能帮我们精准定位「哪些代码没被测试到」，比如某个 if 分支、某个异常捕获逻辑，从而针对性补充测试用例。

二、SpringBoot 集成 JaCoCo

SpringBoot 项目集成 JaCoCo 非常简单，核心是添加依赖 + 配置 Maven/Gradle 插件，这里以最常用的 Maven 为例（Gradle 配置放在文末补充）。

2.1 核心依赖与插件配置（pom.xml）

JaCoCo 的集成不需要额外添加依赖（SpringBoot 测试依赖已包含 JaCoCo 相关组件），只需在 pom.xml 中配置 JaCoCo 插件，用于生成覆盖率报告。

<!-- 无需额外添加依赖，spring-boot-starter-test 已包含 JaCoCo 核心组件 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

<!-- JaCoCo 插件配置（核心，用于生成覆盖率报告） -->
<build>
    <plugins>
        <plugin>
            <groupId>org.jacoco</groupId>
            <artifactId>jacoco-maven-plugin</artifactId>
            <version>0.8.10</version> <!-- 版本可根据需求调整，兼容 SpringBoot 2.x/3.x -->
            <executions>
                <!-- 1. 准备 JaCoCo 运行环境，记录代码执行轨迹 -->
                <execution>
                    <id>prepare-agent</id>
                    <goals>
                        <goal>prepare-agent</goal>
                    </goals>
                </execution>
                <!-- 2. 执行测试用例后，生成覆盖率报告 -->
                <execution>
                    <id>report</id>
                    <phase>test</phase> <!-- 测试阶段执行，生成报告 -->
                    <goals>
                        <goal>report</goal>
                    </goals>
                    <!-- 可选：配置报告输出路径（默认在 target/site/jacoco 目录） -->
                    <configuration>
                       <outputDirectory>${project.build.directory}/jacoco-report</outputDirectory>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

注意点：

• JaCoCo 版本建议选择 0.8.5+，兼容 SpringBoot 2.x 和 3.x 版本，避免版本冲突；
• 默认报告输出路径是 target/site/jacoco，可通过 outputDirectory 自定义路径（如上面的 target/jacoco-report）；
• 插件的两个 execution 缺一不可：prepare-agent 负责记录代码执行轨迹，report 负责生成可视化报告。

2.2 Gradle 配置（适配 Gradle 项目）

如果你的项目是 Gradle 构建，在 build.gradle 中添加以下配置即可：

// 集成 JaCoCo 插件
plugins {
    id 'org.springframework.boot' version '2.7.10'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
    id 'java'
    id 'jacoco' // JaCoCo 插件
}

// 测试配置，执行测试时生成覆盖率数据
test {
    jacoco {
        enabled = true // 启用 JaCoCo
    }
}

// 生成 JaCoCo 覆盖率报告
jacocoTestReport {
    dependsOn test // 依赖 test 任务，先执行测试，再生成报告
    reports {
        html.enabled = true // 启用 HTML 报告（推荐，直观）
        xml.enabled = true // 启用 XML 报告（用于 CI/CD 集成，可选）
        csv.enabled = false // 禁用 CSV 报告（一般用不到）
        // 报告输出路径（默认在 build/reports/jacoco/test 目录）
        html.destination file("${buildDir}/jacoco-report/html")
    }
}

三、生成并解读 JaCoCo 覆盖率报告

配置完成后，只需执行测试用例，JaCoCo 就会自动记录代码执行情况，并生成可视化报告，步骤非常简单。

3.1 第一步：执行测试用例，生成覆盖率数据

有两种方式执行测试用例，触发 JaCoCo 记录覆盖率数据：

方式1：通过 Maven 命令执行

在项目根目录，打开终端，执行以下命令：

# 执行所有测试用例，并生成 JaCoCo 覆盖率报告
mvn clean test jacoco:report

命令解读：

• clean：清理之前的构建产物（避免旧报告干扰）；
• test：执行项目中所有的测试用例（单元测试、集成测试）；
• jacoco:report：根据测试执行轨迹，生成覆盖率报告。

方式2：通过 IDE 执行

在 IDE（IDEA/Eclipse）中，直接右键点击「test」目录，选择「Run Tests」，执行所有测试用例。

执行完成后，JaCoCo 会自动在 target/jacoco 目录下生成覆盖率数据文件（jacoco.exec），再执行 Maven 命令 mvn jacoco:report，即可生成 HTML 报告。

3.2 第二步：查看 JaCoCo 覆盖率报告

执行完成后，进入报告输出目录（默认 target/site/jacoco 或自定义的 target/jacoco-report），找到 index.html 文件，用浏览器打开，就是 JaCoCo 的可视化报告。

报告核心解读

打开报告后，界面分为 4 个核心区域，新手重点关注前 3 个：

（1）总览区域（最顶部）

显示项目的整体覆盖率情况，包括行覆盖率、分支覆盖率、方法覆盖率等，直观看到项目的测试覆盖整体水平。

示例：如果行覆盖率是 85%，说明有 15% 的代码没被测试用例执行到，需要补充测试。

（2）包/类列表区域（中间）

显示项目中所有包和类的覆盖率详情，点击包名可进入下一级，点击类名可查看该类的具体覆盖情况。

颜色说明（关键，一眼识别覆盖情况）：

• 绿色：完全覆盖（代码被测试用例执行到）；
• 黄色：部分覆盖（比如方法被执行，但分支未完全覆盖，如 if 执行了，else 没执行）；
• 红色：未覆盖（代码完全没被测试用例执行到）。

（3）类详情区域（点击类名进入）

这是最核心的区域，能精准看到该类中每一行代码的覆盖情况，红色标注的代码就是未被测试覆盖的部分，可直接定位到需要补充测试用例的地方。

示例：如果某个 if 语句的 else 分支是红色，说明测试用例只测了 if 条件成立的场景，没测 else 条件的场景，需要补充对应的测试用例。

3.3 补充未覆盖代码的测试用例

假设我们有一个 UserService 类，其中一个方法未被完全覆盖，通过 JaCoCo 报告定位后，补充测试用例，提升覆盖率。

步骤1：查看报告，定位未覆盖代码

打开 JaCoCo 报告，进入 UserService 类，发现以下方法有红色未覆盖代码：

// UserService 中的方法
public String getUserStatus(Integer age) {
    if (age < 18) {
        return "未成年"; // 已覆盖（绿色）
    } else if (age <= 60) {
        return "成年"; // 已覆盖（绿色）
    } else {
        return "老年"; // 未覆盖（红色）
    }
}

步骤2：补充测试用例，覆盖未测试分支

原来的测试用例只测了 age=10（未成年）、age=30（成年），没测 age=65（老年），补充测试用例：

@Test
public void testGetUserStatus_Elder() {
    // 补充测试 age=65 的场景，覆盖 else 分支
    String status = userService.getUserStatus(65);
    Assertions.assertEquals("老年", status);
}

步骤3：重新执行测试，查看覆盖率

执行 mvn clean test jacoco:report，重新打开报告，会发现该方法的 else 分支已变为绿色，行覆盖率和分支覆盖率均提升。

四、JaCoCo 进阶配置

基础配置能满足大部分场景，但实际开发中，我们可能需要自定义覆盖率规则、排除不需要统计的代码（如工具类、实体类），这里分享 3 个高频进阶配置。

4.1 排除不需要统计的代码

很多代码不需要统计覆盖率（如实体类、工具类、配置类），可通过配置排除，避免拉低整体覆盖率，修改 JaCoCo 插件配置：

<plugin>
    <groupId>org.jacoco</groupId><artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.10</version>
    <executions>
        <!-- 省略 prepare-agent 和 report 配置，和之前一致 -->
    </executions>
    <configuration><!-- 排除不需要统计覆盖率的类/包 -->
        <excludes>
            <!-- 排除实体类（com.example.demo.entity 包下所有类） -->
            <exclude>com/example/demo/entity/**/*.class</exclude>
            <!-- 排除工具类 -->
            <exclude>com/example/demo/util/**/*.class</exclude>
            <!-- 排除配置类 -->
            <exclude>com/example/demo/config/**/*.class</exclude>
            <!-- 排除单个类 -->
            <exclude>com/example/demo/DemoApplication.class</exclude>
        </excludes>
    </configuration>
</plugin>

注意：排除路径是「类的编译路径」，用 / 分隔包名，不是 .，比如 com.example.demo.entity 对应 com/example/demo/entity/**/*.class。

4.2 自定义覆盖率阈值

为了保证测试质量，我们可以设置覆盖率阈值（如行覆盖率≥80%、分支覆盖率≥70%），如果未达到阈值，Maven 构建会失败，强制开发人员补充测试用例。

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.10</version>
    <executions>
        <execution>
            <id>prepare-agent</id>
            <goals>
                <goal>prepare-agent</goal>
            </goals>
        </execution>
       <execution>
            <id>report</id>
            <phase>test</phase>
            <goals>
                <goal>report</goal>
            </goals>
        </execution>
        <!-- 新增：检查覆盖率阈值 -->
        <execution>
            <id>check</id>
<phase>test</phase>
            <goals>
                <goal>check</goal>
            </goals>
            <configuration>
                <rules>
                    <rule>
                        <element>CLASS</element>
                        <limits>
                           <!-- 行覆盖率≥80% -->
                            <limit>
                                <counter>LINE</counter>
                                <value>COVEREDRATIO</value>
                                <minimum>0.8</minimum>
</limit>
                           <!-- 分支覆盖率≥70% -->
                            <limit>
                                <counter>BRANCH</counter>
                                <value>COVEREDRATIO</value>
                                <minimum>0.7</minimum>
                            </limit>
                            <!-- 方法覆盖率≥85% -->
                            <limit>
                                <counter>METHOD</counter>
                                <value>COVEREDRATIO</value>
                                <minimum>0.85</minimum>
                            </limit>
                        </rules>
                    </rule>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>

说明：如果覆盖率未达到阈值，执行 mvn test 时会报错，提示「覆盖率未达到要求」，需补充测试用例后重新构建。

4.3 生成 XML 报告（适配 CI/CD 集成）

如果项目需要集成 CI/CD（如 Jenkins），可配置 JaCoCo 生成 XML 报告，CI/CD 工具可读取该报告，展示覆盖率统计结果，修改 report 配置：

<execution>
    <id>report</id>
    <phase>test</phase>
    <goals>
        <goal>report</goal>
    </goals>
    <configuration>
        <outputDirectory>${project.build.directory}/jacoco-report</outputDirectory>
        <!-- 生成 XML 报告（CI/CD 用） -->
        <formats>
            <format>HTML</format> <!-- 可视化 HTML 报告（开发用） -->
            <format>XML</format>  <!-- XML 报告（CI/CD 用） -->
        </formats>
    </configuration>
</execution>

五、注意事项

很多开发者集成 JaCoCo 时，会遇到各种问题，整理了 6 个高频坑点，帮你少走弯路：

1. 执行 mvn jacoco:report 报错，提示「jacoco.exec 文件不存在」 → 原因：未先执行测试用例，JaCoCo 没有生成覆盖率数据。解决方案：先执行 mvn test，再执行 mvn jacoco:report，或直接执行 mvn clean test jacoco:report；
2. 报告中没有类/方法，显示为空 → 原因：1. 测试用例未执行到该类/方法；2. 排除配置写错，误排除了需要统计的类；3. 包路径配置错误，JaCoCo 未扫描到类；
3. 覆盖率一直为 0% → 原因：1. 测试用例未执行（比如测试方法加了 @Ignore 注解）；2. JaCoCo 插件配置错误（缺少 prepare-agent 执行）；3. 测试用例执行失败，未生成覆盖率数据；
4. 分支覆盖率始终达不到 100% → 原因：代码中有未覆盖的分支（如 if-else、switch 的某个分支），或有异常捕获逻辑（try-catch 中 catch 块未被测试）。解决方案：补充对应分支的测试用例；
5. SpringBoot 3.x 集成 JaCoCo 报错 → 原因：JaCoCo 版本过低，不兼容 SpringBoot 3.x。解决方案：将 JaCoCo 版本升级到 0.8.8+；
6. 排除配置不生效 → 原因：排除路径写错（用 . 分隔包名，而非/）。解决方案：将 com.example.demo.entity.* 改为 com/example/demo/entity/**/*.class。