Jetpack DataStore 是一种数据存储解决方案，允许您使用协议缓冲区存储键值对或类型化对象。DataStore 使用 Kotlin 协程和流程以异步、一致的事务方式存储数据。
如果您当前使用 SharedPreferences 存储数据，请考虑迁移到 DataStore。
注意：如果您需要支持大型或复杂数据集、部分更新或参照完整性，请考虑使用 Room，而不是 DataStore。DataStore 非常适合简单的小型数据集，不支持部分更新或参照完整性。
Preferences DataStore 和 Proto DataStore
DataStore 提供两种不同的实现：Preferences DataStore 和 Proto DataStore。
- Preferences DataStore 使用键存储和访问数据。此实现不需要预定义的架构，也不确保类型安全。
- Proto DataStore 将数据存储为自定义数据类型的实例。此实现要求您使用协议缓冲区来定义架构，但可以确保类型安全。
欢迎使用 Jetpack DataStore，这是一个经过改进的全新数据存储解决方案，旨在替代原有的 SharedPreferences。Jetpack DataStore 基于 Kotlin 协程和 Flow 开发，并提供两种不同的实现: Proto DataStore 和 Preferences DataStore。其中 Proto DataStore，可以存储带有类型的对象 (使用 protocol buffers 实现)；Preferences DataStore，可以存储键值对。在 DataStore 中，数据以异步的、一致的、事务性的方式进行存储，克服了 SharedPreferences 的大部分缺点。
-
protocol buffers
https://developers.google.cn/protocol-buffers
SharedPreferences 和 DataStore 对比
* SharedPreferences 有一个看上去可以在 UI 线程安全调用的同步 API，但是该 API 实际上执行了磁盘 I/O 操作。此外，apply() 方法会在 fsync() 阻塞 UI 线程。在您应用的任何地方，每当 Service 或 Activity 启动或停止时，就会触发等待 fsync() 的调用。由 apply() 安排的 fsync() 调用过程会阻塞 UI 线程，这也常常成为造成 ANR 的源头。
** SharedPreferences 在分析出错时会抛出运行时异常。
-
ANR
https://developer.android.google.cn/topic/performance/vitals/anr
在两种实现中，除非另外特指，否则 DataStore 会将首选项存储在文件中，并且所有的数据操作都会在 Dispatchers.IO 上执行。
虽然 Preferences DataStore 与 Proto DataStore 都可以存储数据，但它们的实现方法不尽相同:
-
Preference DataStore，就像 SharedPreferences 一样，不能定义 schema 或保证以正确的类型访问键值。
-
Proto DataStore 让您可以使用 Protocol buffers 定义 schema。使用 Protobufs 可以保留强类型数据。它们相对于 XML 或其他相似的数据格式要更快、更小、歧义更少。虽然 Proto DataStore 要求您学习一种新的序列化机制，但考虑到 Proto DataStore 所带来的强类型 schema 的优势，我们认为这样的代价是值得的。
-
Protocol buffers
https://developers.google.cn/protocol-buffers
Room 和 DataStore 对比
如果您有局部更新数据、参照完整性或支持大型、复杂数据集的需求，则应当考虑使用 Room 而不是 DataStore。DataStore 是小型、简单数据集的理想选择，它并不支持局部更新与参照完整性。
一、使用 DataStore
如需在您的应用中使用 Jetpack DataStore，请根据您要使用的实现向 Gradle 文件添加以下内容：首先添加 DataStore 依赖项。如果您使用的是 Proto DataStore，请确保您也添加了 proto 依赖项:
-
proto 依赖项
https://github.com/google/protobuf-gradle-plugin
def dataStoreVersion = "1.0.0-alpha05"
// 在 Android 开发者网站上确认最新的版本号
// https://developer.android.google.cn/jetpack/androidx/releases/datastore
// Preferences DataStore
implementation "androidx.datastore:datastore-preferences:$dataStoreVersion"
// Preferences DataStore (SharedPreferences like APIs)
dependencies {
implementation "androidx.datastore:datastore-preferences:1.0.0-alpha05"
}
// Alternatively - use the following artifact without an Android dependency.
dependencies {
implementation "androidx.datastore:datastore-preferences-core:1.0.0-alpha05"
}
// Proto DataStore
implementation "androidx.datastore:datastore-core:$dataStoreVersion"
// Typed DataStore (Typed API surface, such as Proto)
dependencies {
implementation "androidx.datastore:datastore:1.0.0-alpha05"
}
// Alternatively - use the following artifact without an Android dependency.
dependencies {
implementation "androidx.datastore:datastore-core:1.0.0-alpha05"
}
二、创建 DataStore
您可以使用 Context.createDataStore() 扩展方法创建 DataStore:
使用 Preferences DataStore 存储键值对
Preferences DataStore 实现使用 DataStore 和 Preferences 类将简单的键值对保留在磁盘上。
创建 Preferences DataStore
使用 Context.createDataStore() 扩展函数创建 DataStore<Preferences> 的实例。必需的 name 参数是 Preferences DataStore 的名称。
// 创建 Preferences DataStore
val dataStore: DataStore<Preferences> = context.createDataStore(
name = "settings"
)
使用 Proto DataStore 存储类型化的对象
Proto DataStore 实现使用 DataStore 和协议缓冲区将类型化的对象保留在磁盘上。
定义架构
Proto DataStore 要求在 app/src/main/proto/ 目录的 proto 文件中保存预定义的架构。此架构用于定义您在 Proto DataStore 中保存的对象的类型。如需详细了解如何定义 proto 架构，请参阅 protobuf 语言指南。
当您使用 Proto DataStore 时，您需要在 app/src/main/proto/ 目录下使用 proto 文件定义您自己的 schema。有关定义 proto schema 的更多信息，请参阅 protobuf 语言指南。
-
protobuf 语言指南
https://developers.google.cn/protocol-buffers/docs/proto3
syntax = "proto3";
option java_package = "<your package name here>";
option java_multiple_files = true;
message Settings {
int my_counter = 1;
}
注意：您的存储对象的类在编译时由 proto 文件中定义的 message 生成。请务必重新构建您的项目。
创建 Proto DataStore
如果您使用的是 Proto DataStore，您还需要实现 Serializer 接口来告诉 DataStore 如何读取和写入您的数据类型。
创建 Proto DataStore 来存储类型化对象涉及两个步骤：
- 定义一个实现
Serializer<T>的类，其中T是 proto 文件中定义的类型。此序列化器类会告知 DataStore 如何读取和写入您的数据类型。 - 使用
Context.createDataStore()扩展函数创建DataStore<T>的实例，其中T是在 proto 文件中定义的类型。filename参数会告知 DataStore 使用哪个文件存储数据，而serializer参数会告知 DataStore 第 1 步中定义的序列化器类的名称。
object SettingsSerializer : Serializer<Settings> {
override fun readFrom(input: InputStream): Settings {
try {
return Settings.parseFrom(input)
} catch (exception: InvalidProtocolBufferException) {
throw CorruptionException("Cannot read proto.", exception)
}
}
override fun writeTo(t: Settings, output: OutputStream) = t.writeTo(output)
}
// 创建 Proto DataStore
val settingsDataStore: DataStore<Settings> = context.createDataStore(
fileName = "settings.pb",
serializer = SettingsSerializer
)
三、从 DataStore 读取数据
无论是 Preferences 对象还是您在 proto schema 中定义的对象，DataStore 都会以 Flow 的形式暴露已存储的数据。DataStore 可以确保在 Dispatchers.IO 上检索数据，因此不会阻塞您的 UI 线程。
-
Dispatchers.IO
https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-i-o.html
从 Preferences DataStore 读取内容
由于 Preferences DataStore 不使用预定义的架构，因此您必须使用 preferencesKey() 为需要存储在 DataStore<Preferences> 实例中的每个值定义一个键。然后，使用 DataStore.data 属性，通过 Flow 提供适当的存储值。
// 使用 Preferences DataStore:
val MY_COUNTER = preferencesKey<Int>("my_counter")
val myCounterFlow: Flow<Int> = dataStore.data
.map { currentPreferences ->
// 不同于 Proto DataStore，这里不保证类型安全。
currentPreferences[MY_COUNTER] ?: 0
}
从 Proto DataStore 读取内容
使用 DataStore.data 显示所存储对象的相应属性的 Flow。
// 使用 Proto DataStore:
val myCounterFlow: Flow<Int> = settingsDataStore.data
.map { settings ->
// myCounter 属性由您的 proto schema 生成！
settings.myCounter
}
四、向 DataStore 写入数据
为了写入数据，DataStore 提供了一个 DataStore.updateData() 挂起函数，它会将当前存储数据的状态作为参数提供给您，对于 Preferences 对象或是您在 proto schema 中定义的对象实例皆为如此。updateData() 函数使用原子的读、写、修改操作并以事务的方式更新数据。当数据在磁盘上完成存储时，此协程就会完成。
Preferences DataStore 还提供了一个 DataStore.edit() 函数来方便数据的更新。在此函数中，您会收到一个用于编辑的 MutablePreferences 对象，而不是 Preferences 对象。该函数与 updateData() 一样，会在转换代码块完成之后将修改应用到磁盘，并且当数据在磁盘上完成存储时，此协程就会完成。
将内容写入 Preferences DataStore
Preferences DataStore 提供了一个 edit() 函数，用于以事务方式更新 DataStore 中的数据。该函数的 transform 参数接受代码块，您可以在其中根据需要更新值。转换块中的所有代码均被视为单个事务。
// 使用 Preferences DataStore:
suspend fun incrementCounter() {
dataStore.edit { settings ->
// 可以安全地增加我们的计数器，而不会因为资源竞争而丢失数据。
val currentCounterValue = settings[MY_COUNTER] ?: 0
settings[MY_COUNTER] = currentCounterValue + 1
}
}
将内容写入 Proto DataStore
Proto DataStore 提供了一个 updateData() 函数，用于以事务方式更新存储的对象。updateData() 为您提供数据的当前状态，作为数据类型的一个实例，并在原子读-写-修改操作中以事务方式更新数据。
// 使用 Proto DataStore:
suspend fun incrementCounter() {
settingsDataStore.updateData { currentSettings ->
// 可以安全地增加我们的计数器，而不会因为资源竞争而丢失数据。
currentSettings.toBuilder()
.setMyCounter(currentSettings.myCounter + 1)
.build()
}
}
五、在同步代码中使用 DataStore
注意：请尽可能避免在 DataStore 数据读取时阻塞线程。阻塞界面线程可能会导致 ANR 或界面卡顿，而阻塞其他线程可能会导致死锁。
DataStore 的主要优势之一是异步 API，但可能不一定始终能将周围的代码更改为异步代码。如果您使用了采用同步磁盘 I/O 的现有代码库，或者您的依赖项不提供异步 API，就可能出现这种情况。
Kotlin 协程提供 runBlocking() 协程构建器，以帮助消除同步与异步代码之间的差异。您可以使用 runBlocking() 从 DataStore 同步读取数据。以下代码会阻塞发起调用的线程，直到 DataStore 返回数据：
val exampleData = runBlocking { dataStore.data.first() }
对界面线程执行同步 I/O 操作可能会导致 ANR 或界面卡顿。您可以通过从 DataStore 异步预加载数据来缓解这些问题：
override fun onCreate(savedInstanceState: Bundle?) {
lifecycleScope.launch {
dataStore.data.first()
// You should also handle IOExceptions here.
}
}
这样，DataStore 可以异步读取数据并将其缓存在内存中。以后使用 runBlocking() 进行同步读取的速度可能会更快，或者如果初始读取已经完成，可能也可以完全避免磁盘 I/O 操作。
六、从 SharedPreferences 迁移至 DataStore
要从 SharedPreferences 迁移至 DataStore，您需要将 SharedPreferencesMigration 对象传递给 DataStore 构造器，DataStore 可以自动完成从 SharedPreferences 迁移至 DataStore 的工作。迁移会在 DataStore 中发生任何数据访问之前运行，这意味着在 DataStore.data 返回任何值以及 DataStore.updateData() 可以更新数据之前，您的迁移必须已经成功。
如果您要迁移至 Preferences DataStore，您可以使用 SharedPreferencesMigration 的默认实现。只需要传入 SharedPreferences 构造时所使用的名字就可以了。
使用 Preferences DataStore：
val dataStore: DataStore<Preferences> = context.createDataStore(
name = "settings",
migrations = listOf(SharedPreferencesMigration(context, "settings_preferences"))
)
当需要迁移至 Proto DataStore 时，您必须实现一个映射函数，用来定义如何将 SharedPreferences 所使用的键值对迁移到您所定义的 DataStore schema。
使用 Proto DataStore:
val settingsDataStore: DataStore<Settings> = context.createDataStore(
produceFile = { File(context.filesDir, "settings.preferences_pb") },
serializer = SettingsSerializer,
migrations = listOf(
SharedPreferencesMigration(
context,
"settings_preferences"
) { sharedPrefs: SharedPreferencesView, currentData: UserPreferences ->
// 在这里将 sharedPrefs 映射至您的类型。
}
)
)
七、总结
SharedPreferences 有着许多缺陷: 看起来可以在 UI 线程安全调用的同步 API 其实并不安全、没有提示错误的机制、缺少事务 API 等等。DataStore 是 SharedPreferences 的替代方案，它解决了 Shared Preferences 的绝大部分问题。DataStore 包含使用 Kotlin 协程和 Flow 实现的完全异步 API，可以处理数据迁移、保证数据一致性，并且可以处理数据损坏。
-
文档
https://developer.android.google.cn/datastore
-
Preferences DataStore codelab
https://developer.android.google.cn/codelabs/android-preferences-datastore#0
-
Proto DataStore codelab
https://developer.android.google.cn/codelabs/android-proto-datastore#0
-
问题跟踪器
https://issuetracker.google.com/issues/new?component=907884&template=1466542