1. 迁移动机分析

迁移至 DataStore 并非追逐技术时髦，而是 SharedPreferences 在复杂业务场景下暴露的系统性问题。本章节通过痛点分析、优势对比、性能数据三个维度，量化迁移动机。

1.1 SharedPreferences 四大痛点

1.2 DataStore 五大核心优势

• 异步 API 全链路：基于 Kotlin Flow 和协程，所有读写操作均在 Dispatchers.IO 执行，主线程零阻塞。
• 事务性写入：写操作在 DataStore 内部使用事务（transactions），写入中途崩溃自动回滚，数据保持一致。
• 类型安全：Preferences DataStore 通过 Preferences.Key<T> 泛型约束；Proto DataStore 使用 Protocol Buffers schema 强制数据模型。
• 异常信号化：数据损坏或读取异常会抛出 CorruptionException 或 IOException，开发者可通过 Flow 的 catch 操作符捕获并处理。
• 支持数据迁移：内置 SharedPreferencesMigration 类，可平滑迁移旧数据，无需手动逐 key 搬运。

1.3 性能对比测试数据

测试环境：Pixel 6 / Android 14 / 100 个 key 写入同一文件。单位：毫秒（ms），取 10 次测试中位数。

1.4 迁移决策流程

下面的流程帮助团队快速评估是否应当迁移：

1.5 性能对比测试代码（参考）

验证上述性能数据，可在测试工程中运行以下基准测试片段：

// BenchmarkUtil.kt – 局部计时工具
inline fun measureTimeMs(tag: String, crossinline block: () -> Unit): Long {
    val start = System.nanoTime()
    block()
    val elapsed = (System.nanoTime() - start) / 1_000_000
    Log.d(tag, "耗时 $elapsed ms")
    return elapsed
}

// SharedPreferences 批量写入测试
fun spBatchWrite(context: Context) {
    val sp = context.getSharedPreferences("test", Context.MODE_PRIVATE)
    measureTimeMs("SP") {
        sp.edit().run {
            repeat(100) { i ->
                putString("key_$i", "value_$i")
            }
            apply()
        }
    }
}

// DataStore 批量写入测试
fun dsBatchWrite(context: Context) {
    val dataStore = context.createDataStore(name = "test_preferences")
    measureTimeMs("DataStore") {
        runBlocking {
            dataStore.edit { preferences ->
                repeat(100) { i ->
                    preferences[stringPreferencesKey("key_$i")] = "value_$i"
                }
            }
        }
    }
}