DataStore 用于 Kotlin：完整指南及示例

1. 什么是 DataStore 及其用途

DataStore 是 Google 提供的一个库，用于在 Kotlin（及 Android）应用中存储少量数据。它取代了过时的 SharedPreferences，并提供了一种更安全、异步且类型安全的数据处理方式。DataStore 使用 Kotlin Coroutines 和 Flow，使其成为使用响应式编程编写的现代应用的理想选择。

为什么需要 DataStore？SharedPreferences 的主要问题是同步磁盘读取会阻塞 UI 线程，并且缺乏对数据类型的支持（所有内容都存储为 Set<String>）。DataStore 解决了这些问题：所有读写操作都是异步的，数据存储在类型化对象中（通过 Protocol Buffers 或 Preferences）。此外，DataStore 会自动处理序列化错误，并提供简洁的 API 来处理数据。

该库有两种变体：Preferences DataStore（用于存储简单的键值对，类似于 SharedPreferences）和 Proto DataStore（用于通过 Protocol Buffers 存储类型化对象）。在本文中，我们将重点介绍 Preferences DataStore，因为它是最简单且最常用的变体。

2. 安装

DataStore 通过 Maven Central 分发。要将其添加到 Kotlin/Android 项目中，请在 build.gradle.kts 文件（app 模块）中添加依赖项：

dependencies {\n    // Preferences DataStore\n    implementation("androidx.datastore:datastore-preferences:1.1.1")\n    \n    // 如果您使用 Proto DataStore\n    // implementation("androidx.datastore:datastore-core:1.1.1")\n    \n    // 用于支持 Coroutines（通常项目中已有）\n    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0")\n}\n

如果您使用 Groovy 的 Gradle（build.gradle），则行将如下所示：

implementation 'androidx.datastore:datastore-preferences:1.1.1'\n

同步 Gradle 后，该库即可使用。

3. 快速入门 — 最小工作示例

让我们创建一个简单的 DataStore 来存储用户名和计数器。

import android.content.Context\nimport androidx.datastore.core.DataStore\nimport androidx.datastore.preferences.core.Preferences\nimport androidx.datastore.preferences.core.edit\nimport androidx.datastore.preferences.core.intPreferencesKey\nimport androidx.datastore.preferences.core.stringPreferencesKey\nimport androidx.datastore.preferences.preferencesDataStore\nimport kotlinx.coroutines.flow.Flow\nimport kotlinx.coroutines.flow.map\n\n// 为 Context 创建 DataStore 的扩展\nval Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "user_settings")\n\n// 数据的键\nval USER_NAME_KEY = stringPreferencesKey("user_name")\nval COUNTER_KEY = intPreferencesKey("counter")\n\nclass UserPreferences(private val context: Context) {\n\n    // 将用户名作为 Flow 读取\n    val userName: Flow<String?> = context.dataStore.data.map { preferences ->\n        preferences[USER_NAME_KEY]\n    }\n\n    // 将计数器作为 Flow 读取\n    val counter: Flow<Int> = context.dataStore.data.map { preferences ->\n        preferences[COUNTER_KEY] ?: 0\n    }\n\n    // 保存用户名\n    suspend fun saveUserName(name: String) {\n        context.dataStore.edit { preferences ->\n            preferences[USER_NAME_KEY] = name\n        }\n    }\n\n    // 增加计数器\n    suspend fun incrementCounter() {\n        context.dataStore.edit { preferences ->\n            val currentCounter = preferences[COUNTER_KEY] ?: