Project: /architecture/_project.yaml Book: /architecture/_book.yaml keywords: datastore, architecture, api:JetpackDataStore description: Explore this app architecture guide on data layer libraries to learn about Preferences DataStore and Proto DataStore, Setup, and more. hide_page_heading: true

‫DataStore   חלק מ-Android Jetpack.

כדאי לנסות את Kotlin Multiplatform

‫Kotlin Multiplatform מאפשרת לשתף את שכבת הנתונים עם פלטפורמות אחרות. איך מגדירים את DataStore ב-KMP ואיך עובדים איתו

הגדרה של DataStore ל-KMP‏ →

‫Jetpack DataStore הוא פתרון לאחסון נתונים שמאפשר לכם לאחסן זוגות של מפתח/ערך או אובייקטים מוקלדים באמצעות מאגרי פרוטוקולים. ‫DataStore משתמש ב-Kotlin coroutines וב-Flow כדי לאחסן נתונים באופן אסינכרוני, עקבי וטרנזקציונלי.

אם אתם משתמשים ב-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

מוסיפים את השורות הבאות לחלק של יחסי התלות בקובץ gradle:

    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")
    }
    

כדי להוסיף תמיכה אופציונלית ב-RxJava, מוסיפים את יחסי התלות הבאים:

    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

מוסיפים את השורות הבאות לחלק של יחסי התלות בקובץ gradle:

    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")
    }
    

מוסיפים את יחסי התלות האופציונליים הבאים לתמיכה ב-RxJava:

    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")
    }
    

כדי לבצע סריאליזציה של תוכן, מוסיפים תלות בסריאליזציה של Protocol Buffers או JSON.

JSON serialization

כדי להשתמש בסריאליזציה של JSON, מוסיפים את הקוד הבא לקובץ Gradle:

    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

כדי להשתמש בסריאליזציה של Protobuf, מוסיפים את השורה הבאה לקובץ Gradle:

    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 עבור קובץ נתון באותו תהליך. פעולה כזו עלולה לשבור את כל הפונקציונליות של DataStore. אם יש כמה DataStore פעילים לקובץ נתון באותו תהליך, DataStore יחזיר IllegalStateException כשקוראים או מעדכנים נתונים.

2. הסוג הגנרי של DataStore<T> חייב להיות בלתי ניתן לשינוי. שינוי של סוג שמשמש ב-DataStore מבטל את העקביות ש-DataStore מספק, ויוצר באגים שעלולים להיות חמורים וקשים לאיתור. מומלץ להשתמש ב-protocol buffers, שעוזרים להבטיח אי-שינוי, API ברור וסדרות יעילות.

3. אל תערבבו בין שימושים במאפיינים SingleProcessDataStore ו-MultiProcessDataStore באותו קובץ. אם אתם מתכוונים לגשת אל DataStore מיותר מתהליך אחד, אתם צריכים להשתמש ב-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)
    }
}

יצירת מאגר נתונים

צריך לציין שם לקובץ שמשמש לשמירת הנתונים.

// 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 האסינכרוני, אבל לא תמיד אפשר לשנות את הקוד שמסביב כך שיהיה אסינכרוני. זה יכול לקרות אם אתם עובדים עם בסיס קוד קיים שמשתמש בקלט/פלט סינכרוני בדיסק, או אם יש לכם תלות שלא מספקת API אסינכרוני.

קורוטינות של Kotlin מספקות את כלי הקורוטינות runBlocking() כדי לגשר על הפער בין קוד סינכרוני לקוד אסינכרוני. אפשר להשתמש ב-runBlocking() כדי לקרוא נתונים מ-DataStore באופן סינכרוני. ‫RxJava מציעה שיטות חסימה ב-Flowable. בלוק הקוד הבא חוסם את השרשור שקורא עד ש-DataStore מחזיר נתונים:

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

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

ביצוע פעולות קלט/פלט סינכרוניות בשרשור ה-UI עלול לגרום לשגיאות ANR או לממשק משתמש לא מגיב. כדי לצמצם את הבעיות האלה, אפשר לטעון מראש את הנתונים מ-DataStore באופן אסינכרוני:

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

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

בדרך הזו, DataStore קורא את הנתונים באופן אסינכרוני ומאחסן אותם במטמון בזיכרון. קריאות סינכרוניות מאוחרות יותר באמצעות runBlocking() עשויות להיות מהירות יותר או להימנע לחלוטין מפעולת קלט/פלט בדיסק אם הקריאה הראשונית הושלמה.

שימוש ב-DataStore בקוד מרובה תהליכים

אתם יכולים להגדיר את DataStore כך שתהיה לו גישה לאותם נתונים בתהליכים שונים, עם אותן תכונות של עקביות נתונים כמו בתהליך יחיד. בפרט, DataStore מספק:

• פעולות קריאה מחזירות רק את הנתונים שנשמרו בדיסק.
• עקביות של קריאה אחרי כתיבה.
• פעולות הכתיבה מבוצעות ברצף.
• קריאות אף פעם לא נחסמות על ידי כתיבות.

ניקח לדוגמה אפליקציה עם שירות ופעילות שבה השירות פועל בתהליך נפרד ומעדכן את מאגר הנתונים באופן תקופתי.

בדוגמה הזו נעשה שימוש בחנות נתונים של JSON, אבל אפשר להשתמש גם בחנות נתונים של העדפות או של פרוטו.

@Serializable
data class Time(
    val lastUpdateMillis: Long
)

ספריית סריאליזציה אומרת ל-DataStore איך לקרוא ולכתוב את סוג הנתונים. חשוב לוודא שכוללים ערך ברירת מחדל עבור הסריאליזציה, שישמש אם עדיין לא נוצר קובץ. הדוגמה הבאה היא הטמעה באמצעות 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(), שכותב למאגר הנתונים באמצעות 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)
    }
}

אפשר להשתמש בהזרקת תלות של Hilt כדי שמופע DataStore יהיה ייחודי לכל תהליך:

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

טיפול בקבצים פגומים

יש מקרים נדירים שבהם קובץ מתמשך בדיסק של DataStore עלול להינזק. כברירת מחדל, DataStore לא משחזר אוטומטית נתונים פגומים, וניסיונות לקרוא ממנו יגרמו למערכת להציג את השגיאה CorruptionException.

‫DataStore כולל API לטיפול בפגיעה בנתונים, שיכול לעזור לכם לבצע שחזור בצורה חלקה בתרחיש כזה, ולמנוע את השגיאה. אם מוגדר טיפול בשחיתות, הקובץ הפגום מוחלף בקובץ חדש שמכיל ערך ברירת מחדל מוגדר מראש.

כדי להגדיר את ה-handler הזה, צריך לספק corruptionHandler כשיוצרים את מופע DataStore ב-by dataStore() או בשיטת factory‏ DataStoreFactory:

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