如何在Android Jetpack DataStore中执行版本升级迁移操作

一、同DataStore存储迁移的实现逻辑 #

实现DataStore自身版本升级（含key变更、值格式转换、废弃字段清理等场景），核心是在创建DataStore时传入自定义的DataMigration接口实现，三个核心方法的作用和实现逻辑如下：

• shouldMigrate：判断是否需要触发迁移，通用方案是在DataStore中维护一个专属的版本号标记key，本地存储的版本低于目标版本时返回true即可
• migrate：执行实际迁移逻辑的方法，可通过把当前Preferences转为可编辑的MutablePreferences完成key重命名、值转换、字段删除等操作，最终返回迁移后的新数据对象
• cleanUp：迁移完成后的清理回调，无特殊临时资源清理需求可直接空实现

以下是key变更场景的实际实现示例：

// 定义版本号与业务key
val DATA_VERSION = intPreferencesKey("data_store_version")
const val TARGET_VERSION = 2
val OLD_USER_ID = stringPreferencesKey("old_user_id")
val NEW_USER_ID = stringPreferencesKey("new_user_id")

PreferenceDataStoreFactory.create(
    migrations = listOf(
        object : DataMigration<Preferences> {
            override suspend fun cleanUp() {
                // 无清理需求可留空
            }

            override suspend fun migrate(currentData: Preferences): Preferences {
                val currentVersion = currentData[DATA_VERSION] ?: 1
                val mutablePrefs = currentData.toMutablePreferences()
                
                // 逐版本迭代升级，后续新版本升级可直接新增判断分支
                if (currentVersion < 2) {
                    // 处理key变更：旧key值赋值给新key后删除旧key
                    currentData[OLD_USER_ID]?.let { oldId ->
                        mutablePrefs[NEW_USER_ID] = oldId
                        mutablePrefs.remove(OLD_USER_ID)
                    }
                    // 更新存储版本号
                    mutablePrefs[DATA_VERSION] = 2
                }
                return mutablePrefs
            }

            override suspend fun shouldMigrate(currentData: Preferences): Boolean {
                return (currentData[DATA_VERSION] ?: 1) < TARGET_VERSION
            }
        }
    ),
    produceFile = {
        context.preferencesDataStoreFile("app_global_preferences")
    }
)

二、规范实现参考渠道 #

• AndroidX DataStore官方源码的单元测试用例：开源库的测试目录下覆盖了单迁移、多迁移串行、异常回滚等各类场景的标准实现，是最权威的参考来源
• Jetpack官方issue反馈区：Google工程师会在相关功能issue中给出各类业务场景的迁移实现样例，也可参考其他开发者提交的落地实现
• 对外开源的商业化Android项目：很多已经上线的大型APP开源了自身的DataStore封装逻辑，包含成熟的版本迁移实现可以参考

内容的提问来源于stack exchange，提问作者Stylianos Gakis