5分钟上手kaml为Kotlin项目快速接入YAML序列化的完整教程【免费下载链接】kamlYAML support for kotlinx.serialization项目地址: https://gitcode.com/gh_mirrors/ka/kamlkaml 是一个为 Kotlin 生态提供 YAML 序列化的轻量级开源库它直接扩展了 kotlinx.serialization让你的 Kotlin 数据类可以一行代码完成 YAML 的解析与生成。它支持 YAML 1.2 规范涵盖标量、列表、映射、空值、锚点与别名等主流特性非常适合用来处理配置文件、Docker Compose 风格定义等场景。本文面向新手带你 5 分钟内完成 kaml 的接入与上手。⚠️ 温馨提示项目作者已宣布归档维护源码与已发布的构件仍可正常使用社区鼓励维护 fork。学习其设计与用法依然非常有价值。一、kaml 是什么为什么需要 YAML 序列化库Kotlin 的官方序列化方案 kotlinx.serialization 原生支持 JSON但对 YAML 没有官方支持。而 YAML 凭借其可读性强、语法简洁在配置文件领域被广泛使用。kaml 正是填补这一空白的库核心特点特性说明双向序列化既能把 YAML 解析为 Kotlin 对象也能把对象写回 YAML完整类型支持字符串、布尔、整数、浮点、列表、映射、空值多态支持支持 sealed 类与非密封类的多态读写锚点与别名支持 Docker Compose 风格的扩展字段合并平台支持Kotlin/JVM 完整支持Kotlin/JS 与 Wasm 为实验性支持二、快速安装3 步添加 kaml 依赖第 1 步确保项目已启用 Kotlin 序列化插件。第 2 步在 Gradle 构建脚本中添加依赖以 Kotlin DSL 为例plugins { kotlin(jvm) kotlin(plugin.serialization) } dependencies { implementation(com.charleskorn.kaml:kaml:最新版本号) }第 3 步刷新 Gradle即可开始使用。构建与测试可直接使用项目自带的 Gradle Wrapper./gradlew assemble构建、./gradlew check运行测试。三、第一次读取把 YAML 解析成 Kotlin 对象定义一个带Serializable注解的数据类然后调用Yaml.default即可解析Serializable data class Team(val leader: String, val members: ListString) val yaml leader: Amy members: - Bob - Cindy .trimIndent() val team Yaml.default.decodeFromString(Team.serializer(), yaml)核心 API 都集中在 Yaml.kt其中Yaml.default是开箱即用的默认实例decodeFromString负责字符串解析decodeFromSource则支持从 Okio 的Source流式读取。 在 JVM 平台上还可以直接从InputStream读取需 UTF-8 编码相关扩展函数定义在src/jvmMain/kotlin/com/charleskorn/kaml/JvmYamlReading.kt。四、写回 YAML把 Kotlin 对象序列化为文本反过来把一个对象写成 YAML 字符串只需要一行val yaml Yaml.default.encodeToString(Team.serializer(), Team(Amy, listOf(Bob, Cindy)))如果不想要固定的数据结构、而是想自由浏览 YAML 内容可以先解析为YamlNode节点树val node Yaml.default.parseToYamlNode(yaml) // 像访问 JSON 一样逐层取值YamlNode是一个密封类包含YamlScalar、YamlList、YamlMap三种节点源码位于src/commonMain/kotlin/com/charleskorn/kaml/YamlNode.kt。标量节点还提供了toInt()、toFloat()、toBoolean()等便捷转换方法甚至支持十六进制0x与八进制0o字面量。五、进阶技巧用 YamlConfiguration 精细控制行为创建Yaml实例时可以传入YamlConfiguration定制各种行为常用配置项一览strictMode遇到未知字段是否报错默认true解析不受控的配置文件时建议关闭polymorphismStyle多态风格支持TagYAML 标签!type与Propertytype属性两种写法sequenceStyle列表输出为块式多行- item还是流式单行[a, b]anchorsAndAliases默认出于安全考虑禁止锚点别名设为Permitted后并可通过maxAliasCount限制别名数量防止滥用extensionDefinitionPrefix设置x-等前缀后可像 Docker Compose 一样定义顶层扩展字段并用合并codePointLimit限制输入文档大小默认 3MBdecodeEnumCaseInsensitive枚举解码是否忽略大小写完整配置项说明见src/commonMain/kotlin/com/charleskorn/kaml/YamlConfiguration.kt。六、多态支持与错误处理多态对 sealed 类kaml 支持两种风格。Tag风格输出形如!frontend hostname: a.mycompany.comProperty风格则输出type: frontend。配合SerialName注解即可控制写入的类型名。异常体系解析失败时抛出继承自SerializationException的YamlException并携带精确的行号、列号与YamlPath路径信息还派生出DuplicateKeyException重复键、MalformedYamlException格式错误、MissingRequiredPropertyException缺少必填字段等具体类型排错非常方便。源码位于src/commonMain/kotlin/com/charleskorn/kaml/YamlException.kt与src/commonMain/kotlin/com/charleskorn/kaml/YamlPath.kt。自定义注解kaml 还提供YamlComment序列化时在属性前写注释块、YamlSingleLineStringStyle、YamlMultiLineStringStyle等注解可针对单个字段覆盖全局字符串样式定义在src/commonMain/kotlin/com/charleskorn/kaml/Annotations.kt。七、项目结构速览熟悉源码目录后遇到问题可以快速定位核心入口与 APIsrc/commonMain/kotlin/com/charleskorn/kaml/Yaml.kt配置项与风格枚举src/commonMain/kotlin/com/charleskorn/kaml/YamlConfiguration.kt节点树模型src/commonMain/kotlin/com/charleskorn/kaml/YamlNode.kt输入读取解析侧src/commonMain/kotlin/com/charleskorn/kaml/YamlInput.kt、YamlMapInput.kt、YamlListInput.kt输出写入序列化侧src/commonMain/kotlin/com/charleskorn/kaml/YamlOutput.ktJVM 流式读写扩展src/jvmMain/kotlin/com/charleskorn/kaml/JvmYamlReading.kt、JvmYamlWriting.kt测试用例可当示例库看src/commonTest/kotlin/com/charleskorn/kaml/下的YamlReadingTest.kt、YamlWritingTest.kt八、常见问题 FAQQkaml 和直接用 SnakeYAML 手动映射相比有什么区别Akaml 基于 kotlinx.serialization 生态直接对接Serializable注解无需手写映射代码且异常自带行列位置信息。Q非 JVM 平台能用吗AKotlin/JS 与 Wasm 目前为高度实验性支持生产环境建议仅在 Kotlin/JVM 上使用。Q字段名大小写或命名风格对不上怎么办A可通过YamlConfiguration的yamlNamingStrategy设置命名转换策略。总结kaml 用极简的 API 补齐了 Kotlin 生态中 YAML 序列化的短板一个Serializable数据类加上Yaml.default即可完成 YAML 配置文件的双向转换。配合YamlConfiguration的多态、命名策略、锚点别名等能力足以胜任绝大多数配置解析场景。现在就动手把它加入你的 Kotlin 项目让 YAML 处理变得轻松高效吧【免费下载链接】kamlYAML support for kotlinx.serialization项目地址: https://gitcode.com/gh_mirrors/ka/kaml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考