Kotlinter Gradle

这是一个无痛的Gradle插件，用于使用出色的ktlint引擎对Kotlin源文件进行lint检查和格式化。

它旨在易于设置，无需任何配置，并且开箱即用的行为符合预期。

它还很快，因为它直接将ktlint引擎与Gradle的增量构建集成，并使用Worker API并行化工作。

安装

可在Gradle插件门户获取：https://plugins.gradle.org/plugin/org.jmailen.kotlinter

单模块

<details open> <summary>Kotlin</summary>

plugins {
    id("org.jmailen.kotlinter") version "4.4.1"
}

</details> <details> <summary>Groovy</summary>

plugins {
    id "org.jmailen.kotlinter" version "4.4.1"
}

</details>

多模块和Android

<details open> <summary>Kotlin</summary> 根目录 `build.gradle.kts`

plugins {
    id("org.jmailen.kotlinter") version "4.4.1" apply false
}

每个包含Kotlin源代码的模块的 build.gradle.kts

plugins {
    id("org.jmailen.kotlinter")
}

</details> <details> <summary>Groovy</summary> 根目录 `build.gradle`

plugins {
    id 'org.jmailen.kotlinter' version "4.4.1" apply false
}

每个包含Kotlin源代码的模块的 build.gradle

plugins {
    id 'org.jmailen.kotlinter'
}

</details>

兼容性

kotlinter版本	最低kotlin版本	最高kotlin版本	最低gradle版本
4.2.0+	1.9.20	-	8.4
4.0.0+	1.9.0	-	7.6
3.14.0+	1.8.0	1.8.22	7.6
3.11.0+	1.7.0	1.7.22	7.0
3.10.0+	1.6.20	1.6.21	7.0
3.7.0+	1.5.31	1.6.10	7.0
3.5.0+	1.5.0	1.5.30	6.8
3.0.0+	1.4.0	1.4.30	6.8
2.0.0+	1.3.0	1.3.30	-

特性

• 支持Kotlin Gradle插件：
  • JVM
  • 多平台
  • Android
• 支持.kt和.kts文件
• 独立的LintTask和FormatTask类型用于定义自定义任务
• 支持增量构建并通过Gradle Worker API快速并行化
• 在可用时从.editorconfig配置
• 可配置的报告器

任务

当您的项目使用支持的Kotlin Gradle插件之一时，Kotlinter会添加以下任务：

formatKotlin：根据ktlint规则格式化Kotlin源代码，或在无法自动格式化时发出警告。

lintKotlin：报告Kotlin lint错误，默认情况下会导致构建失败。

此外，check任务会依赖于lintKotlin。

为项目中的每个源集添加了细粒度的任务：formatKotlinSourceSet和lintKotlinSourceSet。

Git钩子

Kotlinter可以安装一个钩子来在推送前运行（installKotlinterPrePushHook）。这个钩子会运行lintKotlin，如果有错误，则运行formatKotlin并以非零状态退出，保留更改的文件以待提交。

您必须将kotlinter插件应用到根项目才能使用此任务。如果使用git worktree，您必须从父git目录安装钩子。

要在有人运行构建时自动安装钩子，请在根项目的build.gradle.kts中添加以下内容：

<details open> <summary>Kotlin</summary>

tasks.check {
    dependsOn("installKotlinterPrePushHook")
}

</details> <details> <summary>Groovy</summary>

tasks.named('check') {
    dependsOn 'installKotlinterPrePushHook'
}

</details>

配置

选项在kotlinter扩展中配置。以下是默认值（如果您想使用这些默认值，可以完全省略配置块）。

<details open> <summary>Kotlin</summary>

kotlinter {
    failBuildWhenCannotAutoFormat = false
    ignoreFailures = false
    reporters = arrayOf("checkstyle", "plain")
}

</details> <details> <summary>Groovy</summary>

kotlinter {
    failBuildWhenCannotAutoFormat = false
    ignoreFailures = false
    reporters = ['checkstyle', 'plain']
}

</details>

将failBuildWhenCannotAutoFormat设置为true会配置formatKotlin任务在无法自动修复lint错误时使构建失败。将ignoreFailures设置为true会覆盖此设置。

reporters的选项：checkstyle、html、json、plain、sarif

报告器的行为如描述：https://github.com/pinterest/ktlint

Editorconfig

如果存在.editorconfig文件，Kotlinter将使用它进行自我配置。 此配置包括代码风格和代码检查规则。

有关详细信息，请参阅KtLint配置。

自定义任务

formatKotlin*SourceSet和lintKotlinSourceSet*任务继承自SourceTask，因此您可以自定义包含、排除和源文件。

<details open> <summary>Kotlin</summary>

tasks.withType<LintTask> {
    this.source = this.source.minus(fileTree("src/generated")).asFileTree
}

tasks.withType<FormatTask> {
    this.source = this.source.minus(fileTree("src/generated")).asFileTree
}

</details> <details> <summary>Groovy</summary>

tasks.named("lintKotlinMain") {
  source = source - fileTree("$buildDir/generated")
}

</details>

请注意，排除路径是相对于包根目录的。

自定义任务

如果您没有使用受支持插件的自动配置，或者需要处理额外的源代码，您可以创建自定义任务：

<details open> <summary>Kotlin</summary>

import org.jmailen.gradle.kotlinter.tasks.LintTask
import org.jmailen.gradle.kotlinter.tasks.FormatTask

tasks.register<LintTask>("ktLint") {
    group = "verification"
    source(files("src"))
    reports.set(
        mapOf(
            "plain" to file("build/lint-report.txt"),
            "json" to file("build/lint-report.json")
        )
    )
}

tasks.register<FormatTask>("ktFormat") {
    group = "formatting"
    source(files("src"))
    report.set(file("build/format-report.txt"))
}

</details> <details> <summary>Groovy</summary>

import org.jmailen.gradle.kotlinter.tasks.LintTask
import org.jmailen.gradle.kotlinter.tasks.FormatTask

tasks.register('ktLint', LintTask) {
    group 'verification'
    source files('src')
    reports = [
            'plain': file('build/lint-report.txt'),
            'json' : file('build/lint-report.json')
    ]
}


tasks.register('ktFormat', FormatTask) {
  group 'formatting'
  source files('src/test')
  report = file('build/format-report.txt')
}

</details>

自定义ktlint版本

如果您需要使用不同版本的ktlint，可以覆盖依赖项。

<details open> <summary>Kotlin或Groovy</summary>

buildscript {
    configurations.classpath {
        resolutionStrategy {
            force(
                "com.pinterest.ktlint:ktlint-rule-engine:1.2.1",
                "com.pinterest.ktlint:ktlint-rule-engine-core:1.2.1",
                "com.pinterest.ktlint:ktlint-cli-reporter-core:1.2.1",
                "com.pinterest.ktlint:ktlint-cli-reporter-checkstyle:1.2.1",
                "com.pinterest.ktlint:ktlint-cli-reporter-json:1.2.1",
                "com.pinterest.ktlint:ktlint-cli-reporter-html:1.2.1",
                "com.pinterest.ktlint:ktlint-cli-reporter-plain:1.2.1",
                "com.pinterest.ktlint:ktlint-cli-reporter-sarif:1.2.1",
                "com.pinterest.ktlint:ktlint-ruleset-standard:1.2.1"
            )
        }
    }
}

</details>

另外，如果您有使用kotlinter的自定义构建约定插件，可以通过platform指令强制使用较新的KtLint版本：

<details open> <summary>Kotlin或Groovy</summary>

dependencies {
    implementation(platform("com.pinterest.ktlint:ktlint-bom:1.2.1"))
    implementation("org.jmailen.gradle:kotlinter-gradle:4.4.1")
}

自定义规则

您可以使用buildscript类路径添加自定义ktlint RuleSets：

<details open> <summary>Kotlin</summary>

buildscript {
    dependencies {
        classpath(files("libs/my-custom-ktlint-rules.jar"))
        classpath("org.other.ktlint:custom-rules:1.0")
    }
}

</details> <details> <summary>Groovy</summary>

buildscript {
    dependencies {
        classpath files('libs/my-custom-ktlint-rules.jar')
        classpath 'org.other.ktlint:custom-rules:1.0'
    }
}

</details>