1. DataStore与SharedPreferences对比：类型安全优势、异步API、协程集成、数据迁移痛点

在Android本地轻量级数据持久化方案中，SharedPreferences（SP）长期占据主导地位，但其设计缺陷在大型项目中逐渐暴露：缺乏类型安全、同步阻塞I/O、不支持协程、数据迁移困难。Jetpack DataStore作为替代方案，从架构层面解决了这些问题。本章从四个维度进行深度对比，并给出选择建议。

1.1 核心差异总览

1.2 类型安全优势

SharedPreferences所有值均以Object存储，读取时必须手动转换类型。一旦键名拼写错误或类型不匹配，运行时才会抛出ClassCastException。

// SharedPreferences – 类型不安全
val prefs = context.getSharedPreferences("user", Context.MODE_PRIVATE)
val age = prefs.getInt("age", 0)          // 正确
val name = prefs.getString("name", "")     // 正确
// 若误将"age"存为String，读取Int时会崩溃
prefs.edit().putString("age", "25").apply()
val crash = prefs.getInt("age", 0)         // ClassCastException!

DataStore通过Protocol Buffers定义schema，每个字段有明确类型，编译时即检查。访问生成的Java/Kotlin类确保类型安全。

// Proto 定义 (user.proto)
message UserPreferences {
    int32 age = 1;
    string name = 2;
}

// DataStore – 类型安全
val userPrefs = context.dataStore.data.map { it.age }
// 编译时保证age为Int，无需手动转换
// 如果proto中age定义改为int64，编译器直接报错

1.3 异步API与协程集成

SharedPreferences的commit()同步写磁盘会阻塞调用线程；apply()虽异步写但无法取消、无法感知完成。DataStore所有读写都是异步：读返回Flow，写通过suspend函数或edit闭包内执行事务。

// SharedPreferences – 阻塞风险
prefs.edit().putString("key", "value").commit()   // 卡UI线程
prefs.edit().putString("key", "value").apply()     // 不可取消，无回调

// DataStore – 协程安全
lifecycleScope.launch {
    context.dataStore.edit { settings ->
        settings[MY_KEY] = "value"   // 自动挂起，不阻塞
    }
}
// 读取实时反应
context.dataStore.data.collect { prefs ->
    // 自动收到最新值
}

1.4 数据迁移痛点

SharedPreferences的迁移通常需要：

1. 定义版本号（通常用常量或SharedPreferences内保存版本）
2. 手动读取旧键值、转换类型、写入新键
3. 处理并发读写冲突
4. 长期维护容易遗漏迁移逻辑

DataStore内置迁移框架，支持从SharedPreferences迁移，也可定义自定义迁移步骤。迁移器在首次创建DataStore时顺序执行，保证数据一致性。

// 从SharedPreferences迁移到DataStore
val dataStore = context.dataStore(
    fileName = "user_preferences.pb",
    migrations = listOf(
        SharedPreferencesMigration(context, "user_shared_prefs")
    )
)

// 自定义迁移（例如重新组织键结构）
object MyMigration : DataMigration<UserPreferences> {
    override suspend fun shouldMigrate(currentData: UserPreferences): Boolean {
        return currentData.hasOldVersionField()
    }
    override suspend fun migrate(currentData: UserPreferences): UserPreferences {
        return currentData.toBuilder()
            .setNewField(currentData.oldField)
            .clearOldField()
            .build()
    }
}

1.5 对比图：架构与数据流

1.6 迁移决策要点

• 新项目：直接使用DataStore（偏好型或Proto型），无需考虑SharedPreferences。
• 存量项目：通过SharedPreferencesMigration逐步替换，建议在版本迭代中先迁移读路径，再迁移写路径。
• 数据量级：键值小于100、简单场景仍可保留SharedPreferences，但需注意类型安全及协程问题。
• 调试：DataStore支持dataStore.data.first()（阻塞获取快照）在测试中快速验证，生产环境推荐使用Flow。