3. 项目环境搭建：添加DataStore依赖、配置Gradle版本、迁移前备份策略

项目环境搭建是实施 DataStore 改造的第一步，也是最容易被忽略的环节。错误的依赖声明或 Gradle 版本不匹配会导致编译失败；缺失迁移备份策略则可能在生产环境中丢失用户数据。本章从依赖引入、版本锁定、备份三个维度给出可落地的操作方案。

3.1 添加 DataStore 依赖

DataStore 官方提供两个变体：Preferences DataStore（轻量键值对）和 Proto DataStore（带 Schema 的类型安全存储）。根据项目需求选择其一，或同时引入。

在模块级 build.gradle（kts 或 groovy）中添加依赖：

// build.gradle.kts (模块级)
dependencies {
    // Preferences DataStore
    implementation("androidx.datastore:datastore-preferences:1.1.1")
    
    // Proto DataStore + Protobuf
    implementation("androidx.datastore:datastore:1.1.1")
    implementation("com.google.protobuf:protobuf-javalite:3.25.3")
}

3.2 配置 Gradle 版本与插件

DataStore 1.1.x 系列需要满足以下最低版本要求，否则可能出现无法解析或运行时异常。

在项目级 build.gradle.kts 声明正确的 Gradle 版本：

// build.gradle.kts (项目级)
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:8.2.2")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22")
    }
}

// gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip

3.3 迁移前备份策略

替换 SharedPreferences 时，必须确保旧数据在新存储初始化完成前被完整保留。推荐采用 “复制并标记” 策略：

1. 在首次启动迁移时，将 SharedPreferences 中的全部键值对复制到 DataStore。
2. 复制完成后，在 DataStore 中写入一个标记键（如 migrated_to_datastore）。
3. 此后每次启动检查该标记：若存在则跳过迁移；若不存在则再次执行备份复制。
4. 旧 SharedPreferences 文件保留至少两个版本周期，确认无回滚后再删除。

备份实现核心代码片段：

// BackupManager.kt
suspend fun backupSharedPrefs(
    context: Context,
    dataStore: DataStore<Preferences>
) {
    val prefs = context.getSharedPreferences("my_prefs", Context.MODE_PRIVATE)
    val migratedKey = booleanPreferencesKey("migrated_to_datastore")

    val alreadyMigrated = dataStore.data.first()[migratedKey] ?: false
    if (alreadyMigrated) return

    // 复制所有键值对
    prefs.all.forEach { (key, value) ->
        when (value) {
            is String -> dataStore.edit { it[stringPreferencesKey(key)] = value }
            is Int -> dataStore.edit { it[intPreferencesKey(key)] = value }
            is Boolean -> dataStore.edit { it[booleanPreferencesKey(key)] = value }
            is Float -> dataStore.edit { it[floatPreferencesKey(key)] = value }
            is Long -> dataStore.edit { it[longPreferencesKey(key)] = value }
            is Set<*> -> dataStore.edit {
                it[stringSetPreferencesKey(key)] = value as Set<String>
            }
        }
    }

    // 写入迁移标记
    dataStore.edit { it[migratedKey] = true }
}

3.4 环境搭建流程总览

3.5 常见错误与解决

3.6 部署前检查清单

• Gradle 同步成功：无红色波浪线，依赖解析正确。
• 备分代码已注入 Application 或 LauncherActivity：确保在首次访问 DataStore 前执行。
• 迁移标记持久化验证：手动卸载 App 重装后迁移不会重复执行（需配合encryptedSharedPreferences 或云端备份策略）。
• 回滚预案：在旧 SharedPreferences 文件未被删除前，一旦 DataStore 出现崩溃可快速切回旧方案。