SuperAPI AI 工具集

kp-type-safe-builders

编程与开发

查看项目

更新于 10-16 16:26

技能介绍

用途

本技能用于在 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。