用途
本技能用于在 Kotlin 中构建流畅、类型安全的 DSL(领域特定语言)。其核心是「带接收者的 lambda」(lambda with receiver),让调用方能够写出形如 html { head { title("hi") } } 的代码,同时由编译器强制约束每个代码块内合法的调用。
何时使用
- 配置以「配方」形式表达比构造函数参数更易读的场景:Gradle 构建脚本、Compose UI 树、Ktor 路由。
- 能从结构化形态中获益的领域特定构造(HTML、SVG、查询构建器)。
- 可读性重要的测试夹具与种子数据。
何时不使用
- 使用具名参数加默认值同样清晰时——DSL 会增加学习成本,只有当结构化形态确实有帮助时才采用。
- 所谓「DSL」只有一层深度、没有嵌套作用域——那只是一个带构建器参数的函数,并不是真正的 DSL。
- 正在设计的语法复杂到值得使用真正的解析器——DSL 只会隐藏复杂度而非解决它。
核心内容
带接收者的 lambda
当函数的最后一个参数类型为 T.() -> Unit 时,T 的方法与属性会如同处于 T 内部一样可用:
fun html(block: HtmlBuilder.() -> Unit): Html {
val b = HtmlBuilder()
b.block() // inside `block`, methods of HtmlBuilder are in scope
return b.build()
}
在 html { … } 内部,this 是 HtmlBuilder,因此 head、body、div 等方法都是非限定调用。
嵌套
每个构建器方法接收自己的带接收者 lambda,从而在其内部创建有类型的作用域:
fun HtmlBuilder.body(block: BodyBuilder.() -> Unit) {
val b = BodyBuilder()
b.block()
bodies.add(b.build())
}
DSL 的语法由类型系统捕获——head 在 html { } 内合法,但在 body { } 内不合法。
@DslMarker——防止作用域泄漏
没有 @DslMarker 时,嵌套 DSL 会隐式允许访问外层作用域,可能引发令人困惑的 bug(「为什么在 body 里 title 也能用?」)。用 @DslMarker 注解标注构建器,可让编译器把每个作用域限制在自己的接收者上:
@DslMarker
annotation class HtmlDsl
@HtmlDsl class HtmlBuilder { ... }
@HtmlDsl class HeadBuilder { ... }
@HtmlDsl class BodyBuilder { ... }
这样在 body { … } 内就无法误调用 head 的方法——编译器强制要求非限定调用的隐式接收者必须是最近的 @HtmlDsl 作用域。
构建 → 返回 → 使用
构建器通常在内部累积状态,并在最后产出不可变结果(build() 返回完成的树)。DSL 在块内可变,在块外不可变。
class HtmlBuilder {
private val children = mutableListOf<Element>()
fun head(block: HeadBuilder.() -> Unit) { children.add(HeadBuilder().apply(block).build()) }
fun body(block: BodyBuilder.() -> Unit) { children.add(BodyBuilder().apply(block).build()) }
fun build(): Html = Html(children.toList())
}
决策要点
- 当语法具有结构(嵌套作用域、带规则的序列)且调用方会频繁使用、足以学会其惯用法时,DSL 才划算。
- 始终使用 @DslMarker 防止作用域意外泄漏。
- 让 build() 的结果不可变;DSL 在块内可变、块外冻结。
- 拥有 30 个构建器类型的 DSL 属于过度设计;从 2–4 层开始。
反模式
- 没有 @DslMarker 的 DSL——外层作用域泄漏进内层,可在 body 内调用 html 的方法,导致难以察觉的 bug。
- 实为流畅 setter 链(builder.foo().bar().build())的「DSL」——没有嵌套作用域、没有类型安全语法,应改用具名参数。
- 构建器持有结果并在多次调用间复用的 DSL——会产生陈旧状态与并发 bug。
- 在构建块中带有副作用(日志、IO)的 DSL——会让构造过程变得不可预测。
参见
- gof-builder——经典 Builder;DSL 构建器是其在 Kotlin 中的惯用特化。
- kp-higher-order-functions——带接收者的 lambda 是其基础。
- gof-kotlin-idioms——其 Builder 章节展示了一个小型 DSL 示例。
参考资料
- Kotlin Design Patterns and Best Practices(Alexey Soshin),第 5 章(Introducing Functional Programming)与第 9 章(Idioms and Anti-Patterns),涉及 @DslMarker 的讨论。
- Kotlin 语言文档——type-safe builders。