使用 Jetpack DataStore 进行数据存储

.markdown-body{word-break:break-word;line-height:1.75;font-weight:400;font-size:15px;overflow-x:hidden;color:#333}.markdown-body h1,.markdown-body h2,.markdown-body h3,.markdown-body h4,.markdown-body h5,.markdown-body h6{line-height:1.5;margin-top:35px;margin-bottom:10px;padding-bottom:5px}.markdown-body h1{font-size:30px;margin-bottom:5px}.markdown-body h2{padding-bottom:12px;font-size:24px;border-bottom:1px solid #ececec}.markdown-body h3{font-size:18px;padding-bottom:0}.markdown-body h4{font-size:16px}.markdown-body h5{font-size:15px}.markdown-body h6{margin-top:5px}.markdown-body p{line-height:inherit;margin-top:22px;margin-bottom:22px}.markdown-body img{max-width:100%}.markdown-body hr{border:none;border-top:1px solid #ddd;margin-top:32px;margin-bottom:32px}.markdown-body code{word-break:break-word;border-radius:2px;overflow-x:auto;background-color:#fff5f5;color:#ff502c;font-size:.87em;padding:.065em .4em}.markdown-body code,.markdown-body pre{font-family:Menlo,Monaco,Consolas,Courier New,monospace}.markdown-body pre{overflow:auto;position:relative;line-height:1.75}.markdown-body pre>code{font-size:12px;padding:15px 12px;margin:0;word-break:normal;display:block;overflow-x:auto;color:#333;background:#f8f8f8}.markdown-body a{text-decoration:none;color:#0269c8;border-bottom:1px solid #d1e9ff}.markdown-body a:active,.markdown-body a:hover{color:#275b8c}.markdown-body table{display:inline-block!important;font-size:12px;width:auto;max-width:100%;overflow:auto;border:1px solid #f6f6f6}.markdown-body thead{background:#f6f6f6;color:#000;text-align:left}.markdown-body tr:nth-child(2n){background-color:#fcfcfc}.markdown-body td,.markdown-body th{padding:12px 7px;line-height:24px}.markdown-body td{min-width:120px}.markdown-body blockquote{color:#666;padding:1px 23px;margin:22px 0;border-left:4px solid #cbcbcb;background-color:#f8f8f8}.markdown-body blockquote:after{display:block;content:""}.markdown-body blockquote>p{margin:10px 0}.markdown-body ol,.markdown-body ul{padding-left:28px}.markdown-body ol li,.markdown-body ul li{margin-bottom:0;list-style:inherit}.markdown-body ol li .task-list-item,.markdown-body ul li .task-list-item{list-style:none}.markdown-body ol li .task-list-item ol,.markdown-body ol li .task-list-item ul,.markdown-body ul li .task-list-item ol,.markdown-body ul li .task-list-item ul{margin-top:0}.markdown-body ol ol,.markdown-body ol ul,.markdown-body ul ol,.markdown-body ul ul{margin-top:3px}.markdown-body ol li{padding-left:6px}@media (max-width:720px){.markdown-body h1{font-size:24px}.markdown-body h2{font-size:20px}.markdown-body h3{font-size:18px}}

作者 / 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 = "";
option java_multiple_files = true;

message Settings {
  int my_counter = 1;
}

创建 DataStore

您可以使用 Context.createDataStore() 扩展方法创建 DataStore:

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

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

object SettingsSerializer : Serializer {
    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 = 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 = context.createDataStore(
    name = "settings",
    migrations = listOf(SharedPreferencesMigration(context, "settings_preferences"))
)

当需要迁移至 Proto DataStore 时，您必须实现一个映射函数，用来定义如何将 SharedPreferences 所使用的键值对迁移到您所定义的 DataStore schema。

使用 Proto DataStore:

val settingsDataStore: DataStore = 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。