KStore 版本迁移完整教程Migration 让旧数据无缝升级【免费下载链接】KStoreA tiny Kotlin multiplatform library that assists in saving and restoring objects to and from disk using kotlinx.coroutines, kotlinx.serialisation and kotlinx.io项目地址: https://gitcode.com/gh_mirrors/ks/KStoreKStore 是一款 Kotlin 多平台对象持久化库其内置的Migration 版本迁移机制可以在你升级数据模型时把磁盘上的旧数据无缝升级到新结构——无需手动读写文件也不会因字段不匹配而崩溃。本教程面向新手用 3 步讲清 KStore 数据迁移的完整用法。为什么需要 KStore 版本迁移应用迭代时数据模型总会变加字段、改类型、重命名。对磁盘上已存在的旧 JSON 文件来说这意味着反序列化直接失败轻则数据丢失重则应用崩溃。KStore 的解决方案是版本化存储每个 Store 声明一个version读取时若发现文件结构与当前模型不匹配就自动调用你提供的迁移函数把旧数据转换成新模型——整个过程对业务代码透明。核心实现位于 KVersionedStore.kt。KStore 迁移机制2 个文件 1 次自动升级启用版本化后KStore 会在数据文件旁边额外维护一个.version后缀的版本文件数据文件如pets.json存放序列化后的对象版本文件如pets.json.version记录数据当前版本号临时文件.temp后缀写入时先写临时文件再原子替换防止中途崩溃留下半截数据迁移触发流程非常直接按当前模型解码数据文件若解码失败读取版本文件拿到旧版本号调用你的Migration函数migration(旧版本, 旧数据JSON)返回新模型对象并在下次写入时落盘为新版本值得注意迁移是惰性的——读取时即时转换不强制立即重写磁盘老版本文件保留到下一次set才升级。快速上手一行代码开启版本管理如果新模型只是新增带默认值的字段甚至不需要写迁移逻辑——Kotlinx Serialization 会自动用默认值补齐缺失字段Serializable data class CatV1(val name: String, val lives: Int 9) Serializable data class CatV2(val name: String, val lives: Int 9, val age: Int 9 - lives) // 仅需声明 versionKStore 自动把 V1 旧数据按默认值读成 V2 val storeV2: KStoreCatV2 storeOf(file file, version 2)更进一步新字段如果能从旧字段推导如上例age 9 - lives连默认值都不用手动猜推导表达式本身就是默认值。这类二进制兼容的升级成本几乎为零。自定义 Migration字段改名怎么办️当变更是二进制不兼容的字段改名、类型变更就必须提供迁移函数。Migration就是一个简单的函数类型typealias MigrationT (version: Int?, JsonElement?) - T?version旧数据的版本号无版本文件时为 0jsonElement旧数据的原始 JSON可从中按需取字段返回值迁移后的新模型返回null表示放弃回退到 Store 的默认值以字段重命名 类型变更为例cuteness: Int→isCute: Boolean完整写法见 KVersionedStoreTests.ktval storeV3: KStoreCatV3 storeOf(file file, version 3) { version, json - when (version) { 1 - json?.jsonObject?.let { val name it[name]!!.jsonPrimitive.content val lives it[lives]!!.jsonPrimitive.int CatV3(name, lives, 9 - lives, it[cuteness]!!.jsonPrimitive.int 1) } else - null } }跨多个版本也只需一步到位when分支里按旧版本号分别处理V1 旧数据可直接迁移到 V3无需逐级接力。迁移避坑指南4 条实用经验向下读会返回 null用 V3 的数据去读 V2 的 Store 时迁移函数没有对应分支结果为null而非异常。KStore 不做降级只支持向前升级。文件损坏不会崩溃空文件、截断写入、版本文件损坏等情况读取一律安全降级为null且下一次set会自动修复存储保证应用始终可用。版本号未知时走兜底分支若版本文件丢失但数据完好version无法确认务必在when中写else - null或返回默认值兜底避免抛异常。写入是事务化的KStore 先写新数据、再更新版本文件。即使两次写入之间崩溃磁盘上仍是旧版本 旧数据的一致状态不会出现版本与数据错配。延伸资料官方版本化文档含完整 Cat 示例using-versioning.md版本化 Store 源码KVersionedStore.kt端到端迁移测试V0→V4 全场景KVersionedStoreTests.kt掌握version声明 Migration函数两件事你的 KStore 数据就能随应用版本平滑演进旧用户的存量数据一条都不少。【免费下载链接】KStoreA tiny Kotlin multiplatform library that assists in saving and restoring objects to and from disk using kotlinx.coroutines, kotlinx.serialisation and kotlinx.io项目地址: https://gitcode.com/gh_mirrors/ks/KStore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考