第2章：Gradle 依赖配置与版本选择

迁移到 DataStore 的第一步是正确配置 Gradle 依赖。目前 DataStore 提供两种实现：Preferences DataStore 和 Proto DataStore，它们的依赖声明、版本选择以及对 Kotlin 协程与 Flow 的依赖要求略有不同。本章将详细说明如何正确声明依赖、处理版本兼容性以及避免常见的依赖冲突。

2.1 Preferences DataStore 依赖

Preferences DataStore 以键值对形式存储数据，无需定义 Schema。只需添加以下单一依赖即可使用：

// build.gradle (Module: app)
dependencies {
    // Preferences DataStore
    implementation("androidx.datastore:datastore-preferences:1.0.0")
}

若项目中已启用 Kotlin 1.6+，该依赖会自动拉取 kotlinx-coroutines-core 与 kotlinx-serialization（用于序列化），但建议显式声明协程版本以保证可控性（参见第 2.4 节）。

2.2 Proto DataStore 依赖

Proto DataStore 基于 Protocol Buffers，需要同时引入 datastore-core 和 protobuf 相关依赖：

// build.gradle (Module: app)
dependencies {
    // Proto DataStore 核心
    implementation("androidx.datastore:datastore-core:1.0.0")

    // Protocol Buffers 运行时
    implementation("com.google.protobuf:protobuf-javalite:3.21.12")

    // 可选：使用 Kotlin 序列化器时可添加 protobuf-kotlin-lite
    // implementation("com.google.protobuf:protobuf-kotlin-lite:3.21.12")
}

此外，需要在项目根目录的 build.gradle 中配置 protobuf 插件以自动生成 Java/Kotlin 数据类：

// build.gradle (Project)
plugins {
    id("com.google.protobuf") version "0.9.4" apply false
}

// build.gradle (Module: app)
plugins {
    id("com.google.protobuf")
}

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

2.3 版本兼容性矩阵

下表列出主流依赖组合的兼容性，建议在迁移时参考：

2.4 Kotlin 协程与 Flow 依赖

两种 DataStore 都基于 Kotlin 协程和 Flow 实现异步读写。即使 DataStore 本身已经间接引入了协程库，仍建议显式声明以下依赖以确保版本可控：

// 协程核心与 Android 调度器
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")

// Flow 相关（DataStore API 已包含，但若需操作 Lifecycle-aware 数据）
implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.6.2")
implementation("androidx.lifecycle:lifecycle-livedata-ktx:2.6.2") // 仅在转换 DataStore Flow 到 LiveData 时需要

若项目中同时使用 Room 或其他协程框架，请核对 coroutines 版本以避免 NoSuchMethodError。推荐统一使用同一版本号。

2.5 选择指南与 SVG 流程图

决定使用哪种 DataStore 是依赖配置的第一个关键分支。下面的流程图帮助团队快速决策，并明确对应的依赖声明路径：