使用 Jetpack DataStore 进行数据存储

做者 / Android 开发技术推广工程师 Florina Muntenescu 与 Google 软件工程师 Rohit Sathyanarayana

欢迎使用 Jetpack DataStore，这是一个通过改进的全新数据存储解决方案，旨在替代原有的 SharedPreferences。Jetpack DataStore 基于 Kotlin 协程和 Flow 开发，并提供两种不一样的实现: Proto DataStore 和 Preferences DataStore。其中 Proto DataStore，能够存储带有类型的对象 (使用 protocol buffers 实现)；Preferences DataStore，能够存储键值对。在 DataStore 中，数据以异步的、一致的、事务性的方式进行存储，克服了 SharedPreferences 的大部分缺点。

SharedPreferences 和 DataStore 对比

• SharedPreferences 有一个看上去能够在 UI 线程安全调用的同步 API，可是该 API 实际上执行了磁盘 I/O 操做。此外，apply() 方法会在 fsync() 阻塞 UI 线程。在您应用的任何地方，每当 Service 或 Activity 启动或中止时，就会触发等待 fsync() 的调用。由 apply() 安排的 fsync() 调用过程会阻塞 UI 线程，这也经常成为形成 ANR 的源头。
• SharedPreferences 在分析出错时会抛出运行时异常。

在两种实现中，除非另外特指，不然 DataStore 会将首选项存储在文件中，而且全部的数据操做都会在 Dispatchers.IO 上执行。

虽然 Preferences DataStore 与 Proto DataStore 均可以存储数据，但它们的实现方法不尽相同:

• Preference DataStore，就像 SharedPreferences 同样，不能定义 schema 或保证以正确的类型访问键值。
• Proto DataStore 让您能够使用 Protocol buffers 定义 schema。使用 Protobufs 能够保留强类型数据。它们相对于 XML 或其余类似的数据格式要更快、更小、歧义更少。虽然 Proto DataStore 要求您学习一种新的序列化机制，但考虑到 Proto DataStore 所带来的强类型 schema 的优点，咱们认为这样的代价是值得的。

Room 和 DataStore 对比

若是您有局部更新数据、参照完整性或支持大型、复杂数据集的需求，则应当考虑使用 Room 而不是 DataStore。DataStore 是小型、简单数据集的理想选择，它并不支持局部更新与参照完整性。

使用 DataStore

首先添加 DataStore 依赖项。若是您使用的是 Proto DataStore，请确保您也添加了 proto 依赖项:

def dataStoreVersion = "1.0.0-alpha05" 
// 在 Android 开发者网站上确认最新的版本号 
// https://developer.android.google.cn/jetpack/androidx/releases/datastore

// Preferences DataStore
implementation "androidx.datastore:datastore-preferences:$dataStoreVersion"

// Proto DataStore
implementation  "androidx.datastore:datastore-core:$dataStoreVersion"

当您使用 Proto DataStore 时，您须要在 app/src/main/proto/ 目录下使用 proto 文件定义您本身的 schema。有关定义 proto schema 的更多信息，请参阅 protobuf 语言指南。

syntax = "proto3";

option java_package = "<your package name here>";
option java_multiple_files = true;

message Settings {
  int my_counter = 1;
}

建立 DataStore

您能够使用 Context.createDataStore() 扩展方法建立 DataStore:

// 建立 Preferences DataStore 
val dataStore: DataStore<Preferences> = context.createDataStore(
    name = "settings"
)

若是您使用的是 Proto DataStore，您还须要实现 Serializer 接口来告诉 DataStore 如何读取和写入您的数据类型。

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 线程。

使用 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:

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:

suspend fun incrementCounter() {
    dataStore.edit { settings ->
        // 能够安全地增长咱们的计数器，而不会由于资源竞争而丢失数据。
        val currentCounterValue = settings[MY_COUNTER] ?: 0
        settings[MY_COUNTER] = currentCounterValue + 1
    }
}

使用 Proto DataStore:

suspend fun incrementCounter() {
    settingsDataStore.updateData { currentSettings ->
        // 能够安全地增长咱们的计数器，而不会由于资源竞争而丢失数据。
        currentSettings.toBuilder()
            .setMyCounter(currentSettings.myCounter + 1)
            .build()
    }
}

从 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，能够处理数据迁移、保证数据一致性，而且能够处理数据损坏。

因为 DataStore 仍处于测试阶段，所以咱们须要您的帮助以使其变得更好！首先，您能够经过咱们的 文档 了解有关 DataStore 的更多信息，也能够经过咱们为您准备的两个 Codelab: Preferences DataStore codelab 和 Proto DataStore codelab 来尝试 DataStore。最后，您能够在 问题跟踪器 上建立问题，让咱们知道如何来改进 DataStore。