第10章配置与扩展

课程目录第10章配置与扩展

10、配置与扩展：Extension对象、NamedDomainObjectContainer、DSL扩展

说实话，Gradle 的 DSL 之所以能这么灵活，核心就靠三个东西：Extension 对象、NamedDomainObjectContainer，还有 DSL 扩展机制。我刚开始接触 Kotlin DSL 时，觉得这玩意儿挺玄乎的。后来在项目里写插件，才真正体会到——没有扩展，你的构建脚本就是一潭死水。

今天我们就来把这几个概念彻底讲透。你想想看，一个构建工具如果只能执行固定任务，那跟写死脚本有什么区别？真正的灵活性，来自于让用户能自定义配置、注册领域对象、甚至扩展 DSL 本身。

10.1 Extension 对象：插件的配置入口

Extension 说白了就是插件的「配置面板」。你写一个插件，总得让用户能传参数吧？比如设置输出目录、开关某个功能。Extension 就是干这个的。

在 Kotlin DSL 里，定义一个 Extension 非常简单：

// 定义一个 Extension 类
open class MyPluginExtension {
    var outputDir: String = "build/output"
    var enableLogging: Boolean = false
    val servers = mutableListOf<String>()
}

然后在插件里注册它：

class MyPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        val extension = project.extensions.create(
            "myPlugin",
            MyPluginExtension::class.java
        )
        // 后续可以用 extension 读取配置
    }
}

用户在使用时，就可以这样写：

myPlugin {
    outputDir = "dist"
    enableLogging = true
    servers.add("prod-server-01")
}

关键点：Extension 的类必须有一个无参构造器，或者用 open 修饰。Kotlin 默认类是 final 的，Gradle 的代理机制需要能创建子类。

我在项目中遇到过一个问题：Extension 的属性如果用了 val 而不是 var，用户赋值时会直接报错。嗯，这个坑我踩过两次才记住。

10.2 NamedDomainObjectContainer：管理一组命名对象

这个家伙有点意思。它本质上是一个容器，里面每个对象都有一个唯一的名字。你想想看，Gradle 里的 dependencies、repositories、configurations 都是这种模式。

举个例子，假设你要让用户配置多个数据源：

// 定义领域对象
open class DataSource(val name: String) {
    var url: String = ""
    var username: String = ""
    var password: String = ""
}

// 在插件中创建容器
val dataSources = project.container(DataSource::class.java)
project.extensions.add("dataSources", dataSources)

用户脚本里就可以这样写：

dataSources {
    mysql {
        url = "jdbc:mysql://localhost:3306/db"
        username = "root"
        password = "secret"
    }
    redis {
        url = "redis://localhost:6379"
    }
}

为什么用 NamedDomainObjectContainer？因为它自动帮你处理了命名冲突、延迟创建、DSL 闭包等一堆脏活。我自己写插件时，只要遇到「一组有名字的配置项」，第一反应就是用容器。

小技巧：容器里的对象默认是 open 的，因为 Gradle 需要代理。如果你用 Kotlin 的 data class，记得改成普通类。

10.3 DSL 扩展：让脚本像自然语言

DSL 扩展是 Gradle 最骚的操作。它让你能写出 myPlugin { ... } 这种看起来像内置语法的代码。背后的原理其实不复杂——就是 Kotlin 的扩展函数 + 接收者作用域。

看个例子：

// 定义一个扩展函数
fun Project.myPlugin(configure: MyPluginExtension.() -> Unit) {
    val extension = extensions.getByType(MyPluginExtension::class.java)
    extension.configure()
}

这样用户就能直接写 myPlugin { ... } 了。注意看参数类型：MyPluginExtension.() -> Unit，这是一个带接收者的 lambda。说白了，就是在闭包内部，this 指向了 Extension 实例，所以可以直接访问它的属性。

我建议你把 DSL 扩展和 Extension 对象配合使用。一个负责定义数据结构，一个负责提供语法糖。这样代码既清晰又优雅。

曾经踩过的坑：我曾经在扩展函数里直接 create 了一个新的 Extension，结果每次调用都会创建一个新实例，之前的配置全丢了。正确的做法是用 getByType 获取已有的实例。

10.4 三者如何协同工作

光讲概念太干，我们画个图看看它们的关系：

从图上能看出来，插件是总指挥。它负责创建 Extension 和容器，然后通过 DSL 扩展函数暴露给用户。用户脚本里写的每一行配置，最终都会映射到这些对象上。

10.5 实战：写一个完整的配置扩展

光说不练假把式。我们写一个完整的例子，把上面三个概念串起来。

假设我们要做一个部署插件，让用户配置多个部署环境：

// 1. 定义领域对象
open class DeploymentEnvironment(val name: String) {
    var host: String = ""
    var port: Int = 8080
    var username: String = ""
    var password: String = ""
}

// 2. 定义 Extension
open class DeployExtension {
    val environments = mutableListOf<DeploymentEnvironment>()
    var defaultEnv: String = "dev"
}

// 3. 实现插件
class DeployPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        // 创建容器
        val envContainer = project.container(DeploymentEnvironment::class.java)
        // 注册 Extension
        val extension = project.extensions.create("deploy", DeployExtension::class.java)
        // 把容器也暴露出去
        project.extensions.add("environments", envContainer)
    }
}

// 4. DSL 扩展函数
fun Project.deploy(configure: DeployExtension.() -> Unit) {
    val ext = extensions.getByType(DeployExtension::class.java)
    ext.configure()
}

fun NamedDomainObjectContainer<DeploymentEnvironment>.production(configure: DeploymentEnvironment.() -> Unit) {
    val env = maybeCreate("production")
    env.configure()
}

用户脚本里就可以这样写：

deploy {
    defaultEnv = "staging"
    environments {
        production {
            host = "prod.example.com"
            port = 443
        }
        staging {
            host = "staging.example.com"
        }
    }
}

个人习惯：我一般会把 DSL 扩展函数单独放在一个文件里，比如 DslExtensions.kt。这样插件主体代码不会被这些语法糖污染，维护起来也清爽。

10.6 常见陷阱与最佳实践

陷阱	说明	解决方案
Extension 类不是 open	Gradle 需要创建代理子类，Kotlin 默认 final 会报错	用 `open class` 或 `abstract class`
容器对象用 data class	data class 是 final 的，且 component 函数会干扰代理	改用普通 `open class`
多次调用 create 导致覆盖	每次调用 `extensions.create` 会创建新实例	用 `getByType` 获取已有实例
DSL 闭包内 this 指向混乱	带接收者的 lambda 容易搞混作用域	明确标注 `this@xxx` 或使用 `apply`

我曾经在一个项目里，因为忘了给 Extension 类加 open，结果 Gradle 在运行时直接抛了个 CannotCreateProxyException。排查了半天才发现是 Kotlin 的 final 特性在作怪。嗯，从那以后我写 Extension 的第一行就是 open class。

10.7 总结

Extension 对象、NamedDomainObjectContainer、DSL 扩展，这三者构成了 Gradle Kotlin DSL 的配置骨架。Extension 负责单一配置块，容器负责管理一组命名对象，DSL 扩展则提供了优雅的语法糖。

你写插件时，可以这样思考：

如果用户只需要配置一个东西 → 用 Extension
如果用户需要配置多个同类东西 → 用 NamedDomainObjectContainer
如果想让脚本写起来更自然 → 加 DSL 扩展函数

记住，好的 DSL 设计，是让用户觉得「这语法就像 Gradle 自带的」。而不是让用户翻着文档猜你定义的闭包到底接收什么参数。

📚 课程目录

10、配置与扩展：Extension对象、NamedDomainObjectContainer、DSL扩展

10.1 Extension 对象：插件的配置入口

10.2 NamedDomainObjectContainer：管理一组命名对象

10.3 DSL 扩展：让脚本像自然语言

10.4 三者如何协同工作

10.5 实战：写一个完整的配置扩展

10.6 常见陷阱与最佳实践

10.7 总结