Kotlin Academy · 课时

在不破坏用户代码的情况下测试和演进 DSL

Q: 「在不破坏用户代码的情况下测试和演进 DSL」这节课中我会学到什么？

设计稳定的 DSL API，并使用可读的断言代码块对其进行测试。 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

设计稳定的 DSL API，并使用可读的断言代码块对其进行测试。

第 4 / 4 课13 个步骤

在不破坏用户代码的情况下测试和演进 DSL 是 CoddyKit 上的免费 Kotlin Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Kotlin Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Kotlin Academy 课程共包含 4 节课。

DSL 测试为何不同

DSL 是公共 API。对它的修改可能会破坏用户代码中的每个调用位置。测试 DSL 意味着既要验证它生成的输出，也要验证它强制实施的结构，包括确保无效构造仍然会导致编译错误。

测试 DSL 输出

最简单的测试方式是：使用 DSL 构建一个对象，然后对渲染结果或构建器的内部状态进行断言。

@Test
fun `div contains a paragraph`() {
    val result = html {
        body {
            div { p("Hi") }
        }
    }
    assertTrue(result.render().contains("<p>"))
}

测试构建器状态

不要测试渲染后的字符串，而是直接测试构建器对象图。这样能更好地适应格式变化：

@Test
fun `server config has correct port`() {
    val cfg = server {
        host = "example.com"
        port = 9090
    }
    assertEquals(9090, cfg.port)
    assertEquals("example.com", cfg.host)
}

测试嵌套结构

遍历对象树，验证嵌套关系：

@Test
fun `body contains one div`() {
    val page = html { body { div { } } }
    assertEquals(1, page.children
        .filterIsInstance<Body>().first()
        .children.filterIsInstance<Div>().size
    )
}

编译错误测试

您无法直接对编译错误进行单元测试，但可以添加类似 // This should NOT compile 的注释，并将无法通过编译的代码注释掉。有些项目会使用 Kotlin Compile Testing 库来断言某些代码无法通过编译。

安全演进 DSL：添加式变更

添加带默认值的新可选参数或新的构建器函数，都是向后兼容的。现有调用位置无需修改即可通过编译。

// Before
fun server(block: ServerConfig.() -> Unit): ServerConfig
// After — additive: new optional feature
fun server(enableMetrics: Boolean = false, block: ServerConfig.() -> Unit): ServerConfig

破坏性变更：移除或重命名

移除或重命名 DSL 函数会破坏调用位置。如果必须重命名，请提供一个已弃用的别名，并在未来的主版本中移除它：

@Deprecated("Use database{} instead", ReplaceWith("database(block)"))
fun db(block: DbConfig.() -> Unit) = database(block)

为 DSL 进行版本管理

对于库中的 DSL，请遵循语义化版本控制。破坏性的 DSL 变更（移除函数或更改接收者类型）应当升级主版本号。请在变更日志中记录这些变更。

使用 @RequiresOptIn 标记实验性 DSL 特性

使用 @RequiresOptIn 标记不稳定的 DSL 扩展。用户必须显式选择加入，从而避免无意中依赖可能发生变化的特性：

@RequiresOptIn(message = "This DSL feature is experimental and may change")
annotation class ExperimentalDsl

@ExperimentalDsl
fun ServerConfig.enableDebug() { /*...*/ }

DSL 中的属性委托

DSL 可以使用属性委托来强制要求必要字段，并在缺少必需值时提供清晰的错误消息：

class Required<T> {
    private var value: T? = null
    operator fun getValue(t: Any?, p: KProperty<*>): T = value ?: error("${p.name} is required")
    operator fun setValue(t: Any?, p: KProperty<*>, v: T) { value = v }
}

跨版本契约测试

将一组“基准”DSL 使用片段作为测试保留下来。如果重构破坏了它们，测试套件会在用户发现问题之前捕获问题。这些片段也可以作为持续更新的文档。

快速检查

对于向后兼容性而言，哪种 DSL 变更最安全？

在交互式课程中回答

回顾：测试和演进 DSL

关键要点：

在单元测试中测试 DSL 输出和构建器对象状态
添加式变更（新增可选函数或参数）是安全的
使用 @Deprecated(ReplaceWith=...) 重命名，同时避免破坏用户代码
使用 @RequiresOptIn 标记实验性 DSL 特性
保留基准用法测试，以捕获跨版本回归

免费开始

用 AI 导师学习 Kotlin — 免费

在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。

课程: 51
课程: 203

免费开始学习查看完整课程

常见问题解答

「在不破坏用户代码的情况下测试和演进 DSL」课时是免费的吗？

是的 — 「在不破坏用户代码的情况下测试和演进 DSL」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Kotlin Academy 课程的其余内容，请升级到 CoddyKit PRO。 Kotlin Academy 课程共包含 4 节课。

「在不破坏用户代码的情况下测试和演进 DSL」这节课中我会学到什么？

设计稳定的 DSL API，并使用可读的断言代码块对其进行测试。你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Kotlin Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Kotlin Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「在不破坏用户代码的情况下测试和演进 DSL」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Kotlin Academy 课中编写并运行代码吗？

能。每节 Kotlin Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Kotlin Academy