17、代码质量工具：集成Checkstyle、PMD、SpotBugs、Jacoco覆盖率报告

说实话，代码质量这个话题，很多团队都是嘴上重视、行动敷衍。我见过太多项目，功能跑通了就万事大吉，代码里藏着各种潜在问题——命名不规范、潜在的空指针、测试覆盖率不到20%。

等到上线出故障了，大家才手忙脚乱地排查。嗯，这种痛我经历过不止一次。

这一章，我们就来聊聊如何在Gradle项目中集成四款主流的质量工具：Checkstyle、PMD、SpotBugs和Jacoco。它们各自负责不同的维度，组合起来就是一套完整的代码质量防线。

核心思路：用自动化工具代替人工审查，把质量问题扼杀在构建阶段。你想想看，与其让代码评审时花半小时争论缩进风格，不如让Checkstyle自动帮你搞定。

Gradle 代码质量工具体系 Gradle 构建 Checkstyle PMD SpotBugs Jacoco 代码风格检查 命名/缩进/注释 潜在缺陷检测 空循环/未用变量 字节码分析 空指针/资源泄漏 测试覆盖率 行/分支/方法覆盖 输出：HTML报告 / XML数据 / 构建失败阻断 集成方式：Gradle 插件 + 配置文件 + 任务依赖

17.1 为什么需要代码质量工具？

我个人习惯把代码质量工具比作「代码的体检医生」。你平时可能觉得自己写得挺好，但工具一扫描，各种小毛病就现原形了。

举个例子：我曾经接手过一个遗留项目，代码里到处都是魔法数字、超长方法、还有几百行的if-else嵌套。手动改？改不完的。后来我直接上了Checkstyle+PMD，配合自定义规则集，两周内把代码规范度从30%提到了85%。

这四款工具的分工很明确：

  • Checkstyle：管的是「长相」——缩进、命名、Javadoc、文件长度等编码规范。
  • PMD：管的是「坏习惯」——空catch块、重复代码、过于复杂的表达式。
  • SpotBugs：管的是「隐藏炸弹」——空指针、资源未关闭、线程安全问题。
  • Jacoco：管的是「测试覆盖」——哪些代码被测试到了，哪些还是盲区。

我的建议：不要一次性把所有规则都打开，否则你会被上千条警告淹死。先开核心规则，逐步收紧。我一般分三个阶段：第一阶段只报error，第二阶段加warning，第三阶段才开全部规则。

17.2 集成Checkstyle

Checkstyle是最容易上手的工具。说白了，它就是检查你的代码是否符合某种「风格公约」。

在Gradle中集成，只需要两步：

第一步：在 build.gradle 中应用插件：

plugins {
    id 'checkstyle'
}

checkstyle {
    toolVersion = '10.12.0'
    configFile = rootProject.file('config/checkstyle/checkstyle.xml')
    maxErrors = 0  // 有error就构建失败
    maxWarnings = 100
}

第二步：编写规则配置文件 config/checkstyle/checkstyle.xml：

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
    "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
    <module name="TreeWalker">
        <module name="JavadocMethod"/>
        <module name="NeedBraces"/>
        <module name="LineLength">
            <property name="max" value="120"/>
        </module>
        <module name="ConstantName"/>
        <module name="LocalVariableName"/>
    </module>
</module>

运行 ./gradlew check 就会自动执行Checkstyle检查。报告在 build/reports/checkstyle/ 目录下。

注意：Checkstyle的规则文件写起来有点繁琐。我建议直接从官方GitHub下载一个现成的 google_checks.xml 或 sun_checks.xml，在此基础上改。别自己从头写，太累了。

17.3 集成PMD

PMD比Checkstyle更「聪明」一些。它不光看格式，还会分析代码逻辑。比如你写了个空的if块，或者声明了变量却没用，PMD都能揪出来。

配置方式类似：

plugins {
    id 'pmd'
}

pmd {
    toolVersion = '6.55.0'
    ruleSetFiles = rootProject.files('config/pmd/ruleset.xml')
    rulePriority = 3  // 只报告优先级3及以上的问题
    ignoreFailures = false
}

规则文件示例：

<?xml version="1.0"?>
<ruleset name="Custom Rules">
    <rule ref="category/java/bestpractices.xml" />
    <rule ref="category/java/errorprone.xml" />
    <rule ref="category/java/performance.xml" />
    
    <!-- 排除某些规则 -->
    <rule ref="category/java/design.xml/ExcessiveMethodLength">
        <properties>
            <property name="minimum" value="80"/>
        </properties>
    </rule>
</ruleset>

运行后，PMD报告在 build/reports/pmd/ 下。我个人习惯把PMD的优先级1和2的规则设为「必须修复」，优先级3和4的作为「建议修复」。

17.4 集成SpotBugs

SpotBugs是FindBugs的继任者。它分析的是编译后的字节码，所以能发现一些源码层面看不到的问题。比如你调用了 equals() 但没检查null，或者 InputStream 没有在finally中关闭。

配置方式：

plugins {
    id 'com.github.spotbugs' version '5.0.14'
}

spotbugs {
    toolVersion = '4.7.3'
    ignoreFailures = false
    effort = 'max'  // 分析深度：max/min/default
    reportLevel = 'low'  // 报告级别：low/medium/high
}

// 生成HTML报告
tasks.withType(com.github.spotbugs.snom.SpotBugsTask) {
    reports {
        html.required = true
        xml.required = false
    }
}

避坑指南：我曾经在项目中遇到SpotBugs报了一大堆「可能空指针」的警告，结果发现是因为我们用了Optional，而SpotBugs的旧版本对Optional支持不好。升级到最新版就解决了。所以记得保持工具版本更新。

17.5 集成Jacoco覆盖率报告

Jacoco是我最看重的工具之一。没有覆盖率数据的项目，就像闭着眼睛开车——你根本不知道测试到底测了哪些地方。

配置方式：

plugins {
    id 'jacoco'
}

jacoco {
    toolVersion = '0.8.10'
}

jacocoTestReport {
    dependsOn test
    reports {
        html.required = true
        xml.required = true
        csv.required = false
    }
}

// 设置覆盖率阈值
jacocoTestCoverageVerification {
    violationRules {
        rule {
            limit {
                minimum = 0.80  // 行覆盖率不低于80%
            }
        }
        rule {
            element = 'CLASS'
            excludes = [
                'com.example.dto.*',
                'com.example.config.*'
            ]
            limit {
                counter = 'LINE'
                value = 'COVEREDRATIO'
                minimum = 0.70
            }
        }
    }
}

check.dependsOn jacocoTestCoverageVerification

运行 ./gradlew jacocoTestReport 就能在 build/reports/jacoco/ 下看到漂亮的HTML报告。红色表示未覆盖，绿色表示已覆盖，一目了然。

核心指标：我个人认为，一个健康的项目应该满足：行覆盖率 > 80%，分支覆盖率 > 70%。低于这个线，说明测试写得太敷衍了。

17.6 统一执行与报告聚合

你肯定不想每次手动执行四个任务吧？我们可以把它们串起来：

// 定义一个聚合任务
tasks.register('codeQuality') {
    dependsOn 'checkstyleMain', 'pmdMain', 'spotbugsMain', 'jacocoTestReport'
    group = 'verification'
    description = '执行所有代码质量检查并生成报告'
}

// 让check任务依赖所有质量检查
check.dependsOn codeQuality

这样，你只需要运行 ./gradlew check，四个工具就会依次执行。如果任何一个工具报错，构建就会失败。

报告聚合方面，我建议用CI工具（如Jenkins、GitLab CI）来收集这些HTML报告，做成一个统一的仪表盘。这样团队每个人都能看到代码质量的趋势——是变好了还是变差了。

17.7 一些实战经验

最后分享几点我在项目中踩过的坑：

  • 不要一开始就全开规则。 我曾经在一个老项目上直接开了Checkstyle的全部规则，结果报了3000多个错误，直接把团队干懵了。正确的做法是：先开10条核心规则，跑通后再逐步增加。
  • 排除掉自动生成的代码。 比如Lombok生成的getter/setter、MyBatis的Mapper实现类，这些不需要检查。在配置里加上 excludes 即可。
  • Jacoco的覆盖率阈值要合理。 我见过有人设100%覆盖率，结果团队为了达标写了大量无意义的测试。80%是个比较务实的目标。
  • 把质量检查放在CI流水线里。 本地开发时可以跳过（毕竟有时候赶进度），但合并到主分支前必须通过所有检查。这是底线。

重要提醒：工具只是辅助，不能替代人的判断。有时候PMD报的「方法过长」可能恰恰是业务逻辑需要。学会「什么时候忽略工具」，也是工程师的必修课。

好了，这一章的内容就到这里。代码质量不是一蹴而就的事，但有了这些工具，至少你能知道自己的代码「健康」还是「亚健康」。动手试试吧，从今天开始给你的项目加上这些检查。

公众号:蓝海资料掘金营，微信deep3321

← 上一章 📖 返回目录 下一章 →