Ktlint 自定义集成开发指南

概述

Ktlint 是一款流行的 Kotlin 代码风格检查工具，它提供了强大的 API 支持自定义集成。本文将深入讲解如何利用 Ktlint 的规则引擎进行二次开发，实现自定义的代码检查和格式化功能。

核心组件：KtLintRuleEngine

Ktlint 的核心是 KtLintRuleEngine，它是所有自定义集成的入口点。这个引擎只需要在应用程序生命周期中创建一次，重复使用可以提高性能。

创建规则引擎

val ktLintRuleEngine = KtLintRuleEngine(
    ruleProviders = KTLINT_API_CONSUMER_RULE_PROVIDERS,
)

规则提供器(RuleProvider)

规则引擎需要至少一个 RuleProvider 来配置。RuleProvider 是一个 lambda 表达式，当规则引擎需要时会提供特定规则的新实例。

自定义规则示例

val KTLINT_API_CONSUMER_RULE_PROVIDERS = setOf(
    // 自定义规则
    RuleProvider { NoVarRule() },
    // 使用 KtLint 内置规则
    RuleProvider { IndentationRule() },
)

EditorConfig 配置

Ktlint 在检查代码时会考虑路径上的 .editorconfig 文件。我们可以通过三种方式配置编辑器设置：

1. editorConfigOverride：优先级最高，会覆盖 .editorconfig 文件中的设置
2. editorConfigDefaults：作为后备值，当属性未定义时使用
3. .editorconfig 文件：常规配置文件

覆盖配置示例

val ktLintRuleEngine = KtLintRuleEngine(
    ruleProviders = KTLINT_API_CONSUMER_RULE_PROVIDERS,
    editorConfigOverride = EditorConfigOverride.from(
        INDENT_STYLE_PROPERTY to IndentConfig.IndentStyle.SPACE,
        INDENT_SIZE_PROPERTY to 4
    )
)

默认配置加载

val ktLintRuleEngine = KtLintRuleEngine(
    ruleProviders = KTLINT_API_CONSUMER_RULE_PROVIDERS,
    editorConfigDefaults = EditorConfigDefaults.load(
        path = Paths.get("/path/to/editorconfig"),
        propertyTypes = KTLINT_API_CONSUMER_RULE_PROVIDERS.propertyTypes(),
    )
)

代码检查与格式化

配置好规则引擎后，就可以对代码进行检查和格式化了。

代码来源

代码可以来自文件或代码片段：

// 从文件加载
val code = Code.fromFile(File("/path/to/file"))

// 从代码片段加载
val code = Code.fromSnippet("""
    val code = "some-code"
""".trimIndent())

代码检查(Lint)

ktLintRuleEngine.lint(code) { lintError ->
    // 处理检查出的问题
}

代码格式化(Format)

Ktlint 1.3 引入了新的格式化 API，允许对每个问题单独决定是否自动修复：

val formattedCode = ktLintRuleEngine.format(code) { lintError ->
    if (lintError.canBeAutoCorrected) {
        AutocorrectDecision.ALLOW_AUTOCORRECT
    } else {
        AutocorrectDecision.NO_AUTOCORRECT
    }
}

自定义规则开发

从 Ktlint 1.3 开始，建议自定义规则实现 RuleAutocorrectApproveHandler 接口，以支持更灵活的自动修复控制。

新旧 API 对比

旧版本 (将被废弃)	新版本 (推荐)
beforeVisitChildNodes(node, autoCorrect, emit)	beforeVisitChildNodes(node, emit)

实现示例

emit(node.startOffset, "错误信息", true)
   .ifAutocorrectAllowed {
       // 执行自动修复
   }

日志配置

Ktlint 使用 io.github.oshai:kotlin-logging 作为日志框架，它是 slf4j 的封装。开发者可以自由选择日志实现并进行配置。

最佳实践

1. 重用规则引擎实例：避免重复创建，提高性能
2. 实现新接口：自定义规则应实现 RuleAutocorrectApproveHandler
3. 合理配置 EditorConfig：根据项目需求设置默认值和覆盖值
4. 渐进式迁移：从旧 API 逐步迁移到新 API

通过本文的指导，开发者可以充分利用 Ktlint 的强大功能，构建符合团队需求的代码质量检查工具。