kaml快速开始：data class与YAML双向转换，4个实战例子讲清核心用法

kaml快速开始：data class与YAML双向转换，4个实战例子讲清核心用法

【免费下载链接】kamlYAML support for kotlinx.serialization项目地址: https://gitcode.com/gh_mirrors/ka/kaml

kaml 是一个为 Kotlin 生态提供 YAML 支持的开源库，它为 kotlinx.serialization 补上了 YAML 序列化这块拼图。借助 kaml，你可以用一行代码把 YAML 文本解析成 data class，也能把 data class 直接输出为规范的 YAML 1.2 文档，是处理配置文件、CI 定义等场景的轻量好工具。

为什么需要 kaml？

Kotlin 的序列化框架 kotlinx.serialization 原生支持 JSON，但 YAML 在配置文件中依然无处不在。手写解析代码又累又容易出错，而 kaml 帮你做到了：

• ✅双向转换：YAML → Kotlin 对象（反序列化）、Kotlin 对象 → YAML（序列化）
• ✅完整支持 YAML 1.2：标量、列表、映射、空值、锚点与别名、合并键
• ✅类型安全：直接绑定到带@Serializable注解的 data class
• ✅错误定位清晰：解析出错时，异常会带上具体的行号和列号

核心入口就是 Yaml 类，它实现了 kotlinx.serialization 的StringFormat接口，用起来和你熟悉的 Json 格式几乎一样。

准备工作：引入依赖只需两行

在 Gradle 构建脚本中，先启用 Kotlin 序列化插件，再加入 kaml 依赖（Kotlin DSL 写法）：

plugins { kotlin("jvm") version "1.4.20" kotlin("plugin.serialization") version "1.4.20" } dependencies { implementation("com.charleskorn.kaml:kaml:<版本号>") }

⚠️ 注意：kaml 目前只完全支持 Kotlin/JVM，JS 和 Native 目标仍处于实验阶段。另外项目已归档停止维护，源码和已发布的构件仍可用，生产使用前请留意这一点。

实战例子1：把 YAML 字符串解析为 data class

这是最高频的用法。先定义一个@Serializable数据类，再用decodeFromString一步完成解析：

@Serializable data class Team( val leader: String, val members: List<String> ) val input = """ leader: Amy members: - Bob - Cindy - Dan """.trimIndent() val result = Yaml.default.decodeFromString(Team.serializer(), input) println(result) // Team(leader=Amy, members=[Bob, Cindy, Dan])

如果 YAML 写错了怎么办？kaml 抛出的YamlException（见 YamlException.kt）会明确告诉你出错位置，比如缺少必填字段、遇到未知属性、值类型不匹配，都附带了path、line、column信息，排查问题非常快。

实战例子2：把 data class 输出为 YAML 字符串

反向操作同样简单，调用encodeToString即可：

val team = Team("Amy", listOf("Bob", "Cindy", "Dan")) val yamlText = Yaml.default.encodeToString(Team.serializer(), team) println(yamlText) // leader: "Amy" // members: // - "Bob" // - "Cindy" // - "Dan"

生成的 YAML 默认使用 2 空格缩进、双引号包裹字符串、80 列自动换行，格式规范且对人类友好。JVM 平台上还支持通过encodeToSink直接写入文件流，适合生成配置文件的大文件场景。

实战例子3：不想建类？直接解析为 YamlNode

有时候文档结构不固定，或者只想取某一个字段，没必要提前定义整个数据类。kaml 支持把 YAML 解析成树形结构YamlNode，按需取值：

val node = Yaml.default.parseToYamlNode(input) println( node.yamlMap .get<YamlList>("members")!![1] .yamlScalar .content ) // Cindy

YamlNode分为三种形态：YamlScalar（标量）、YamlList（列表）、YamlMap（映射），你可以像遍历普通集合一样逐层读取。而且拿到节点后，还可以随时用decodeFromYamlNode把它转成某个 data class，灵活度拉满。节点模型定义在 YamlNode.kt。

实战例子4：自定义配置——命名策略与宽松模式

真实世界的配置文件风格各异，kaml 通过YamlConfiguration提供了一组可调参数（定义在 YamlConfiguration.kt），常用的有两个：

val yaml = Yaml( configuration = YamlConfiguration( yamlNamingStrategy = YamlNamingStrategy.SnakeCase, // 字段名按 snake_case 匹配 strictMode = false, // 忽略未知属性 ) ) val config = yaml.decodeFromString(GitRepoConfig.serializer(), """ repo_name: kaml star_count: 4000 some_new_field: ignored """.trimIndent())

命名策略的四种实现位于 YamlNamingStrategy.kt，例如设为SnakeCase后，serialName字段就能自动匹配 YAML 里的serial_name键。

进阶能力一览

掌握上面 4 个例子后，你可以按需探索 kaml 的更多特性：

• 🔀多态支持：sealed 类与未封装类型都支持，可用!<type>标签或type属性两种风格声明子类型
• 🔗锚点、别名与合并：支持 Docker Compose 风格的x-扩展字段与<<:合并
• 💬注释注解：用@YamlComment在输出 YAML 的字段前添加注释行
• 📐排版控制：缩进宽度、字符串换行长度、列表块状/流式风格均可配置

更多用法可参考项目自带的完整测试用例，比如读取场景的 YamlReadingTest.kt 和写出场景的 YamlWritingTest.kt，覆盖了标量、列表、空值、多态等几乎所有边界情况。

总结

kaml 的 API 与 kotlinx.serialization 保持了高度一致，如果你已经熟悉 JSON 序列化，学习成本几乎为零。4 个例子跑通之后，YAML 配置文件对你来说就只是一份普通的 Kotlin 对象而已。

【免费下载链接】kamlYAML support for kotlinx.serialization项目地址: https://gitcode.com/gh_mirrors/ka/kaml