1. DataStore 离线缓存概述与迁移动机

Android DataStore 是 Google 推出的新一代本地持久化存储方案，用于替代历史久远的 SharedPreferences。它基于 Kotlin 协程与 Flow 构建，天然支持异步、事务性写入，且默认提供 类型安全 的 Protobuf 版本（DataStore）以及简单键值版本（Preferences DataStore）。DataStore 从 Android 12（API 31） 开始成为官方首选存储组件，Google 明确建议新项目优先使用 DataStore，并提供了从 SharedPreferences 到 DataStore 的 迁移适配器。

迁移的核心动机在于 SharedPreferences 的 同步写入 机制会在 UI 线程引发 ANR（Application Not Responding），且不支持 事务性批量写入、数据一致性保证和运行时类型安全。DataStore 通过 协程+Flow 将读写操作移至后台线程，并利用 事务性写入 确保数据要么全部写入，要么全部回滚，避免脏数据。

1.1 DataStore vs SharedPreferences 关键差异

1.2 离线缓存场景与迁移收益

DataStore 特别适合以下 离线缓存场景：

• 用户偏好设置：主题、语言、通知开关等非敏感轻量配置。
• 应用状态持久化：上次登录用户、引导页已展示标志、首次启动时间戳。
• 离线任务队列元数据：如缓存键、最后同步时间、分页游标。
• 联网带宽受限时的关键配置：如服务器端点缓存、日志级别等。

1.3 适用版本与兼容性

DataStore 从版本 1.0.0 起稳定，支持 Android API 14（Ice Cream Sandwich） 及以上设备。迁移适配器 SharedPreferencesMigration 作为独立 artifact 提供，无需修改原 SP 文件即可完成迁移。Google Play Services 和 Jetpack 库均已适配。

// Preferences DataStore
implementation "androidx.datastore:datastore-preferences:1.0.0"

// 如需 Proto 支持
implementation "androidx.datastore:datastore-core:1.0.0"

// 迁移适配器（用于从 SharedPreferences 迁移）
implementation "androidx.datastore:datastore-migration:1.0.0"

1.4 迁移前代码示例（SharedPreferences 风格）

以下是一段典型的 SharedPreferences 读写代码，后续章节将演示如何迁移到 DataStore：

// 写入（同步，可能阻塞 UI）
val prefs = getSharedPreferences("app_settings", Context.MODE_PRIVATE)
prefs.edit().putBoolean("is_dark_mode", true).apply() // apply 异步但仍有风险

// 读取（同步，UI 线程执行）
val isDarkMode = prefs.getBoolean("is_dark_mode", false)

// 监听变化（效率低，需轮询或手动注册）
prefs.registerOnSharedPreferenceChangeListener { sharedPreferences, key ->
    // 回调中处理变化
}

1.5 迁移后代码示例（DataStore 风格预览）

// 定义 DataStore（通常在单例或顶层属性中）
val Context.settingsDataStore by preferencesDataStore(name = "app_settings")

// 定义类型安全的键
val IS_DARK_MODE = booleanPreferencesKey("is_dark_mode")

// 写入（协程，原子事务）
suspend fun setDarkMode(context: Context, enabled: Boolean) {
    context.settingsDataStore.edit { preferences ->
        preferences[IS_DARK_MODE] = enabled
    }
}

// 读取（返回 Flow，可观察变化）
val darkModeFlow: Flow = context.settingsDataStore.data.map { preferences ->
    preferences[IS_DARK_MODE] ?: false
}

1.6 迁移流程总览架构图

1.7 什么时候必须迁移？什么时候可以暂缓？