Checkstyle 插件使用 Checkstyle 对项目的 Java 源文件执行质量检查,并从这些检查中生成报告。

用法

要使用 Checkstyle 插件,请在您的构建脚本中包含以下内容

build.gradle.kts
plugins {
    checkstyle
}
build.gradle
plugins {
    id 'checkstyle'
}

该插件向项目添加了许多执行质量检查的任务。您可以通过运行 gradle check 来执行检查。

请注意,Checkstyle 将使用与运行 Gradle 相同的 Java 版本运行。

任务

Checkstyle 插件向项目添加以下任务

checkstyleMainCheckstyle

依赖于classes

对生产 Java 源文件运行 Checkstyle。

checkstyleTestCheckstyle

依赖于: testClasses

对测试 Java 源文件运行 Checkstyle。

checkstyleSourceSetCheckstyle

依赖于: sourceSetClasses

对给定源集的 Java 源文件运行 Checkstyle。

添加到其他任务的依赖项

Checkstyle 插件向 Java 插件定义的任务添加以下依赖项。

check

依赖于: 所有 Checkstyle 任务,包括 checkstyleMaincheckstyleTest

项目布局

默认情况下,Checkstyle 插件期望配置文件放置在根项目中,但这可以更改。

<root>
└── config
    └── checkstyle           (1)
        └── checkstyle.xml   (2)
        └── suppressions.xml
1 Checkstyle 配置文件放在这里
2 主要的 Checkstyle 配置文件

依赖管理

Checkstyle 插件添加以下依赖配置

表 1. Checkstyle 插件 - 依赖配置
名称 含义

checkstyle

要使用的 Checkstyle 库

默认情况下,checkstyle 配置使用 com.puppycrawl.tools:checkstyle。使用的 com.puppycrawl.tools:checkstyle 版本是从扩展的工具版本派生的

checkstyle {
    toolVersion = "10.12.4"
}

如果添加了另一个依赖项,则默认的 com.puppycrawl.tools:checkstyle 依赖项将被删除

checkstyle {
    toolVersion = "10.12.4"
}

dependencies {
    checkstyle "group:artifact:version"
}

要在 checkstyle 配置中添加依赖项,同时保留对 com.puppycrawl.tools:checkstyle 的依赖项,请使用以下解决方案

checkstyle {
    toolVersion = "10.12.4"
}

dependencies {
    checkstyle "com.puppycrawl.tools:checkstyle:${checkstyle.toolVersion}"
    checkstyle "group:artifact:version"
}

配置

有关全面的配置选项,请参阅 API 文档中的 CheckstyleExtension 类。

使用 Java Toolchains 配置 Checkstyle

Checkstyle 要求最低 JDK 11,并预计在即将发布的版本中过渡到 JDK 17。对于针对早期 JDK 版本(例如 JDK 8)的项目,这提出了兼容性挑战。历史上,用户会求助于后向移植依赖项(例如 com.puppycrawl.tools:checkstyle-backport-jre8)来弥合这一差距。然而,随着 Checkstyle 和 Gradle 都与现代 Java 版本保持一致,通过 Gradle 的 Java toolchains 可以获得更健壮和面向未来的解决方案。

通过利用 javaLauncher 属性,您可以明确配置 Checkstyle 任务以指定的 JDK 版本执行,而独立于用于项目编译或 Gradle 运行时的 JDK。以下配置确保 Checkstyle 在 JDK 17 下运行

tasks.withType(Checkstyle).configureEach {
    javaLauncher = javaToolchains.launcherFor {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

这种方法有几个优点

  • 解耦:Checkstyle 执行与项目的 JDK 隔离,无需更改构建的核心环境即可实现兼容性。

  • 自动化:Gradle 的 toolchain 支持自动配置指定的 JDK,简化设置并确保跨环境的一致性。

  • 可持续性:它消除了对社区维护的后向移植的依赖,这些后向移植可能会滞后于官方版本或引入维护开销。

我们强烈建议采用此配置作为管理 Checkstyle JDK 要求的首选方法,尤其是在生态系统向 JDK 17 及更高版本发展的过程中。

内置变量

Checkstyle 插件定义了一个 config_loc 属性,可在 Checkstyle 配置文件中使用,以定义指向其他配置文件(如 suppressions.xml)的路径。

checkstyle.xml
<module name="SuppressionFilter">
    <property name="file" value="${config_loc}/suppressions.xml"/>
</module>

自定义 HTML 报告

Checkstyle 任务生成的 HTML 报告可以使用 XSLT 样式表进行自定义,例如突出显示特定错误或更改其外观

build.gradle.kts
tasks.withType<Checkstyle>().configureEach {
    reports {
        xml.required = false
        html.required = true
        html.stylesheet = resources.text.fromFile("config/xsl/checkstyle-custom.xsl")
    }
}
build.gradle
tasks.withType(Checkstyle) {
    reports {
        xml.required = false
        html.required = true
        html.stylesheet = resources.text.fromFile('config/xsl/checkstyle-custom.xsl')
    }
}

生成 SARIF 报告

Checkstyle 10.3.3 及更高版本支持 SARIF 报告。默认情况下未启用。

build.gradle.kts
checkstyle {
    toolVersion = "10.3.3"
}
tasks.withType<Checkstyle>().configureEach {
    reports {
        sarif.required = true
    }
}
build.gradle
checkstyle {
    toolVersion = '10.3.3'
}
tasks.withType(Checkstyle) {
    reports {
        sarif.required = true
    }
}

更改分配给 Checkstyle 的内存量

Checkstyle 分析在单独的进程中执行。默认情况下,Checkstyle 进程的最大堆为 512MB。在分析许多源文件时,您可能需要为该进程提供额外的内存。您可以通过配置 Checkstyle.maxHeapSize 来更改 Checkstyle 的内存量。

build.gradle.kts
tasks.withType<Checkstyle>().configureEach {
    minHeapSize = "200m"
    maxHeapSize = "1g"
}
build.gradle
tasks.withType(Checkstyle) {
    minHeapSize = "200m"
    maxHeapSize = "1g"
}