DSL

是什么，为什么存在

Kotlin 内部 领域特定语言（domain-specific language，DSL） 是一组普通 Kotlin 声明，调用时看起来像针对某个领域的小语言。它没有独立解析器，也没有绕过 Kotlin 语法。配置文件、测试描述、界面树和路由表都常用这种 API，因为调用方更关心领域结构，而不是对象创建顺序。

「内部」表示 DSL 仍由 Kotlin 编译器解析和检查。与 SQL 这类外部 DSL 不同，内部 DSL 只能使用宿主语言允许的词法结构，却能直接复用 Kotlin 的类型、控制流、变量和 IDE 导航。这种取舍适合由 Kotlin 开发者维护、需要与应用代码紧密交互的 API。

DSL 解决的是调用表面的噪音，而不是替代领域模型。server { port = 8443 } 比一串临时对象和 setter 更集中，但它背后仍需要明确的数据类型、默认值、校验和所有权规则。若这些规则没有进入类型或构建边界，语法再像自然语言也不会自动安全。

你会在 Gradle Kotlin DSL、Jetpack Compose 和 Ktor 等 API 中遇到相似形式。不过，尾随 lambda 或链式调用本身不等于 DSL。只有当一组操作形成受约束的领域词汇，并且读者能从调用结构看出意图时，这个名字才有用。

一个可维护的内部 DSL 通常分成两个层次：

• 调用表面使用领域名称，并隐藏暂时状态的装配过程。
• 构建器保存尚未完成的可变状态，最终结果则尽量使用明确、稳定的类型。
• 类型签名限制当前步骤能够执行的操作，运行期校验补上无法静态表达的规则。
• 错误信息指向调用者给出的值，而不是暴露构建器内部实现。

工作原理

核心类型是 带接收者的 lambda（lambda with receiver） 。函数类型 ServerBuilder.() -> Unit 表示这段函数值以 ServerBuilder 为接收者，不接收额外参数，并返回 Unit。lambda 内的 this 指向构建器，因此可以省略 this. 直接访问它的成员。

接收者不是编译器临时发明的全局上下文。函数值仍可以写成 block(builder) 或 builder.block() 来调用，接收者在概念上相当于一个显式的首参数。普通 lambda 类型与带接收者的函数类型在适用位置还能互相转换，但显式写出接收者类型会让 DSL 的作用域边界更清楚。

Kotlin 允许把最后一个函数参数写到圆括号外，所以 server(block = { ... }) 可以写成 server { ... }。构建入口通常创建一个新构建器，执行 lambda，然后调用 build()。这三个阶段分别决定初始状态、允许的配置操作和最终结果。

一次构建调用可以按下面的顺序理解：

1. 入口函数创建一个只属于本次调用的构建器。
2. 接收者 lambda 修改构建器中的暂时状态。
3. build() 检查跨字段约束，并复制仍由构建器拥有的可变集合。
4. 入口函数向调用方返回结果，不再暴露构建器。

扩展函数、扩展属性、中缀函数和操作符重载可以补充 DSL 的词汇，但都不是必需条件。先用普通成员函数设计可发现的 API，再为确实符合领域含义的操作选择特殊语法。若 a shouldBe b 的含义一眼可见，中缀形式有价值；若操作符需要注释才能解释，普通函数名通常更稳妥。

嵌套构建器会同时引入多个隐式接收者。未加限制时，内层 lambda 可能调用外层接收者的成员，代码能够编译，却构造出不符合层级的结果。用 @DslMarker 标注的注解把相关接收者归入同一个 DSL；同一作用域中，最靠近的接收者保留隐式访问资格，外层接收者必须显式限定。

DSL 标记（DSL marker） 只影响编译期的隐式接收者解析。它不会验证端口范围，不会阻止空字符串，也不会把构建结果变成不可变对象。这些仍是领域类型与构建边界的责任。

示例

下面四个程序逐步增加约束。每个程序都是独立文件，并已使用 Kotlin 2.4.10 编译器编译，在 JRE 21 上运行；输出块来自实际执行。

从接收者 lambda 到稳定结果

第一个构建器只公开领域所需的配置操作。调用方看不到内部的可变 features，而 build() 返回列表副本，使之后对构建器的修改不会改变既有结果。

server 的最后一个参数是函数类型，所以调用处能使用尾随 lambda。apply(block) 在 ServerBuilder 实例上执行配置并返回同一个实例，随后 build() 完成校验和结果转换。

这里的 List<String> 是只读接口，不等同于任意来源的深度不可变集合。真正隔离结果的是 features.toList()：构建器保留自己的 MutableList，结果拿到新的列表结构。列表元素是不可变字符串，因此这个边界已经足够。

用 @DslMarker 限制嵌套作用域

第二个程序把服务与数据库构建器标记为同一个 DSL。数据库块中的 name 本来会命中外层 ServiceBuilder；加上标记后，未限定的访问会被编译器拒绝。

@DslMarker
annotation class ConfigDsl

@ConfigDsl
class ServiceBuilder {
    var name: String = "unnamed"
    private var database: String = "none"

    fun database(block: DatabaseBuilder.() -> Unit) {
        database = DatabaseBuilder().apply(block).build()
    }

    fun build(): String = "$name -> $database"
}

@ConfigDsl
class DatabaseBuilder {
    var url: String = ""
    var poolSize: Int = 4

    fun build(): String = "$url (pool=$poolSize)"
}

fun service(block: ServiceBuilder.() -> Unit): String =
    ServiceBuilder().apply(block).build()

fun main() {
    val config = service {
        name = "catalog"
        database {
            url = "jdbc:postgresql://db/catalog"
            poolSize = 12
            // name = "wrong" 会被拒绝：外层接收者已隐藏。
            this@service.name = "catalog-api"
        }
    }

    println(config)
}

catalog-api -> jdbc:postgresql://db/catalog (pool=12)

this@service 使用调用产生的隐式标签，明确选择外层接收者，所以仍可修改服务名称。标记的目标是消除意外访问，而不是彻底禁止层级之间的协作；需要跨层时，显式限定会把这项选择留在审查视线内。

实际 DSL 应让同一语言中的所有接收者类型都带上同一个标记。若漏标了一个中间类型，进入该类型的 lambda 后，外层成员可能再次进入隐式候选集，保护就会出现缺口。

用阶段类型表达必填顺序

有些约束不适合放进一个装满可空属性的构建器。创建端点时，路径和处理器都不可缺少；让每一步返回不同类型，调用方就无法在缺少处理器时得到 Endpoint。

data class Endpoint(
    val path: String,
    val handler: () -> String,
)

class PathStage {
    fun path(value: String): HandlerStage {
        require(value.startsWith("/")) { "path must start with /" }
        return HandlerStage(value)
    }
}

class HandlerStage(private val path: String) {
    fun handle(block: () -> String): Endpoint = Endpoint(path, block)
}

fun endpoint(): PathStage = PathStage()

fun main() {
    val health = endpoint()
        .path("/health")
        .handle { "ok" }

    println("${health.path} -> ${health.handler()}")
}

/health -> ok

这是 类型安全构建器（type-safe builder） 的另一种形式。PathStage 没有 build()，HandlerStage 也不能重新选择路径；类型签名把合法顺序写进了自动补全和编译错误。

阶段类型不应为每个可选字段制造一个类型。它最适合少量、稳定且顺序明确的必填步骤。端口范围仍取决于运行时数值，所以前一个示例使用 require 更直接。

显式选择外层接收者

同名成员最容易暴露接收者解析规则。下面的内层 name 属于 ItemBuilder，外层名称只能通过 this@menu 取得。

@DslMarker
annotation class MenuDsl

@MenuDsl
class MenuBuilder {
    var name: String = "unnamed"

    fun item(block: ItemBuilder.() -> Unit) {
        val item = ItemBuilder().apply(block)
        println("$name/${item.name}")
    }
}

@MenuDsl
class ItemBuilder {
    var name: String = "unnamed"
}

fun menu(block: MenuBuilder.() -> Unit) {
    MenuBuilder().apply(block)
}

fun main() {
    menu {
        name = "admin"
        item {
            name = "users"
            println("inner=$name")
            println("outer=${this@menu.name}")
        }
    }
}

inner=users
outer=admin
admin/users

未限定的 name 总是选择最近的可用隐式接收者。this@menu 不是字符串查找，也不是运行期反射；标签在源码中确定具体接收者，编译器据此解析属性访问。

如果跨层访问频繁到每个块都有多个 this@...，问题通常不在标签语法。构建器的职责可能重叠，应把跨层操作提升为内层构建器的显式参数或方法。

陷阱

修复方法： 盘点每个接收者 lambda 的接收者类型，并让属于同一 DSL 的类型共享一个标记。再添加负向编译测试，证明不合法的嵌套调用确实无法通过编译。

修复方法： 在结果边界复制由构建器拥有的集合，并判断元素本身是否也可变。更简单的规则是构建完成后不再暴露或复用构建器。

修复方法： 对少量固定步骤使用构造参数或阶段类型；必须运行期检查时，用 requireNotNull 给出领域化消息。不要用虚假的默认值掩盖缺失配置。

修复方法： 只有领域已经普遍接受该符号或双操作数短语时才使用特殊语法。复杂表达式加括号；只要存在歧义，就退回带名称和圆括号的普通函数。

修复方法： 在输出层使用该领域的编码器或参数绑定 API，并把原始文本与已验证值建模为不同类型。安全边界应有恶意输入测试，不能靠 DSL 的外观推断。

延伸阅读

以下链接指向 Kotlin 官方文档的源文件；它们避免了文档站在本地检查环境中的超时，并保留可审查的原始内容。

类型安全构建器页面解释 DSL 标记；其余页面分别覆盖接收者函数类型、尾随与中缀调用，以及限定的 this。

• Kotlin 类型安全构建器（官方文档源码）
• Kotlin 高阶函数与 lambda（官方文档源码）
• Kotlin 函数与中缀调用（官方文档源码）
• Kotlin this 表达式与限定接收者（官方文档源码）