โปรเจ็กต์: /architecture/_project.yaml หนังสือ: /architecture/_book.yaml คำหลัก: datastore, architecture, api:JetpackDataStore คำอธิบาย: สำรวจคู่มือสถาปัตยกรรมแอปนี้ในไลบรารีเลเยอร์ข้อมูลเพื่อดูข้อมูลเกี่ยวกับ Preferences DataStore และ Proto DataStore, การตั้งค่า และอื่นๆ hide_page_heading: true

DataStore   ส่วนหนึ่งของ Android Jetpack

ลองใช้ Kotlin Multiplatform

Kotlin Multiplatform ช่วยให้แชร์เลเยอร์ข้อมูลกับแพลตฟอร์มอื่นๆ ได้ ดูวิธีตั้งค่าและทำงานกับ DataStore ใน KMP

ตั้งค่า DataStore สำหรับ KMP →

Jetpack DataStore เป็นโซลูชันพื้นที่เก็บข้อมูลที่ช่วยให้คุณจัดเก็บคู่คีย์-ค่าหรือออบเจ็กต์ที่มีการพิมพ์ด้วยบัฟเฟอร์โปรโตคอลได้ DataStore ใช้โครูทีนและ Flow ของ Kotlin เพื่อจัดเก็บข้อมูลแบบไม่พร้อมกัน อย่างสม่ำเสมอ และแบบทรานแซ็กชัน

หากใช้ SharedPreferences เพื่อจัดเก็บข้อมูล ให้พิจารณาย้ายข้อมูลไปยัง DataStore แทน

DataStore API

อินเทอร์เฟซ DataStore มี API ดังนี้

1. โฟลว์ที่ใช้เพื่ออ่านข้อมูลจาก DataStore ได้

   val data: Flow<T>
   

2. ฟังก์ชันสำหรับอัปเดตข้อมูลใน DataStore

   suspend updateData(transform: suspend (t) -> T)
   

การกำหนดค่า DataStore

หากต้องการจัดเก็บและเข้าถึงข้อมูลโดยใช้คีย์ ให้ใช้การติดตั้งใช้งาน Preferences DataStore ซึ่งไม่ต้องมีสคีมาที่กำหนดไว้ล่วงหน้า และไม่มี การรับประกันความปลอดภัยของประเภท มี API ที่คล้ายกับ SharedPreferences แต่ไม่มีข้อเสียที่เกี่ยวข้องกับค่ากำหนดที่แชร์

DataStore ช่วยให้คุณบันทึกคลาสที่กำหนดเองได้ โดยคุณต้องกำหนด สคีมาสำหรับข้อมูลและระบุ Serializer เพื่อแปลงข้อมูลเป็นรูปแบบที่คงอยู่ได้ คุณเลือกใช้ Protocol Buffers, JSON หรือกลยุทธ์การซีเรียลไลซ์อื่นๆ ได้

ตั้งค่า

หากต้องการใช้ Jetpack DataStore ในแอป ให้เพิ่มข้อมูลต่อไปนี้ลงในไฟล์ Gradle โดยขึ้นอยู่กับการติดตั้งใช้งานที่คุณต้องการใช้

Preferences DataStore

Add the following lines to the dependencies part of your gradle file:

    dependencies {
        // Preferences DataStore (SharedPreferences like APIs)
        implementation "androidx.datastore:datastore-preferences:1.1.7"

        // Alternatively - without an Android dependency.
        implementation "androidx.datastore:datastore-preferences-core:1.1.7"
    }
    

    dependencies {
        // Preferences DataStore (SharedPreferences like APIs)
        implementation("androidx.datastore:datastore-preferences:1.1.7")

        // Alternatively - without an Android dependency.
        implementation("androidx.datastore:datastore-preferences-core:1.1.7")
    }
    

To add optional RxJava support, add the following dependencies:

    dependencies {
        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.1.7"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-preferences-rxjava3:1.1.7"
    }
    

    dependencies {
        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.1.7")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-preferences-rxjava3:1.1.7")
    }
    

DataStore

Add the following lines to the dependencies part of your gradle file:

    dependencies {
        // Typed DataStore for custom data objects (for example, using Proto or JSON).
        implementation "androidx.datastore:datastore:1.1.7"

        // Alternatively - without an Android dependency.
        implementation "androidx.datastore:datastore-core:1.1.7"
    }
    

    dependencies {
        // Typed DataStore for custom data objects (for example, using Proto or JSON).
        implementation("androidx.datastore:datastore:1.1.7")

        // Alternatively - without an Android dependency.
        implementation("androidx.datastore:datastore-core:1.1.7")
    }
    

Add the following optional dependencies for RxJava support:

    dependencies {
        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.1.7"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-rxjava3:1.1.7"
    }
    

    dependencies {
        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.1.7")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-rxjava3:1.1.7")
    }
    

To serialize content, add dependencies for either Protocol Buffers or JSON serialization.

JSON serialization

To use JSON serialization, add the following to your Gradle file:

    plugins {
        id("org.jetbrains.kotlin.plugin.serialization") version "2.2.20"
    }

    dependencies {
        implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0"
    }
    

    plugins {
        id("org.jetbrains.kotlin.plugin.serialization") version "2.2.20"
    }

    dependencies {
        implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
    }
    

Protobuf serialization

To use Protobuf serialization, add the following to your Gradle file:

    plugins {
        id("com.google.protobuf") version "0.9.5"
    }
    dependencies {
        implementation "com.google.protobuf:protobuf-kotlin-lite:4.32.1"

    }

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

    plugins {
        id("com.google.protobuf") version "0.9.5"
    }
    dependencies {
        implementation("com.google.protobuf:protobuf-kotlin-lite:4.32.1")
    }

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

ใช้ DataStore อย่างถูกต้อง

โปรดคำนึงถึงกฎต่อไปนี้เสมอเพื่อให้ใช้ DataStore ได้อย่างถูกต้อง

1. อย่าสร้างอินสแตนซ์ของ DataStore มากกว่า 1 รายการสำหรับไฟล์ที่กำหนดใน กระบวนการเดียวกัน การทำเช่นนี้อาจทำให้ฟังก์ชันการทำงานทั้งหมดของ DataStore หยุดทำงาน หากมี DataStore หลายรายการที่ใช้งานอยู่สำหรับไฟล์หนึ่งๆ ในกระบวนการเดียวกัน DataStore จะแสดงข้อผิดพลาด IllegalStateException เมื่ออ่านหรืออัปเดตข้อมูล

2. ประเภททั่วไปของ DataStore<T> ต้องเปลี่ยนแปลงไม่ได้ การเปลี่ยนแปลงประเภท ที่ใช้ใน DataStore จะทำให้ความสอดคล้องที่ DataStore มีอยู่ไม่ถูกต้อง และ อาจทำให้เกิดข้อบกพร่องที่ร้ายแรงและตรวจจับได้ยาก เราขอแนะนำให้คุณใช้ บัฟเฟอร์โปรโตคอล ซึ่งจะช่วยให้มั่นใจได้ถึงความคงที่ API ที่ชัดเจน และการ ซีเรียลไลซ์ที่มีประสิทธิภาพ

3. อย่าใช้ SingleProcessDataStore และ MultiProcessDataStore ร่วมกันสำหรับไฟล์เดียวกัน หากต้องการเข้าถึง DataStore จากกระบวนการมากกว่า 1 รายการ คุณต้องใช้ MultiProcessDataStore

คำจำกัดความของข้อมูล

val EXAMPLE_COUNTER = intPreferencesKey("example_counter")

@Serializable
data class Settings(
    val exampleCounter: Int
)

object SettingsSerializer : Serializer<Settings> {

    override val defaultValue: Settings = Settings(exampleCounter = 0)

    override suspend fun readFrom(input: InputStream): Settings =
        try {
            Json.decodeFromString<Settings>(
                input.readBytes().decodeToString()
            )
        } catch (serialization: SerializationException) {
            throw CorruptionException("Unable to read Settings", serialization)
        }

    override suspend fun writeTo(t: Settings, output: OutputStream) {
        output.write(
            Json.encodeToString(t)
                .encodeToByteArray()
        )
    }
}

syntax = "proto3";

option java_package = "com.example.datastore.snippets.proto";
option java_multiple_files = true;

message Settings {
  int32 example_counter = 1;
}

object SettingsSerializer : Serializer<Settings> {
    override val defaultValue: Settings = Settings.getDefaultInstance()

    override suspend fun readFrom(input: InputStream): Settings {
        try {
            return Settings.parseFrom(input)
        } catch (exception: InvalidProtocolBufferException) {
            throw CorruptionException("Cannot read proto.", exception)
        }
    }

    override suspend fun writeTo(t: Settings, output: OutputStream) {
        return t.writeTo(output)
    }
}

สร้าง DataStore

คุณต้องระบุชื่อไฟล์ที่ใช้เพื่อคงข้อมูลไว้

// At the top level of your kotlin file:
val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "settings")

val Context.dataStore: DataStore<Settings> by dataStore(
    fileName = "settings.json",
    serializer = SettingsSerializer,
)

val Context.dataStore: DataStore<Settings> by dataStore(
    fileName = "settings.pb",
    serializer = SettingsSerializer,
)

อ่านจาก DataStore

คุณต้องระบุชื่อไฟล์ที่ใช้เพื่อคงข้อมูลไว้

fun counterFlow(): Flow<Int> = context.dataStore.data.map { preferences ->
    preferences[EXAMPLE_COUNTER] ?: 0
}

fun counterFlow(): Flow<Int> = context.dataStore.data.map { settings ->
    settings.exampleCounter
}

fun counterFlow(): Flow<Int> = context.dataStore.data.map { settings ->
    settings.exampleCounter
}

เขียนไปยัง DataStore

DataStore มีฟังก์ชัน updateData() ที่อัปเดตออบเจ็กต์ที่จัดเก็บไว้แบบธุรกรรม updateData จะแสดงสถานะปัจจุบันของข้อมูลเป็น อินสแตนซ์ของประเภทข้อมูล และอัปเดตข้อมูลแบบทรานแซกชันในการดำเนินการอ่าน-เขียน-แก้ไขแบบอะตอมมิก โค้ดทั้งหมดในบล็อก updateData จะถือเป็นธุรกรรมเดียว

suspend fun incrementCounter() {
    context.dataStore.updateData {
        it.toMutablePreferences().also { preferences ->
            preferences[EXAMPLE_COUNTER] = (preferences[EXAMPLE_COUNTER] ?: 0) + 1
        }
    }
}

suspend fun incrementCounter() {
    context.dataStore.updateData { settings ->
        settings.copy(exampleCounter = settings.exampleCounter + 1)
    }
}

suspend fun incrementCounter() {
    context.dataStore.updateData { settings ->
        settings.copy { exampleCounter = exampleCounter + 1 }
    }
}

ตัวอย่างการเขียน

คุณสามารถรวมฟังก์ชันเหล่านี้ไว้ในคลาสเดียวและใช้ในแอป Compose ได้

val context = LocalContext.current
val coroutineScope = rememberCoroutineScope()
val preferencesDataStore = remember(context) { PreferencesDataStore(context) }

// Display counter value.
val exampleCounter by preferencesDataStore.counterFlow()
    .collectAsState(initial = 0, coroutineScope.coroutineContext)
Text(
    text = "Counter $exampleCounter",
    fontSize = 25.sp
)

// Update the counter.
Button(
    onClick = {
        coroutineScope.launch { preferencesDataStore.incrementCounter() }
    }
) {
    Text("increment")
}

val context = LocalContext.current
val coroutineScope = rememberCoroutineScope()
val jsonDataStore = remember(context) { JsonDataStore(context) }

// Display counter value.
val exampleCounter by jsonDataStore.counterFlow()
    .collectAsState(initial = 0, coroutineScope.coroutineContext)
Text(
    text = "Counter $exampleCounter",
    fontSize = 25.sp
)

// Update the counter.
Button(onClick = { coroutineScope.launch { jsonDataStore.incrementCounter() } }) {
    Text("increment")
}

val context = LocalContext.current
val coroutineScope = rememberCoroutineScope()
val protoDataStore = remember(context) { ProtoDataStore(context) }

// Display counter value.
val exampleCounter by protoDataStore.counterFlow()
    .collectAsState(initial = 0, coroutineScope.coroutineContext)
Text(
    text = "Counter $exampleCounter",
    fontSize = 25.sp
)

// Update the counter.
Button(onClick = { coroutineScope.launch { protoDataStore.incrementCounter() } }) {
    Text("increment")
}

ใช้ DataStore ในโค้ดแบบซิงโครนัส

ประโยชน์หลักอย่างหนึ่งของ DataStore คือ API แบบอะซิงโครนัส แต่การเปลี่ยนโค้ดโดยรอบให้เป็นแบบอะซิงโครนัสอาจทำไม่ได้เสมอไป กรณีนี้อาจเกิดขึ้นหากคุณทำงานกับโค้ดเบสที่มีอยู่ซึ่งใช้ I/O ของดิสก์แบบซิงโครนัส หรือหากคุณมี Dependency ที่ไม่ได้ให้ API แบบอะซิงโครนัส

โคโรทีน Kotlin มีตัวสร้างโคโรทีน runBlocking() เพื่อช่วย เชื่อมช่องว่างระหว่างโค้ดแบบซิงโครนัสและแบบอะซิงโครนัส คุณใช้ runBlocking()เพื่ออ่านข้อมูลจาก DataStore แบบซิงโครนัสได้ RxJava มีเมธอดที่บล็อกใน Flowable โค้ดต่อไปนี้จะบล็อกเธรดที่เรียกใช้ จนกว่า DataStore จะแสดงข้อมูล

val exampleData = runBlocking { context.dataStore.data.first() }

Settings settings = dataStore.data().blockingFirst();

การดำเนินการ I/O แบบซิงโครนัสในเทรด UI อาจทำให้เกิด ANR หรือ UI ที่ไม่ตอบสนอง คุณสามารถลดปัญหาเหล่านี้ได้โดยการโหลดข้อมูลจาก DataStore ล่วงหน้าแบบไม่พร้อมกัน ดังนี้

override fun onCreate(savedInstanceState: Bundle?) {
    lifecycleScope.launch {
        context.dataStore.data.first()
        // You should also handle IOExceptions here.
    }
}

dataStore.data().first().subscribe();

ด้วยวิธีนี้ DataStore จะอ่านข้อมูลแบบไม่พร้อมกันและแคชข้อมูลไว้ในหน่วยความจำ การอ่านแบบซิงโครนัสในภายหลังโดยใช้ runBlocking() อาจเร็วกว่าหรืออาจหลีกเลี่ยงการดำเนินการ I/O ของดิสก์ ทั้งหมดได้หากการอ่านครั้งแรกเสร็จสมบูรณ์แล้ว

ใช้ DataStore ในโค้ดแบบหลายกระบวนการ

คุณสามารถกําหนดค่า DataStore เพื่อเข้าถึงข้อมูลเดียวกันในกระบวนการต่างๆ โดยมีพร็อพเพอร์ตี้ความสอดคล้องของข้อมูลเดียวกันกับที่อยู่ภายในกระบวนการเดียว โดยเฉพาะอย่างยิ่ง DataStore มีบริการต่อไปนี้

• การอ่านจะแสดงเฉพาะข้อมูลที่บันทึกลงในดิสก์เท่านั้น
• ความสอดคล้องแบบ Read-After-Write
• ระบบจะจัดลำดับการเขียน
• การอ่านจะไม่ถูกบล็อกโดยการเขียน

ลองพิจารณาแอปพลิเคชันตัวอย่างที่มีบริการและกิจกรรมซึ่งบริการ ทำงานในกระบวนการแยกต่างหากและอัปเดต DataStore เป็นระยะ

ตัวอย่างนี้ใช้ที่เก็บข้อมูล JSON แต่คุณจะใช้ที่เก็บข้อมูลการตั้งค่าหรือที่เก็บข้อมูล Proto ก็ได้

@Serializable
data class Time(
    val lastUpdateMillis: Long
)

ซีเรียลไลเซอร์จะบอก DataStore วิธีอ่านและเขียนประเภทข้อมูล ตรวจสอบว่าคุณได้ระบุมูลค่าเริ่มต้นสำหรับ Serializer ที่จะใช้ในกรณีที่ยังไม่มีการสร้างไฟล์ ตัวอย่างการใช้งานโดยใช้ kotlinx.serialization มีดังนี้

object TimeSerializer : Serializer<Time> {

    override val defaultValue: Time = Time(lastUpdateMillis = 0L)

    override suspend fun readFrom(input: InputStream): Time =
        try {
            Json.decodeFromString<Time>(
                input.readBytes().decodeToString()
            )
        } catch (serialization: SerializationException) {
            throw CorruptionException("Unable to read Time", serialization)
        }

    override suspend fun writeTo(t: Time, output: OutputStream) {
        output.write(
            Json.encodeToString(t)
                .encodeToByteArray()
        )
    }
}

หากต้องการใช้ DataStore ในกระบวนการต่างๆ คุณต้องสร้างออบเจ็กต์ DataStore โดยใช้ MultiProcessDataStoreFactory สำหรับทั้งโค้ดแอปและโค้ดบริการ

val dataStore = MultiProcessDataStoreFactory.create(
    serializer = TimeSerializer,
    produceFile = {
        File("${context.cacheDir.path}/time.pb")
    },
    corruptionHandler = null
)

เพิ่มโค้ดต่อไปนี้ใน AndroidManifiest.xml

<service
    android:name=".TimestampUpdateService"
    android:process=":my_process_id" />

บริการจะเรียกใช้ updateLastUpdateTime() เป็นระยะๆ ซึ่งจะเขียนไปยัง Datastore โดยใช้ updateData

suspend fun updateLastUpdateTime() {
    dataStore.updateData { time ->
        time.copy(lastUpdateMillis = System.currentTimeMillis())
    }
}

แอปจะอ่านค่าที่บริการเขียนโดยใช้โฟลว์ข้อมูลต่อไปนี้

fun timeFlow(): Flow<Long> = dataStore.data.map { time ->
    time.lastUpdateMillis
}

ตอนนี้เราสามารถรวมฟังก์ชันทั้งหมดนี้ไว้ในคลาสที่ชื่อ MultiProcessDataStore และใช้ในแอปได้แล้ว

รหัสบริการมีดังนี้

class TimestampUpdateService : Service() {
    val serviceScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
    val multiProcessDataStore by lazy { MultiProcessDataStore(applicationContext) }


    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        serviceScope.launch {
            while (true) {
                multiProcessDataStore.updateLastUpdateTime()
                delay(1000)
            }
        }
        return START_NOT_STICKY
    }

    override fun onDestroy() {
        super.onDestroy()
        serviceScope.cancel()
    }
}

และโค้ดของแอป

val context = LocalContext.current
val coroutineScope = rememberCoroutineScope()
val multiProcessDataStore = remember(context) { MultiProcessDataStore(context) }

// Display time written by other process.
val lastUpdateTime by multiProcessDataStore.timeFlow()
    .collectAsState(initial = 0, coroutineScope.coroutineContext)
Text(
    text = "Last updated: $lastUpdateTime",
    fontSize = 25.sp
)

DisposableEffect(context) {
    val serviceIntent = Intent(context, TimestampUpdateService::class.java)
    context.startService(serviceIntent)
    onDispose {
        context.stopService(serviceIntent)
    }
}

คุณสามารถใช้การแทรกทรัพยากร Dependency ของ Hilt เพื่อให้อินสแตนซ์ DataStore ไม่ซ้ำกันต่อกระบวนการ

@Provides
@Singleton
fun provideDataStore(@ApplicationContext context: Context): DataStore<Settings> =
   MultiProcessDataStoreFactory.create(...)

จัดการไฟล์ที่เสียหาย

ในบางกรณีที่เกิดขึ้นไม่บ่อยนัก ไฟล์ที่คงอยู่บนดิสก์ของ DataStore อาจเสียหาย โดยค่าเริ่มต้น DataStore จะไม่กู้คืนจากการเสียหายโดยอัตโนมัติ และการพยายามอ่านจาก DataStore จะทำให้ระบบแสดงCorruptionException

DataStore มี API ตัวแฮนเดิลความเสียหายที่จะช่วยให้คุณกู้คืนได้อย่างราบรื่น ในสถานการณ์ดังกล่าว และหลีกเลี่ยงการทิ้งข้อยกเว้น เมื่อกำหนดค่าแล้ว ตัวแฮนเดิลการเสียหายจะแทนที่ไฟล์ที่เสียหายด้วยไฟล์ใหม่ที่มี ค่าเริ่มต้นที่กำหนดไว้ล่วงหน้า

หากต้องการตั้งค่าแฮนเดิลนี้ ให้ระบุ corruptionHandler เมื่อสร้างอินสแตนซ์ DataStore ใน by dataStore() หรือในเมธอด DataStoreFactory ของ Factory

val dataStore: DataStore<Settings> = DataStoreFactory.create(
   serializer = SettingsSerializer(),
   produceFile = {
       File("${context.cacheDir.path}/myapp.preferences_pb")
   },
   corruptionHandler = ReplaceFileCorruptionHandler { Settings(lastUpdate = 0) }
)

แสดงความคิดเห็น

แชร์ความคิดเห็นและไอเดียกับเราผ่านแหล่งข้อมูลต่อไปนี้

เครื่องมือติดตามปัญหา:

รายงานปัญหาเพื่อให้เราแก้ไขข้อบกพร่องได้

แหล่งข้อมูลเพิ่มเติม

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Jetpack DataStore ได้จากแหล่งข้อมูลเพิ่มเติมต่อไปนี้

ตัวอย่าง

บล็อก

• ควรจัดเก็บข้อมูลด้วย Jetpack DataStore

Codelabs

• การทำงานกับ Preferences DataStore
• การทำงานกับ Proto DataStore