Kotlin 项目中的代码质量工具
代码质量工具可以帮助你强制执行编码标准, 尽早发现错误, 测量测试覆盖率, 并维护整个 Kotlin 项目的代码质量. 本指南介绍如何将常用工具集成到使用 Maven 或 Gradle 的后端项目中, 例如 ktlint, detekt, SonarQube, SonarCloud, 以及 Kover.
使用 ktlint 进行代码格式化
ktlint 是一个 Kotlin 代码检查和格式化工具, 不需要需额外的配置, 即可强制执行 Kotlin 官方的 编码规范.
ktlint 会检查各种代码规则, 例如缩进, 操作符周围的空格, import 顺序, 以及尾随逗号. 如果发现违反规则的代码, 构建会失败, 并通过错误消息显示对应的文件和行号. 除了报告违规之外, ktlint 还能自动修复简单的问题.
要在项目中集成 ktlint, 请执行以下步骤:
在构建文件中添加插件:
<!-- pom.xml --> <plugin> <groupId>com.github.gantsign.maven</groupId> <artifactId>ktlint-maven-plugin</artifactId> <version>3.7.1</version> <executions> <execution> <id>check</id> <goals> <goal>check</goal> </goals> </execution> </executions> </plugin>// build.gradle.kts plugins { id("org.jlleitschuh.gradle.ktlint") version "12.3.0" }运行代码检查工具, 检查代码风格:
mvn ktlint:check./gradlew ktlintCheck(可选) 也可以在项目的根目录中添加
.editorconfig文件, 自定义规则. 例如, 允许通配符 import, 并禁用尾随逗号检查:[*.{kt,kts}] ij_kotlin_imports_layout = * ktlint_standard_trailing-comma-on-call-site = disabled ktlint_standard_trailing-comma-on-declaration-site = disabled默认情况下, ktlint 遵循 Kotlin 的官方编码规范. 如果你更喜欢与 Kotlin 规范有明显差异的 Android Kotlin 风格指南, 请在
.editorconfig文件中, 将代码风格设置为android_studio:[*.{kt,kts}] ktlint_code_style = android_studio要自动修复格式问题, 请运行:
mvn ktlint:format./gradlew ktlintFormat
关于可用的功能和规则, 详情请参见 ktlint 文档.
使用 detekt 进行代码分析
detekt 是一个 Kotlin 静态代码分析工具, 能够检测代码异味, 复杂度问题, 以及潜在的错误.
要在项目中集成 detekt, 请执行以下步骤:
在构建文件中添加插件:
<!-- pom.xml --> <plugin> <groupId>com.github.ozsie</groupId> <artifactId>detekt-maven-plugin</artifactId> <version>1.23.8</version> <executions> <execution> <phase>verify</phase> <goals> <goal>check</goal> </goals> </execution> </executions> </plugin>// build.gradle.kts plugins { id("io.gitlab.arturbosch.detekt") version "1.23.8" }生成默认的
detekt.yml配置文件:mvn detekt:generate-config./gradlew detektGenerateConfig打开
detekt.yml文件, 对生成的文件中的规则进行定制. 例如:complexity: LongMethod: threshold: 50 style: MagicNumber: active: false在构建文件中引用配置文件, 让 detekt 应用新的规则:
<!-- pom.xml --> <plugin> <groupId>com.github.ozsie</groupId> <artifactId>detekt-maven-plugin</artifactId> <version>1.23.8</version> <configuration> <config>detekt.yml</config> <report> <report>txt:reports/detekt.txt</report> <report>xml:reports/detekt.xml</report> </report> </configuration> <executions> <execution> <phase>verify</phase> <goals> <goal>check</goal> </goals> </execution> </executions> </plugin>// build.gradle.kts detekt { toolVersion = "1.23.8" config.setFrom(file("config/detekt/detekt.yml")) buildUponDefaultConfig = true }运行代码分析:
mvn detekt:check./gradlew detekt
detekt 会生成报告, 列出所有违反规则的代码, 严重程度, 文件位置, 以及问题说明. 默认情况下, Gradle 将报告输出到项目根目录下的 build/reports/detekt 目录, Maven 输出到 reports/detekt 目录.
使用 SonarSource 进行代码质量检查
SonarSource 的 SonarQube 和 SonarCloud 为 Kotlin 项目提供深入的静态分析, 包括通过 Web 仪表板进行 bug 检测, 漏洞扫描, 以及代码覆盖率跟踪.
要使用 SonarQube 分析项目, 请执行以下步骤:
在构建文件中添加插件:
<!-- pom.xml --> <plugin> <groupId>org.sonarsource.scanner.maven</groupId> <artifactId>sonar-maven-plugin</artifactId> <version>5.7.0.6970</version> </plugin>// build.gradle.kts plugins { id("org.sonarqube") version "6.2.0.5505" } sonar { properties { property("sonar.projectKey", "my-project") property("sonar.host.url", "http://localhost:9000") } }(可选) 配置分析属性. 例如, 要让构建等待品质门禁(Quality Gate)的结果, 并在未通过品质门禁检测时让构建失败, 请添加
sonar.qualitygate.wait属性:mvn verify sonar:sonar \ -Dsonar.qualitygate.wait=true \ -Dsonar.projectKey=my-project \ -Dsonar.host.url=http://localhost:9000 \ -Dsonar.token=YOUR_TOKEN// build.gradle.kts sonar { properties { property("sonar.qualitygate.wait", "true") } }在 SonarQube 服务器上运行分析:
mvn verify sonar:sonar \ -Dsonar.projectKey=my-project \ -Dsonar.host.url=http://localhost:9000 \ -Dsonar.token=YOUR_TOKEN对于 SonarCloud, 请将主机 URL 替换为
https://sonarcloud.io, 并提供你的组织密钥:mvn verify sonar:sonar \ -Dsonar.projectKey=my-project \ -Dsonar.organization=my-org \ -Dsonar.host.url=https://sonarcloud.io \ -Dsonar.token=YOUR_TOKEN要运行分析, 请使用
sonar任务, 并提供身份验证 token:./gradlew sonar \ -Dsonar.token=YOUR_TOKEN默认情况下, 分析会针对本地 SonarQube 服务器运行. 要使用 SonarCloud, 请更新
build.gradle.kts中的sonar {}代码块, 将主机 URL 设为https://sonarcloud.io, 并添加组织密钥:sonar { properties { property("sonar.projectKey", "example-project") property("sonar.organization", "example-org") property("sonar.host.url", "https://sonarcloud.io") } }打开 SonarQube 或 SonarCloud 仪表板查看结果. 仪表板会根据类型 (bug, 漏洞, 代码异味) 和严重程度, 对问题分组显示.
详情请参见 SonarSource 文档.
使用 Kover 测量代码覆盖率
Kover 是 JetBrains 官方的 Kotlin 代码覆盖率工具. 它会测量代码中哪些行和分支被测试覆盖, 并生成供人类阅读的报告.
与 JaCoCo 不同, Kover 能正确理解 Kotlin 特有的结构, 例如内联函数, 数据类, 因此它能报告更准确的覆盖率数字, 不会由于编译器生成的字节码而产生误报.
要在项目中集成 Kover, 请执行以下步骤:
在构建文件中添加插件:
<!-- pom.xml --> <plugin> <groupId>org.jetbrains.kotlinx</groupId> <artifactId>kover-maven-plugin</artifactId> <version>0.9.8</version> <executions> <execution> <id>instr</id> <goals> <goal>instrumentation</goal> </goals> </execution> <execution> <id>kover-verify</id> <goals> <goal>verify</goal> </goals> </execution> <execution> <id>kover-report-xml</id> <goals> <goal>report-xml</goal> </goals> </execution> <execution> <id>kover-report-html</id> <goals> <goal>report-html</goal> </goals> </execution> </executions> </plugin>// build.gradle.kts plugins { id("org.jetbrains.kotlinx.kover") version "0.9.8" }运行测试, 收集覆盖率数据, 并生成报告:
mvn verify./gradlew koverVerify koverHtmlReport打开 HTML 报告, 报告生成在
target/site/kover/html/目录下 (对于 Gradle 项目, 生成在build/reports/kover/html/目录下), 逐行查看覆盖率.(可选) 要强制执行最低覆盖率阈值, 在不满足条件时使构建失败, 可以在构建文件中添加覆盖率验证的配置. 例如:
<!-- pom.xml --> <configuration> <!-- 创建新的覆盖率验证规则 --> <rules> <rule> <bounds> <bound> <minValue>50</minValue> <coverageUnits>LINE</coverageUnits> <aggregationForGroup>COVERED_PERCENTAGE</aggregationForGroup> </bound> </bounds> </rule> </rules> </configuration>// build.gradle.kts // 添加 `kover` 配置代码块 import kotlinx.kover.gradle.plugin.dsl.* kover { reports { total { log { aggregationForGroup = AggregationType.COVERED_PERCENTAGE coverageUnits = CoverageUnit.LINE } verify { rule { minBound(50) } } } } }
其他工具
除了 ktlint, detekt, SonarQube, SonarCloud 和 Kover 之外, 也可以尝试其他工具, 来提升 Kotlin 代码质量: