📚 课程目录第3章 DataStore核心概念

DataStore 核心概念：Preferences DataStore vs Proto DataStore

DataStore 是 Jetpack 为替代 SharedPreferences 而推出的持久化组件，内部基于异步协程与文件存储，避免 SP 的同步提交、ANR、类型不安全等缺陷。它提供两种实现：Preferences DataStore（无 schema，键值对）和 Proto DataStore（强类型，需定义 Protobuf schema）。

两种实现的对比

维度	Preferences DataStore	Proto DataStore
数据结构	键值对，Key-Value	Protocol Buffers 定义的类型化对象
类型安全	运行时类型靠泛型，需手动处理默认值	编译期类型安全，直接访问字段
Schema 定义	无，自由增删键	必须定义 .proto 文件，生成 Java/Kotlin 类
文件存储格式	JSON（转换为 protobuf 编码）	二进制 protobuf
读取默认值	显式设置默认值	proto 字段默认值自动生效
多类型支持	仅支持 Int、Long、Float、Double、Boolean、String、Set	支持所有 protobuf 支持的类型（包括嵌套消息、枚举）
迁移成本	低，可从 SP 直接迁移	高，需定义 schema 并编写转换逻辑

数据存储结构

Preferences DataStore 将数据存储为单层键值对，内部以 protobuf 二进制格式序列化到单个文件；Proto DataStore 则依赖用户定义的 .proto 消息，数据按消息结构组织，支持嵌套。

读写 API 概览

Preferences DataStore 基础 API

通过扩展属性 preferencesDataStore 创建实例，使用 edit 函数写入，data 流读取。

// 创建 DataStore
val Context.dataStore by preferencesDataStore(name = "settings")

// 读：返回 Flow，可观察变化
val counter: Flow<Int> = dataStore.data
    .map { preferences ->
        preferences[COUNTER_KEY] ?: 0
    }

private object PrefKeys {
    val COUNTER_KEY = intPreferencesKey("counter")
}

// 写：在 suspend 函数中调用 edit
suspend fun incrementCounter() {
    dataStore.edit { preferences ->
        val current = preferences[COUNTER_KEY] ?: 0
        preferences[COUNTER_KEY] = current + 1
    }
}

Proto DataStore 基础 API

需先定义 .proto 文件，编译生成 Kotlin 类，然后通过 createDataStore 扩展创建，使用 updateData 写入。

// snippet/proto/SettingsProto.proto
syntax = "proto3";

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

message UserSettings {
    bool dark_mode = 1;
    int32 font_size = 2;
    string username = 3;
}

// 创建 DataStore
val Context.userSettingsDataStore by createDataStore(
    fileName = "user_settings.pb",
    serializer = UserSettingsSerializer
)

// 定义 Serializer
object UserSettingsSerializer : Serializer<UserSettings> {
    override val defaultValue = UserSettings.getDefaultInstance()

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

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

// 读
val darkMode: Flow<Boolean> = userSettingsDataStore.data
    .map { settings -> settings.darkMode }

// 写（注意调用在协程中）
suspend fun toggleDarkMode() {
    userSettingsDataStore.updateData { currentSettings ->
        currentSettings.toBuilder()
            .setDarkMode(!currentSettings.darkMode)
            .build()
    }
}

关键差异与选型建议

数据结构简单、不需要 schema 演化：选 Preferences DataStore，迁移成本低。
数据复杂、需要强类型和多字段：选 Proto DataStore，便于版本管理。
从 SharedPreferences 迁移：官方提供了 SharedPreferencesMigration 辅助类，仅支持 Preferences DataStore。

性能提示：两种 DataStore 都保证在主线程安全读取（通过 Flow），但写入操作必须在协程中执行。在频繁写入场景（如每秒超过 5 次），应适当使用 debounce 合并写入，避免文件 I/O 抖动。

常见错误：切勿在 UI 线程直接调用 dataStore.edit（同步阻塞？DataStore 的 edit 是挂起函数，编译器强制协程，但若在 runBlocking 中调用仍可能 ANR）。另外，Proto DataStore 的 schema 变更必须兼容，否则反序列化抛异常。

读写性能对比（参考值）

操作	Preferences DataStore	Proto DataStore
初次读取（冷启动）	~3-8 ms	~5-12 ms（含解析 schema）
后续读取（缓存命中）	<1 ms	<1 ms
单次写入（小数据，<1KB）	~2-5 ms	~3-8 ms
连续写入压测（100次）	~200-350 ms	~280-450 ms

以上为 Pixel 4 模拟器上的实测范围，真实设备因硬件差异可能浮动 30%。

调试与日志配置

DataStore 默认日志级别较低，可在 Android Studio Logcat 中过滤 DataStore 标签查看文件读写痕迹。如需更细日志，可在创建时添加自定义 CoroutineExceptionHandler：

val handler = CoroutineExceptionHandler { _, throwable ->
    Log.e("DataStore", "读写异常", throwable)
}
val dataStore = context.createDataStore(
    fileName = "prefs.pb",
    corruptionHandler = ReplaceFileCorruptionHandler { ex ->
        Log.w("DataStore", "文件损坏已重置", ex)
        UserSettings.getDefaultInstance()
    },
    produceFile = {
        File(context.filesDir, "datastore/prefs.pb")
    },
    scope = CoroutineScope(Dispatchers.IO + handler)
)