21、Kotlin DSL：从Groovy迁移到Kotlin DSL、Kotlin DSL的优势、常用写法对比

说实话，我第一次接触 Gradle 的 Kotlin DSL 时，内心是抗拒的。

那时候 Groovy 用得挺顺手，build.gradle 文件写得飞起。直到有一次，我在一个大型多模块项目里，因为 Groovy 的动态类型特性，折腾了整整一个下午才找到一个括号不匹配的 bug。嗯，从那以后，我开始认真考虑迁移到 Kotlin DSL。

为什么 Kotlin DSL 值得迁移？

说白了，Kotlin DSL 就是 Gradle 官方推荐的下一代构建脚本语言。它和 Groovy DSL 最大的区别在于：类型安全。

我个人习惯用 IntelliJ IDEA 写代码，Kotlin DSL 的自动补全和错误提示，比 Groovy 强了不止一个档次。你想想看，写 Groovy 脚本时，IDE 基本就是个文本编辑器，全靠你脑子记 API。而 Kotlin DSL 呢？你打个点，所有可用的配置项就列出来了。

从 Groovy 迁移到 Kotlin DSL

迁移其实没那么可怕。Gradle 官方提供了很好的兼容性，你可以逐步迁移，不用一次性全改。

我记得第一次迁移时，我先把一个简单的单模块项目改成了 Kotlin DSL。步骤很简单：

1. 把 build.gradle 重命名为 build.gradle.kts
2. 把 settings.gradle 重命名为 settings.gradle.kts
3. 修改语法，把 Groovy 的写法改成 Kotlin 的写法

这里有个坑，我曾经踩过：settings.gradle.kts 里不能用 include ':app' 这种写法，得改成 include(":app")。Groovy 里括号可以省略，但 Kotlin 不行。

常用写法对比

我整理了一份对照表，把最常用的几种场景列出来。你在迁移时可以直接参考：

场景	Groovy DSL	Kotlin DSL
依赖声明	implementation 'com.squareup.okhttp3:okhttp:4.9.0'	implementation("com.squareup.okhttp3:okhttp:4.9.0")
插件声明	apply plugin: 'com.android.application'	plugins { id("com.android.application") }
仓库配置	mavenCentral()	mavenCentral()（写法相同）
自定义任务	task hello { doLast { println 'Hello' } }	tasks.register("hello") { doLast { println("Hello") } }
扩展属性	ext.compileSdkVersion = 34	val compileSdkVersion by extra(34)
条件判断	if (project.hasProperty('release'))	if (project.hasProperty("release"))

一个完整的迁移示例

来看一个实际的 Android 项目配置。这是 Groovy 版本：

// build.gradle (Groovy)
apply plugin: 'com.android.application'

android {
    compileSdkVersion 34
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 21
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
    }
}

dependencies {
    implementation 'androidx.core:core-ktx:1.12.0'
    implementation 'androidx.appcompat:appcompat:1.6.1'
}

这是迁移后的 Kotlin DSL 版本：

// build.gradle.kts (Kotlin DSL)
plugins {
    id("com.android.application")
}

android {
    compileSdk = 34
    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 21
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.12.0")
    implementation("androidx.appcompat:appcompat:1.6.1")
}

你发现没？Kotlin DSL 里 compileSdkVersion 变成了 compileSdk，minSdkVersion 变成了 minSdk。这是 Gradle 8.0 之后的 API 变更，Groovy 里也能用新写法，但 Kotlin DSL 强制你使用新 API。

Kotlin DSL 的进阶用法

迁移完成后，你会发现 Kotlin DSL 能做很多 Groovy 做不到的事。比如：

• 类型安全的扩展函数——可以自定义 DSL 块，IDE 能自动补全
• 编译时检查——配置错误在编译期就能发现，不用等到运行时
• 更好的重构支持——重命名变量、提取方法，IDE 都能正确处理

我曾经在一个项目里，用 Kotlin DSL 写了一个自定义的版本管理函数：

// 自定义版本管理
fun Project.androidConfig(block: AndroidConfig.() -> Unit) {
    val config = AndroidConfig().apply(block)
    // 应用配置
}

class AndroidConfig {
    var compileSdk: Int = 34
    var minSdk: Int = 21
    var targetSdk: Int = 34
}

// 使用
androidConfig {
    compileSdk = 34
    minSdk = 23
    targetSdk = 34
}

这种写法在 Groovy 里也能实现，但不会有类型检查。你写错了字段名，Groovy 不会报错，直到运行时才会发现。而 Kotlin DSL 在编译期就能告诉你：Unresolved reference: compilSdk。

迁移中的常见问题

我整理了几个迁移时容易踩的坑：

• Gradle 版本要求——Kotlin DSL 需要 Gradle 5.0 以上，建议用 7.0+
• Kotlin 版本兼容——Gradle 内置了 Kotlin 编译器，但版本可能较旧
• 第三方插件兼容性——有些老插件不支持 Kotlin DSL，需要升级
• 多模块项目迁移顺序——建议从最底层的 library 模块开始，逐步向上迁移

知识体系结构图

下面这张图展示了 Kotlin DSL 迁移的核心知识体系：

从这张图可以看出，迁移到 Kotlin DSL 不是简单的语法替换，而是一个涉及多个方面的系统性工作。但只要你掌握了核心优势、迁移步骤和常用写法对比，整个过程就会顺畅很多。

我个人觉得，Kotlin DSL 最大的价值不在于语法本身，而在于它带来的开发体验提升。当你习惯了 IDE 的自动补全和编译时检查，再回头看 Groovy 脚本，会有一种「回不去」的感觉。

好了，这一章的内容就到这里。如果你在迁移过程中遇到什么问题，欢迎随时交流。

---