2. 项目环境搭建：添加Gradle依赖、配置Kotlin协程与Flow依赖、最小SDK要求

本章将引导你完成 DataStore 项目的基础环境搭建。正确的依赖配置是 DataStore 正常工作的前提，同时还需要适配 Kotlin 协程与 Flow 的异步数据流模型。我们将从最小 SDK 版本要求、Gradle 依赖声明、协程及 Flow 的集成配置三个方面展开，并附上验证步骤与常见问题排查。

2.1 最小 SDK 要求与构建工具版本

DataStore 基于 AndroidX 库实现，对 API 级别有最低要求。下表列出了项目必须满足的基线版本：

2.2 添加 Gradle 依赖：Preferences DataStore 与 Proto DataStore

DataStore 提供两种实现：Preferences DataStore（轻量键值存储）和 Proto DataStore（基于 Protocol Buffers 的类型安全存储）。根据需求在 build.gradle（模块级）添加对应依赖。

2.2.1 Preferences DataStore 依赖

dependencies {
    implementation "androidx.datastore:datastore-preferences:1.0.0"
}

2.2.2 Proto DataStore 依赖

使用 Proto DataStore 需要额外添加 protobuf 编译插件及运行时库：

dependencies {
    implementation "androidx.datastore:datastore-core:1.0.0"
    implementation "com.google.protobuf:protobuf-javalite:3.21.7"
}

// 在项目级 build.gradle 添加 protobuf 插件
plugins {
    id "com.google.protobuf" version "0.9.1" apply false
}

2.3 配置 Kotlin 协程与 Flow 依赖

DataStore 的数据操作基于协程（Coroutine）和 Flow 实现异步、响应式读取。必须引入协程核心库及生命周期扩展库（可选但强烈建议）。

dependencies {
    // 协程核心
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4"

    // 生命周期对协程的支持（用于 ViewModelScope）
    implementation "androidx.lifecycle:lifecycle-runtime-ktx:2.6.1"
    implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:2.6.1"

    // Flow 是 Kotlin 标准库的一部分，无需额外依赖
    // 但需要确保 Kotlin 版本 ≥1.6
}

注意：Flow 是 kotlinx.coroutines.flow 包中的核心类型，已随协程库引入，无需单独添加。确保项目 Kotlin 编译版本与协程库版本兼容。

2.4 环境搭建流程总览

下图展示了从依赖声明到可运行 DataStore 实例的关键步骤：

2.5 调试：验证依赖是否正确加载

在成功同步 Gradle 后，执行以下操作验证环境：

• 在项目根目录执行 ./gradlew app:dependencies --configuration implementation，检查是否包含 androidx.datastore 及 kotlinx-coroutines。
• 在 Activity 或 ViewModel 中创建一个 DataStore 实例并尝试写入一个键值对（Preferences DataStore）：

val Context.dataStore by preferencesDataStore(name = "test_prefs")

suspend fun writeTest(context: Context) {
    context.dataStore.edit { prefs ->
        prefs[booleanPreferencesKey("is_setup_complete")] = true
    }
}

• 运行后检查本地文件（位于 /data/data/[packageName]/files/datastore/）是否存在 test_prefs.preferences_pb 文件。若文件生成，说明环境搭建成功。

2.6 常见错误与解决方案

2.7 性能与稳定性优化建议

• 避免在主线程调用 DataStore 操作： dataStore 的读写都是挂起函数，需在协程调度器如 Dispatchers.IO 或 ViewModelScope 中执行。
• 使用 Flow 进行观察，避免轮询： DataStore 默认暴露 Flow，每次数据更新都会自动通知，无需手动轮询。
• 合理设置 DataStoreFactory 的文件路径： 默认路径位于 files/datastore/，可自定义目录但建议保持一致以防数据丢失。
• 在多进程环境下使用 DataStoreFactory.MultiProcessMultiInstance： 如果应用有多个进程访问同一个 DataStore，需要开启多进程支持（Pro DataStore 1.1.0+ 已支持）。
• 定期压缩数据文件： 频繁写入会导致文件体积增长，可考虑在闲时调用 dataStore.asyncCompact()（Proto DataStore 专用）或自行控制写入频率。

private val dataStore = context.createDataStore(
    fileName = "settings.pb",
    serializer = SettingsSerializer,
    produceFile = { context.preferencesDataStoreFile("settings.pb") }
)

完成本章配置后，你的项目已具备使用 DataStore 的全部基础设施。接下来可以进入 DataStore 核心 API 的学习与实践。