Android Studio Detekt 使用

Detekt 是 Kotlin 专用静态代码检查工具，检测代码异味、圈复杂度、编码规范、潜在 bug；类似 Android Lint，但只针对 Kotlin 代码，支持 Gradle 任务、CI 门禁、IDE 实时提示、基线忽略历史问题detekt。

版本说明：1.23.x 稳定版；2.x 大版本，注意和项目 Kotlin 版本匹配。

1、根目录 build.gradle.kts 配置（全局推荐，多模块共用）

kotlin

dart 复制代码

plugins {
    id("io.gitlab.arturbosch.detekt") version "1.23.8"
}

detekt {
    toolVersion = "1.23.8"
    // 继承默认规则，只写自定义修改，不用复制全部默认规则
    buildUponDefaultConfig = true
    // 自定义规则配置文件，放在项目根目录 config/detekt/detekt.yml
    config.setFrom(files("config/detekt/detekt.yml"))
    // 基线文件：老项目忽略历史旧问题，只拦截新增问题
    baseline = file("config/detekt/baseline.xml")
    // true：检查失败不打断构建；CI门禁要改为 false
    ignoreFailures = false
}

// 配置输出报告：html、checkstyle(xml)、sarif
tasks.withType<io.gitlab.arturbosch.detekt.Detekt>().configureEach {
    reports {
        html.required.set(true)
        checkstyle.required.set(true)
        sarif.required.set(true)
    }
}

Groovy 版本语法不一样，注意区分。

2、生成默认配置文件 detekt.yml

执行 gradle 任务，会生成完整规则模板，复制到config/detekt/detekt.yml，按需开关规则、调整阈值Kotlin

shell

bash 复制代码

./gradlew detektGenerateConfig

示例修改 detekt.yml 片段：

yaml

yaml 复制代码

complexity:
  LongMethod:
    active: true
    threshold: 30  # 方法行数阈值
style:
  MagicNumber:
    active: false # 关闭魔法数字检查

3、常用 Gradle 命令

shell

bash 复制代码

# 执行全项目detekt扫描
./gradlew detekt

# 生成基线baseline.xml，老项目第一次执行，把存量问题录入基线不再报错
./gradlew detektBaseline

# 同时detekt会绑定到check任务，执行 ./gradlew check 自动跑detekt+单元测试
./gradlew check

报告输出路径：app/build/reports/detekt/，打开 html 可以看完整问题位置、规则说明GitHub。

4、Android Studio IDE 插件（实时编辑器提示）

File → Settings → Plugins，搜索 Detekt 安装官方插件
Settings → Tools → Detekt
- ✅ Enable detekt
- Configuration file：选择项目的config/detekt/detekt.yml
- Baseline file：选择baseline.xml
保存，kt 文件内直接出现黄色 / 红色警告，鼠标悬浮看到 detekt 规则 ID。

⚠️ 插件只是 IDE 实时提示；真正门禁必须执行 gradle detekt 任务，插件和 gradle 任务是两套独立运行，必须保证两者配置文件完全一致。

5、忽略报错两种方式

方式 1：代码内注解忽略（单个位置）

kotlin

kotlin 复制代码

// LongMethod 是规则ID
@Suppress("LongMethod")
fun bigFunc() {

}

也可以写集合：@Suppress("LongMethod", "MagicNumber")detekt

方式 2：baseline 基线（批量忽略历史旧代码）

运行detektBaseline生成baseline.xml，已经存在的旧问题自动忽略；新增同类代码会报错。

代码大量修改重构后，建议重新执行 detektBaseline 更新基线。

6、格式化插件 detekt‑formatting（集成 ktlint 格式化）

detekt 本身不做格式化，需要额外引入 formatting 插件，对齐格式化规范：根目录 build.gradle.kts

kotlin

scss 复制代码

dependencies {
    detektPlugins("io.gitlab.arturbosch.detekt:detekt-formatting:1.23.8")
}

执行 detekt 就会同时检测代码格式（换行、逗号、空格）。

7、CI/Gerrit 门禁集成

CI 脚本执行：./gradlew detekt
返回非 0 退出码代表发现违规，直接阻断提交；ignoreFailures=false
上传checkstyle.xml报告到 Gerrit 做代码评审展示。

8、常见踩坑

Kotlin 版本不匹配：detekt 版本必须和项目 Kotlin 版本兼容，Kotlin2.0 + 要用 detekt 2.x
IDE 插件提示和 gradle 执行结果不一致：确认插件指定的 yml、baseline 路径和 gradle 配置完全一致
baseline 不生效：不要手动修改 baseline.xml，重新运行detektBaseline生成
排除目录：在 detekt.yml 中配置 excludes，排除 build、generated 生成代码

yaml

markdown 复制代码

build:
  excludes:
    - '**/build/**'
    - '**/generated/**'

detekt vs ktlint 简单区分

表格

工具	定位
detekt	代码异味、复杂度、bug 风险、编码规范（静态分析）
ktlint	只做代码格式化（空格换行）

detekt‑formatting 底层封装 ktlint，两者可以二选一。