3. DataStore 核心概念精讲：Preference 与 Proto DataStore 的区别、存储模型及序列化方式

DataStore 是 Jetpack 提供的现代化数据持久化方案，替代 SharedPreferences。它提供两种实现：Preference DataStore 和 Proto DataStore。两者底层共享基于文件的事务性存储引擎，但在数据建模、类型安全、序列化路径上存在本质差异。理解这些差异是完成 Room → DataStore 迁移决策的前提。

3.1 核心区别一览

3.2 架构对比：两条持久化路径

下面的架构图展示了两种 DataStore 从应用层到磁盘的完整路径。左侧为 Preference 路线，右侧为 Proto 路线，底部为统一的持久化层。

3.3 Preference DataStore 深度解析

存储模型

Preference DataStore 采用键值对（Key-Value）模型，每个数据条目通过 PreferencesKey<T> 标识。所有 Key 共享同一个文件，内部以 Map<String, Any> 形式维护在内存中，写入时通过事务追加方式持久化到文件。Key 在运行时使用 stringPreferencesKey、intPreferencesKey 等工厂函数创建，无需预定义 Schema。

序列化方式

序列化完全由 DataStore 框架封装。框架内部将键值对转换为二进制格式写入文件，读取时反序列化为 Map。开发者不需要定义任何序列化器，也不感知序列化细节。支持的 Value 类型被硬编码为：Int、Long、Float、Double、Boolean、String、Set<String>。

代码示例：定义、写入与读取

// 1. 在顶层扩展属性中定义 DataStore
val Context.userPrefDataStore by preferencesDataStore(
    name = "user_preferences"
)

// 2. 定义 Key（运行时）
private val KEY_USER_NAME = stringPreferencesKey("user_name")
private val KEY_AGE = intPreferencesKey("age")
private val KEY_DARK_MODE = booleanPreferencesKey("dark_mode")

// 3. 写入数据
suspend fun saveUserPreferences(context: Context, name: String, age: Int, darkMode: Boolean) {
    context.userPrefDataStore.edit { prefs ->
        prefs[KEY_USER_NAME] = name
        prefs[KEY_AGE] = age
        prefs[KEY_DARK_MODE] = darkMode
    }
}

// 4. 读取数据（返回 Flow）
val userNameFlow: Flow<String?> = context.userPrefDataStore.data
    .map { preferences ->
        preferences[KEY_USER_NAME]
    }

val isDarkModeFlow: Flow<Boolean> = context.userPrefDataStore.data
    .map { preferences ->
        preferences[KEY_DARK_MODE] ?: false  // 提供默认值
    }

3.4 Proto DataStore 深度解析

存储模型

Proto DataStore 采用类型化对象（Typed Object）模型。整个 DataStore 文件在逻辑上只包含一个 Protobuf Message 实例。所有数据字段都在这个 Message 中定义，文件内容就是该 Message 的二进制编码。读取时整个 Message 被反序列化到内存，写入时替换整个 Message。这种“全量读、全量写”的模式使得字段级的原子性由 Protobuf 的内置机制保障。

序列化方式

序列化依赖 Protocol Buffers。开发者必须完成三项工作：① 编写 .proto 文件定义消息结构；② 使用 protoc 编译器（或 Gradle 插件）生成 Java/Kotlin 类；③ 实现 Serializer<T> 接口，将生成的类与 DataStore 绑定。序列化和反序列化逻辑由生成的 parseFrom() 和 writeTo() 方法完成。

代码示例：Proto 定义 → Serializer → 创建 DataStore

步骤 1：定义 .proto 文件

// src/main/proto/user_preferences.proto
syntax = "proto3";

option java_package = "com.example.datastore.proto";
option java_multiple_files = true;

message UserPreferences {
  string user_name = 1;
  int32 age = 2;
  bool notifications_enabled = 3;
  repeated string favorite_colors = 4;
}

步骤 2：配置 Gradle 编译 protobuf（app/build.gradle.kts）

plugins {
    id("com.google.protobuf") version "0.9.4"
}

android {
    // ...
}

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:3.25.1"
    }
    generateProtoTasks {
        all().forEach { task ->
            task.builtins {
                create("java") {
                    option("lite")
                }
                create("kotlin")
            }
        }
    }
}

dependencies {
    implementation("com.google.protobuf:protobuf-javalite:3.25.1")
    implementation("androidx.datastore:datastore:1.1.1")
}

步骤 3：实现 Serializer

import androidx.datastore.core.Serializer
import com.example.datastore.proto.UserPreferences
import java.io.InputStream
import java.io.OutputStream

object UserPreferencesSerializer : Serializer<UserPreferences> {
    override val defaultValue: UserPreferences
        get() = UserPreferences.getDefaultInstance()

    override suspend fun readFrom(input: InputStream): UserPreferences {
        return UserPreferences.parseFrom(input)
    }

    override suspend fun writeTo(t: UserPreferences, output: OutputStream) {
        t.writeTo(output)
    }
}

步骤 4：创建 Proto DataStore 实例

val Context.userProtoDataStore by dataStore(
    fileName = "user_preferences.pb",
    serializer = UserPreferencesSerializer
)

步骤 5：读写数据

// 读取（返回 Flow<UserPreferences>）
val userPrefsFlow: Flow<UserPreferences> = context.userProtoDataStore.data

// 写入（通过 updateData 事务）
suspend fun updateUserName(context: Context, newName: String) {
    context.userProtoDataStore.updateData { currentPrefs ->
        currentPrefs.toBuilder()
            .setUserName(newName)
            .build()
    }
}

3.5 存储模型深入对比

3.6 序列化方式深入对比

3.7 性能与稳定性考量

• 写入延迟：两种 DataStore 的写入操作都是异步挂起函数，内部通过单线程写入器串行化，避免并发写冲突。Preference 的 edit 和 Proto 的 updateData 在事务上等价。
• 文件损坏恢复：两种实现都使用追加写入 + 替换策略。写入时先写临时文件，成功后原子替换原文件。如果进程在写入中崩溃，临时文件被丢弃，原文件保持不变。
• 内存占用：Preference DataStore 将所有 Key 加载到内存 Map 中，Key 数量越多内存占用越高。Proto DataStore 只有单个对象实例，内存占用取决于 Message 中字段的总数据量。
• 冷启动加载：首次读取 .data Flow 时，两种 DataStore 都会从磁盘同步加载一次数据到内存。Proto DataStore 需要全量反序列化，大 Message（超过 500KB）可能造成 ANR 风险。建议将大对象拆分到多个 Proto DataStore 文件中。

3.8 常见错误与避坑

• 错误 1：跨 DataStore 文件使用相同 Key 名称
  如果两个不同的 preferencesDataStore(name = "...")
• 错误 2：Proto DataStore 修改字段类型未更新版本
  将 int32 age = 2 改为 string age = 2 会导致已存储的数据反序列化抛出 InvalidProtocolBufferException。务必使用新的字段号，或标记旧字段为 reserved。
• 错误 3：在多个模块中定义相同 fileName 的 Proto DataStore
  不同 Gradle Module 如果定义了同名的 Proto DataStore（相同的 fileName），写入时会互相覆盖文件，造成数据丢失。建议在文件名中加入模块前缀，如 moduleA_user_prefs.pb。
• 错误 4：未处理 DataStore 初始化异常
  如果文件损坏或反序列化失败，.data Flow 会抛出 DataStoreException。生产环境应使用 .catch { emit(defaultValue) } 或 mapCatching 提供降级策略，避免崩溃。

// 安全的读取示例（捕获异常并降级）
val safeUserPrefsFlow: Flow<UserPreferences> = context.userProtoDataStore.data
    .catch { exception ->
        // 记录日志
        Log.e("DataStore", "读取失败，使用默认值", exception)
        // 发射默认值
        emit(UserPreferences.getDefaultInstance())
    }