# Kotlin DSL 模式 ## 简介 Kotlin 的语言功能支持创建富有表现力的特定领域语言 (DSL)，感觉像是语言本身的自然扩展。 DSL 提高了代码可读性，减少了样板文件，并为配置、构建器和域建模提供类型安全的 API。支持 DSL 设计的关键功能包括带有接收器的 lambda、扩展函数、中缀表示法、运算符重载和范围控制。这些功能结合起来创建了流畅、直观的 API，可以清楚地表达领域概念，而无需牺牲类型安全或 IDE 支持。该技能涵盖类型安全构建器、lambda 接收器、中缀函数、运算符重载以及在 Android、测试和配置上下文中设计可维护 DSL 的实用模式。 ## 类型安全的构建器类型安全构建器使用带有接收器的 lambda 来创建具有编译时验证和 IDE 支持的分层结构。 // HTML DSL 示例类 HTML { 私有 val 元素 = mutableListOf() 有趣的头（初始化：头。（） - >单位）{ val 头 = 头() head.init() 元素.add(头) } 有趣的身体（初始化：身体。（） - >单位）{ val 主体 = 主体() body.init() 元素.add(body) } 重写 fun toString(): String { 返回“\n${elements.joinToString(“\n”)}\n” } } 抽象类元素（值名称：字符串）{ private val Children = mutableListOf() protected fun initElement(element: T, init: T.() -> Unit): T { 元素.init() 儿童.添加（元素）返回元素 } 重写 fun toString(): String { 返回 if (children.isEmpty()) { “<$名称/>” } 否则{ "<$name>\n${children.joinToString("\n")}\n" } } } 头类：元素（“头”）{ 有趣的标题（文本：字符串）{ initElement(Title()) { this.text = 文本 } } } 类标题：元素（“标题”）{ var 文本：字符串 = "" 重写 fun toString() = "$text" } 类主体：元素（“主体”）{ 有趣的h1（文本：字符串）{ initElement(H1()) { this.text = 文本 } } 有趣的p（文本：字符串）{ initElement(P()) { this.text = 文本 } } fun div(cssClass: String = "", init: Div.() -> Unit) { initElement(Div(cssClass), init) } } H1 类：元素（“h1”）{ var 文本：字符串 = "" 重写 fun toString() = "

$text

" } P 类：元素（“p”）{ var 文本：字符串 = "" 覆盖 fun toString() = "

$text

" } class Div(private val cssClass: String = "") : Element("div") { 有趣的p（文本：字符串）{ initElement(P()) { this.text = 文本 } } 重写 fun toString(): String { val classAttr = if (cssClass.isNotEmpty()) " class=\"$cssClass\"" else "" 返回“...” } } // 使用 HTML DSL 有趣的 buildPage() = html { 头{ title("我的页面") } 身体{ h1(“欢迎”) p("这是一个段落") div(“容器”) { p("嵌套段落") } } } fun html(init: HTML.() -> Unit): HTML { val html = HTML() html.init() 返回 HTML } // 配置DSL 类服务器配置{ 变量端口：Int = 8080 var 主机：字符串=“本地主机” val 路由 = mutableListOf() 有趣的路线（路径：字符串，初始化：路线。（）->单位）{ val 路线 = 路线（路径）路线.init() 路线.添加（路线） } } 类路线（val路径：字符串）{ var 方法: String = "GET" var 处理程序：（请求）-> 响应 = { 响应（200，“确定”）} fun get(处理程序: (请求) -> 响应) { 这个.方法 = "GET" this.handler = 处理程序 } 有趣的帖子（处理程序：（请求）->响应）{ 这个.方法 = "POST" this.handler = 处理程序 } } 数据类请求（val路径：String，val主体：String =“”）数据类响应（val status：Int，val body：String） fun server(init: ServerConfig.() -> Unit): ServerConfig { val 配置 = ServerConfig() 配置.init() 返回配置 } // 使用配置 DSL val配置=服务器{ 端口=9000 主机=“0.0.0.0” 路线（“/ api /用户”）{ 获取{请求-> 响应（200，“用户列表”） } } 路线（“/ api /帖子”）{ 发布{请求-> 响应（201，“帖子已创建”） } } } 类型安全构建器提供 IDE 自动完成和编译时验证，同时创建可读的分层结构。 ## 带有接收器的 Lambda 表达式带有接收器的 Lambda 使 DSL 函数能够直接访问接收器属性和方法，从而为更简洁的 API 创建隐式上下文。 // 带有接收器基础知识的 Lambda fun buildString(action: StringBuilder.() -> Unit): String { val 构建器 = StringBuilder() 构建器.action() 返回 builder.toString() } val 结果 = buildString { 附加（“你好”）附加（“”）附加（“世界”） } // 作为 DSL 构建器的扩展函数类查询{ 私有 val 条件 = mutableListOf() 有趣的地方（条件：字符串）{ 条件.add(条件) } 有趣的构建（）：字符串{ 返回 "SELECT * WHERE ${conditions.joinToString(" AND ")}" } } 有趣的查询（初始化：查询。（）->单位）：字符串{ val 查询 = 查询() 查询.init() 返回查询.build() } val sql = 查询 { 其中(“年龄 > 18”) 其中（“状态 = '活动'”） } // 作用域构建器类 TestSuite(val 名称: String) { 私有 val 测试 = mutableListOf() 有趣的测试（名称：字符串，块：TestContext.（）->单元）{ val 上下文 = TestContext() 上下文.block() 测试.add（测试（名称，上下文）） } 有趣的跑步（）{ println("正在运行的套件：$name") 测试.forEach { it.run() } } } 类测试上下文{ val 断言 = mutableListOf<() -> Unit>() 有趣的断言Equals（预期：任何，实际：任何）{ 断言.add { 如果（预期！=实际）{ throw AssertionError("预期为 $expected，但得到了 $actual") } } } } 类测试（val名称：字符串，val上下文：TestContext）{ 有趣的跑步（）{ println("测试：$name") context.assertions.forEach { it() } } } fun suite(名称: String, init: TestSuite.() -> Unit): TestSuite { val suite = TestSuite(名称) 套件.init() 返回套房 } // 使用测试 DSL val testSuite = suite("数学测试") { 测试（“加法”）{ 断言等于(4, 2 + 2) 断言等于(0, 1 - 1) } 测试（“乘法”）{ 断言等于(6, 2 * 3) } } // 适用于 DSL 链接数据类人（变量名称：字符串=“”，变量年龄：Int = 0， var 电子邮件：字符串 = "" ）有趣的 createPerson() = Person().apply { 名称=“爱丽丝” 年龄 = 30 电子邮件=“alice@example.com” } // 用于范围访问有趣的 processConfig(配置：ServerConfig) { 与（配置）{ println("服务器位于 $host:$port") 路线.forEach { 路线 -> println(" ${route.method} ${route.path}") } } } 带有接收器的 Lambda 允许在没有显式限定符的情况下访问接收器成员，从而创建自然的、上下文感知的 DSL 语法。 ## 中缀函数和运算符中缀函数和运算符重载可在 DSL 中实现自然的数学和逻辑表达式，从而提高领域概念的可读性。 // 流畅 API 的中缀函数中缀乐趣 String.shouldEqual(预期：字符串) { 如果（这！=预期）{ 抛出断言错误（“预期'$expected'但得到'$this'”） } } “你好”应该等于“你好” // 带中缀的 DSL 持续时间类持续时间（val毫秒：长）{ 运算符 fun plus(其他: 持续时间) = 持续时间（毫秒 + 其他毫秒）覆盖 fun toString() = "${milliseconds}ms" } infix fun Int.seconds(unit: Unit) = Duration(this * 1000L) infix fun Int.分钟(单位：单位) = 持续时间(本 * 60 * 1000L) 对象单位 val 超时 = 5 秒单位验证间隔 = 2 分钟单位 // 查询带中缀的 DSL 类条件（val 字段：字符串，val 运算符：字符串，val 值：任意） infix fun String.eq(value: Any) = Condition(this, "=, value) infix fun String.gt(value: Any) = Condition(this, ">", value) infix fun String.lt(value: Any) = Condition(this, "<", value) 类查询生成器{ 私有 val 条件 = mutableListOf() 有趣的地方（条件：条件）{ 条件.add(条件) } infix fun Condition.and(other: Condition): List { 返回列表（这个，其他） } 有趣的构建（）：字符串{ 返回“WHERE ${conditions.joinToString（”AND“）{ “${it.field} ${it.operator} ${it.value}” }}" } } 有趣的 queryBuilder(init: QueryBuilder.() -> Unit): String { val 构建器 = QueryBuilder() 构建器.init() 返回 builder.build() } val query1 = queryBuilder { 其中（“年龄”gt 18）其中（“状态”eq“活动”） } // DSL 的运算符重载数据类 Vector(val x: Double, val y: Double) { 运算符 fun plus(其他：向量) = 向量(x + other.x, y + other.y) 运算符乐趣时间（标量：Double）= 向量（x * 标量，y * 标量）运算符 fun unaryMinus() = 向量（-x，-y） } val v1 = 向量(1.0, 2.0) val v2 = 向量(3.0, 4.0) 值 v3 = v1 + v2 值 v4 = v1 * 2.0 值 v5 = -v1 // 为类似函数的对象调用运算符路由器类{ 私有 val 路由 = mutableMapOf Response>() 运算符乐趣调用（路径：字符串，处理程序：（请求）->响应）{ 路线[路径] = 处理程序 } 有趣的句柄（请求：请求）：响应{ 返回路由[request.path]?.invoke(request) ？：响应（404，“未找到”） } } val 路由器 = 路由器() 路由器（“/用户”）{ 请求 - > 响应（200，“用户”） } // 类似地图 DSL 的获取/设置运算符类配置{ 私有 val 值 = mutableMapOf() Operator fun get(key: String): 有吗？ = 值[键] 运算符 fun set(键：字符串，值：任意) { 值[键] = 值 } } val config1 = 配置() 配置1[“超时”] = 5000 val timeout1 = config1["超时"] 中缀函数删除了二元运算的括号和点，而运算符重载则在 DSL 中实现了自然的数学符号。 ## 使用@DslMarker 进行范围控制 DslMarker 注释可防止来自外部作用域的隐式接收者，通过在编译时捕获意外嵌套错误来提高 DSL 安全性。 // 问题：没有 @DslMarker 的隐式接收器类表（值名称：字符串）{ val columns = mutableListOf() 有趣的列（名称：字符串，初始化：Column.（）->单位）{ val 列 = 列（名称）列.init() columns.add(列) } } 类列（值名称：字符串）{ var 类型：String = "VARCHAR" var 可空：布尔值 = true 有趣的列（名称：字符串，初始化：Column.（）->单位）{ // 意外地从外部作用域访问 } } // 如果没有@DslMarker，这可以编译但错误有趣的问题DSL（）=表（“用户”）{ 列（“id”）{ 类型=“INT” // 这意外地调用了外部 Table.column，而不是内部列（“嵌套”）{ 类型=“文本” } } } // 解决方案：@DslMarker注解 @DslMarker 注释类DatabaseDsl @DatabaseDsl 类 SafeTable(val 名称: String) { val columns = mutableListOf() 有趣的列（名称：字符串，初始化：SafeColumn.（）->单位）{ val 列 = SafeColumn(名称) 列.init() columns.add(列) } } @DatabaseDsl 类 SafeColumn(val 名称: String) { var 类型：String = "VARCHAR" var 可空：布尔值 = true } // 现在这不会编译 - @DslMarker 阻止隐式外部接收器有趣的 safeDSL() = SafeTable(“用户”) { 列（“id”）{ 类型=“INT” // column("nested") { } // 编译错误！ } } // 不同域的自定义 DSL 标记 @DslMarker 注释类 HtmlDsl @DslMarker 注释类TestDsl @HtmlDsl 类 SafeHTML { fun body(init: SafeBody.() -> Unit) { SafeBody().init() } } @HtmlDsl 类安全体{ 有趣的p（文本：字符串）{} } @TestDsl 类 SafeTestSuite { 有趣的测试（名称：字符串，块：SafeTestContext.（）->单元）{ SafeTestContext().block() } } @TestDsl 类 SafeTestContext { fun assertEquals(预期：任何，实际：任何) {} } // 多个 DSL 标记可防止混合有趣的混合DSLs() { 安全HTML { 身体{ // 此处无法访问测试 DSL } } 安全测试套件{ 测试（“示例”）{ // 此处无法访问 HTML DSL } } } DslMarker 可防止混淆跨 DSL 边界的隐式接收器访问，从而使 DSL 更安全且更易于维护。 ## Gradle Kotlin DSL 模式 Gradle 的 Kotlin DSL 演示了用于构建配置、依赖项管理和任务定义的真实 DSL 模式。 // 构建脚本 DSL 模式插件{ kotlin（“jvm”）版本“1.9.0” id（“应用程序”） } 存储库{ mavenCentral() 谷歌() } 依赖项{ 实现（“org.jetbrains.kotlinx：kotlinx-coroutines-core：1.7.0”） testImplementation("org.junit.jupiter:junit-jupiter:5.9.0") } // 使用 DSL 自定义任务抽象类 CustomTask : DefaultTask() { @get:输入抽象 val 消息：Property @任务动作有趣的执行（）{ println(消息.get()) } } 任务{ 注册<自定义任务>（“问候”）{ message.set("来自自定义任务的问候") } } // 特定于域配置的扩展函数有趣的 Project.configureKotlin() { 科特林{ jvm工具链(17) } } 有趣的项目.configureTesting() { tasks.withType<测试> { 使用JUnitPlatform() } } // 带有 DSL 的约定插件抽象类 MyPluginExtension { 抽象 val 版本：Property 启用抽象值：Property 初始化{ 版本.约定(“1.0.0”) 启用.约定(true) } } 类 MyPlugin : 插件<项目> { 覆盖乐趣应用（项目：项目）{ val 扩展 = project.extensions.create( “我的插件”， MyPluginExtension::class.java ）项目.tasks.register（“printConfig”）{ 做最后{ println("版本：${extension.version.get()}") println("启用：${extension.enabled.get()}") } } } } // 使用插件 DSL 配置 { 版本.set("2.0.0") 启用.设置（真） } // 类型安全访问器 valcompileKotlin：Kotlin按任务编译编译Kotlin.kotlinOptions { jvmTarget = “17” freeCompilerArgs = listOf("-Xjsr305=strict") } // 多平台 DSL 科特林{ 虚拟机{ withJava() } js(IR) { 浏览器() 节点js() } 源集{ val commonMain 通过获取 { 依赖项{ 实现（“org.jetbrains.kotlinx：kotlinx-coroutines-core：1.7.0”） } } val commonTest 通过获取 { 依赖项{ 实现（kotlin（“测试”）） } } } } Gradle Kotlin DSL 结合了多种 DSL 模式，通过出色的 IDE 支持创建富有表现力、类型安全的构建配置。 ## 用于 Web 应用程序的 Ktor DSL Ktor 演示了 Web 应用程序中用于路由、序列化和服务器配置的 DSL 模式。 // Ktor 应用程序 DSL 有趣的应用程序.module() { 安装（内容协商）{ json(Json { 漂亮打印 = true 宽松 = true }) } 路由{ 获取（“/”）{ call.respondText("你好，世界！") } 获取（“/用户/ {id}”）{ val id = call.parameters["id"] call.respond(User(id?.toInt() ?: 0, "用户 $id")) } 帖子（“/用户”）{ val user = call.receive<用户>() call.respond(HttpStatusCode.Created, 用户) } 路线（“/api”）{ 获取（“/健康”）{ call.respondText("确定") } 验证（“auth-jwt”）{ 获取（“/受保护”）{ call.respondText("受保护的路线") } } } } } // 自定义 Ktor DSL 扩展有趣的 Route.userRoutes() { 路线（“/用户”）{ 得到{ call.respond(listOf(User(1, "Alice"), User(2, "Bob"))) } 获取（“/ {id}”）{ val id = call.parameters["id"]?.toInt() ?: return@get call.respond( HttpStatusCode.BadRequest ） call.respond(User(id, "用户 $id")) } } } // 类型安全的路由 DSL 内联乐趣 Route.typedGet( 路径：字符串，跨内联处理程序：挂起 PipelineContext.(T) -> Unit ）{ 获取（路径）{ val params = call.receive() 处理程序（参数） } } 数据类 UserQuery(val name: String, val minAge: Int) 有趣的 Route.typedRoutes() { typedGet("/search") { 查询 -> call.respondText("正在搜索${query.name}，年龄 >= ${query.minAge}") } } Ktor 的 DSL 提供可读的声明性服务器配置，同时保持类型安全性和可组合性。 ## 最佳实践 1. **使用 @DslMarker 通过限制隐式接收器并在编译时捕获不正确的嵌套来防止范围混淆** 2. **将 DSL 范围集中**在单个域上，以保持清晰度并防止在一个 DSL 中混合不相关的概念 3. **在 DSL 构建器中提供合理的默认设置**，以减少样板文件，同时允许在需要时进行自定义 4. **利用 lambda 和接收器** 实现上下文感知 DSL 语法，无需限定符即可直接访问成员 5. **谨慎使用中缀函数**仅适用于自然二元运算，例如比较、逻辑运算符或域关系 6. **通过示例记录 DSL 使用情况**，以显示预期模式并防止滥用灵活的 DSL API 7. **在构建时而不是运行时验证 DSL 结构**，以便及早发现错误并清除编译错误 8. **尽可能使 DSL 不可变**以防止意外修改并实现更安全的并发使用 9. **提供DSL和非DSL API**，让用户在表达性和显性之间进行选择 10. **广泛测试 DSL 使用模式**，以确保直观的行为并捕获复杂嵌套场景中的边缘情况 ## 常见陷阱 1. **过度使用中缀函数**进行不适当的操作会使代码在没有明确约定的情况下更难以阅读和理解 2. **创建过于复杂的 DSL** 尝试做太多事情会导致 API 混乱，难以学习和维护 3. **忘记@DslMarker注释**允许来自外部作用域的隐式接收器，导致嵌套DSL结构中的微妙错误 4. **不验证DSL结构**允许无效配置通过编译并在运行时失败 5. **在没有保护的情况下使用可变 DSL 构建器**会导致不安全的并发修改和意外行为 6. **在没有清晰结构的情况下创建深度嵌套的 DSL** 会变得难以导航和推理 7. **重载过多的运算符**会掩盖意图并使代码变得神秘而不是富有表现力 8. **混合 DSL 和命令式代码**会不一致地造成在何处使用哪种样式的混乱 9. **不提供清晰的 DSL 边界**使得 DSL 上下文在代码中何时开始和结束变得不清楚 10. **忽略 IDE 支持影响** 创建的 DSL 不能与自动完成或重构工具很好地配合 ## 何时使用此技能在构建受益于可读、类型安全的域特定语法的库、框架或配置系统时，请使用 Kotlin DSL 模式。将类型安全构建器应用于分层结构，例如 HTML 生成、UI 布局或结构重要的嵌套配置树。对具有自然二元运算（例如比较、测量或逻辑关系）的域概念使用中缀函数和运算符。将 lambda 与测试框架、构建脚本或任何 API 的接收器结合使用，其中特定于上下文的操作可提高可读性。在构建复杂的嵌套 DSL 时使用 @DslMarker 可以防止范围混淆并在编译时而不是运行时捕获错误。 ## 资源 * [Kotlin DSL 文档]() * [Gradle Kotlin DSL 入门]() * [Ktor 文档]() * [Effective Kotlin：DSL 设计]() * [类型安全构建器示例]()

Kotlin DSL 模式

包含技能