kaml多态实战指南sealed class 的 YAML 标签与 type 字段两种风格详解【免费下载链接】kamlYAML support for kotlinx.serialization项目地址: https://gitcode.com/gh_mirrors/ka/kamlkaml 是为 kotlinx.serialization 提供 YAML 支持的开源库。本文以最常见的 sealed class 多子类场景为例完整讲解 kaml 多态的两种风格——YAML 标签Tag与 type 字段Property它们如何配置、YAML 长什么样、又该如何选型新手可直接当速查手册使用。为什么多态需要类型标记配置文件里经常出现一列里混着几种对象的情况。比如服务清单里既有前端节点、又有后端节点Kotlin 中通常用 sealed class 建模Serializable sealed class Server { SerialName(frontend) Serializable data class Frontend(val hostname: String) : Server() SerialName(backend) Serializable data class Backend(val database: String) : Server() }⚠️ 注意SerialName它决定了序列化到 YAML 中出现的类型名frontend/backend两种多态风格都依赖它拼错就会解析失败。反序列化时kaml 必须知道每个节点该还原成哪个子类——这就是多态类型标记的作用。kaml 提供了两种写法通过YamlConfiguration.polymorphismStyle切换枚举定义在 YamlConfiguration.kt 中的PolymorphismStyleTag / Property / None。两种风格一览30 秒对比对比维度️ Tag 标签风格 Property 字段风格配置方式polymorphismStyle PolymorphismStyle.TagpolymorphismStyle PolymorphismStyle.Property是否默认✅Yaml.default默认即是❌ 需显式配置YAML 形态!frontend写在对象前type: frontend作为普通字段字段名固定YAML 标签语法可自定义默认type值必须是对象否是否则抛异常典型场景与标准 YAML 1.2 工具链互通人类手编配置、字段名有业务含义风格一YAML 标签Tag默认推荐Yaml.default开箱即用无需任何配置序列化后输出servers: - !frontend hostname: a.mycompany.com - !backend database: db-1️ 标签紧跟在-之后用!引导类型信息独立于对象属性之外不占字段位。解析时 kaml 在 YamlInput.kt 中识别YamlTaggedNode节点并据此选择子类反序列化器标签本身不会进入数据模型。风格二type 字段Property当你希望类型信息长得像普通属性方便人工编辑或跨语言读取时切换到 Property 风格val yaml Yaml( configuration YamlConfiguration( polymorphismStyle PolymorphismStyle.Property ) )序列化输出变为servers: - type: frontend hostname: a.mycompany.com - type: backend database: db-1三个实用要点字段名可自定义设置polymorphismPropertyName kind后输出即变成kind: backend避免与业务字段type撞名。读入时自动剥离解析后type字段会被 kaml 剔除不会出现在模型里逻辑见 YamlPolymorphicInput.kt。值必须是映射对象若多态值被序列化为标量如纯字符串会抛出IllegalStateException: Cannot serialize a polymorphic value that is not a YAML object...此时建议改用 Tag 风格。新手常见报错排查清单所有相关异常定义在 YamlException.kt报错原因解决方法MissingTypeTagException配置为 Tag 风格但 YAML 里没有标签给节点加!类型名或改用 Property 风格UnknownPolymorphicTypeException类型名未注册检查SerialName拼写非 sealed 类型需在SerializersModule中注册MissingRequiredPropertyException: typeProperty 风格下缺少 type 字段在 YAML 中补上该字段IllegalStateExceptionCannot serialize...Property 风格写入了非对象值调整模型结构或切换 Tag 风格 遇到UnknownPolymorphicTypeException时不必慌异常信息会列出所有已知类型名对照它即可快速定位拼写错误。如何选型给新手的快速建议优先默认Tag零配置且标签是 YAML 1.2 标准特性与主流 YAML 工具兼容性最好。配置文件给人手写 → Propertytype: backend比!backend更直观配合polymorphismPropertyName还能规避字段冲突。与 Jackson 等 JSON 生态互通 → Propertytype字段是 Jackson 多态的惯例写法跨语言团队更易理解。相关源码与测试文件想深入原理可按以下路径阅读风格枚举与配置项src/commonMain/kotlin/com/charleskorn/kaml/YamlConfiguration.kt读写入口Yaml类src/commonMain/kotlin/com/charleskorn/kaml/Yaml.kt反序列化分派逻辑src/commonMain/kotlin/com/charleskorn/kaml/YamlInput.kt序列化输出逻辑src/commonMain/kotlin/com/charleskorn/kaml/YamlOutput.kt类型名解析与未知类型处理src/commonMain/kotlin/com/charleskorn/kaml/YamlPolymorphicInput.kt官方测试用例含两种风格的完整输入输出对照src/commonTest/kotlin/com/charleskorn/kaml/YamlWritingTest.kt、src/commonTest/kotlin/com/charleskorn/kaml/YamlReadingTest.kt小结kaml 的多态支持本质上只做一件事把 sealed class 的子类信息写进 YAML、再准确地读回来。Tag 风格零配置、标准兼容Property 风格可读性强、字段名可定制二者切换只需一行配置。掌握SerialName与PolymorphismStyle这两个核心概念多态配置基本不会踩坑。 补充说明kaml 项目目前已归档不再活跃维护但源码与已发布的构建产物仍可正常使用多态等核心功能稳定可靠。【免费下载链接】kamlYAML support for kotlinx.serialization项目地址: https://gitcode.com/gh_mirrors/ka/kaml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
kaml多态实战指南：sealed class 的 YAML 标签与 type 字段两种风格详解
kaml多态实战指南sealed class 的 YAML 标签与 type 字段两种风格详解【免费下载链接】kamlYAML support for kotlinx.serialization项目地址: https://gitcode.com/gh_mirrors/ka/kamlkaml 是为 kotlinx.serialization 提供 YAML 支持的开源库。本文以最常见的 sealed class 多子类场景为例完整讲解 kaml 多态的两种风格——YAML 标签Tag与 type 字段Property它们如何配置、YAML 长什么样、又该如何选型新手可直接当速查手册使用。为什么多态需要类型标记配置文件里经常出现一列里混着几种对象的情况。比如服务清单里既有前端节点、又有后端节点Kotlin 中通常用 sealed class 建模Serializable sealed class Server { SerialName(frontend) Serializable data class Frontend(val hostname: String) : Server() SerialName(backend) Serializable data class Backend(val database: String) : Server() }⚠️ 注意SerialName它决定了序列化到 YAML 中出现的类型名frontend/backend两种多态风格都依赖它拼错就会解析失败。反序列化时kaml 必须知道每个节点该还原成哪个子类——这就是多态类型标记的作用。kaml 提供了两种写法通过YamlConfiguration.polymorphismStyle切换枚举定义在 YamlConfiguration.kt 中的PolymorphismStyleTag / Property / None。两种风格一览30 秒对比对比维度️ Tag 标签风格 Property 字段风格配置方式polymorphismStyle PolymorphismStyle.TagpolymorphismStyle PolymorphismStyle.Property是否默认✅Yaml.default默认即是❌ 需显式配置YAML 形态!frontend写在对象前type: frontend作为普通字段字段名固定YAML 标签语法可自定义默认type值必须是对象否是否则抛异常典型场景与标准 YAML 1.2 工具链互通人类手编配置、字段名有业务含义风格一YAML 标签Tag默认推荐Yaml.default开箱即用无需任何配置序列化后输出servers: - !frontend hostname: a.mycompany.com - !backend database: db-1️ 标签紧跟在-之后用!引导类型信息独立于对象属性之外不占字段位。解析时 kaml 在 YamlInput.kt 中识别YamlTaggedNode节点并据此选择子类反序列化器标签本身不会进入数据模型。风格二type 字段Property当你希望类型信息长得像普通属性方便人工编辑或跨语言读取时切换到 Property 风格val yaml Yaml( configuration YamlConfiguration( polymorphismStyle PolymorphismStyle.Property ) )序列化输出变为servers: - type: frontend hostname: a.mycompany.com - type: backend database: db-1三个实用要点字段名可自定义设置polymorphismPropertyName kind后输出即变成kind: backend避免与业务字段type撞名。读入时自动剥离解析后type字段会被 kaml 剔除不会出现在模型里逻辑见 YamlPolymorphicInput.kt。值必须是映射对象若多态值被序列化为标量如纯字符串会抛出IllegalStateException: Cannot serialize a polymorphic value that is not a YAML object...此时建议改用 Tag 风格。新手常见报错排查清单所有相关异常定义在 YamlException.kt报错原因解决方法MissingTypeTagException配置为 Tag 风格但 YAML 里没有标签给节点加!类型名或改用 Property 风格UnknownPolymorphicTypeException类型名未注册检查SerialName拼写非 sealed 类型需在SerializersModule中注册MissingRequiredPropertyException: typeProperty 风格下缺少 type 字段在 YAML 中补上该字段IllegalStateExceptionCannot serialize...Property 风格写入了非对象值调整模型结构或切换 Tag 风格 遇到UnknownPolymorphicTypeException时不必慌异常信息会列出所有已知类型名对照它即可快速定位拼写错误。如何选型给新手的快速建议优先默认Tag零配置且标签是 YAML 1.2 标准特性与主流 YAML 工具兼容性最好。配置文件给人手写 → Propertytype: backend比!backend更直观配合polymorphismPropertyName还能规避字段冲突。与 Jackson 等 JSON 生态互通 → Propertytype字段是 Jackson 多态的惯例写法跨语言团队更易理解。相关源码与测试文件想深入原理可按以下路径阅读风格枚举与配置项src/commonMain/kotlin/com/charleskorn/kaml/YamlConfiguration.kt读写入口Yaml类src/commonMain/kotlin/com/charleskorn/kaml/Yaml.kt反序列化分派逻辑src/commonMain/kotlin/com/charleskorn/kaml/YamlInput.kt序列化输出逻辑src/commonMain/kotlin/com/charleskorn/kaml/YamlOutput.kt类型名解析与未知类型处理src/commonMain/kotlin/com/charleskorn/kaml/YamlPolymorphicInput.kt官方测试用例含两种风格的完整输入输出对照src/commonTest/kotlin/com/charleskorn/kaml/YamlWritingTest.kt、src/commonTest/kotlin/com/charleskorn/kaml/YamlReadingTest.kt小结kaml 的多态支持本质上只做一件事把 sealed class 的子类信息写进 YAML、再准确地读回来。Tag 风格零配置、标准兼容Property 风格可读性强、字段名可定制二者切换只需一行配置。掌握SerialName与PolymorphismStyle这两个核心概念多态配置基本不会踩坑。 补充说明kaml 项目目前已归档不再活跃维护但源码与已发布的构建产物仍可正常使用多态等核心功能稳定可靠。【免费下载链接】kamlYAML support for kotlinx.serialization项目地址: https://gitcode.com/gh_mirrors/ka/kaml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考