android-data-persistence（安卓数据持久化）

Platform Notes

• Optional helper plugins may help in some environments, but they must not be treated as required for this skill.

Android Data Persistence

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Use When

• Android data persistence standards with Room as primary local storage and custom API backends for cloud sync. Covers SharedPreferences, DataStore, Room (entities, DAOs, relations, migrations), file storage, offline-first architecture, and...
• The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

Do Not Use When

• The task is unrelated to android-data-persistence or would be better handled by a more specific companion skill.
• The request only needs a trivial answer and none of this skill's constraints or references materially help.

Required Inputs

• Gather relevant project context, constraints, and the concrete problem to solve; load references only as needed.
• Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

Workflow

• Read this SKILL.md first, then load only the referenced deep-dive files that are necessary for the task.
• Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
• Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

Quality Standards

• Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
• Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
• Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

Anti-Patterns

• Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
• Loading every reference file by default instead of using progressive disclosure.

Outputs

• A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
• Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
• References used, companion skills, or follow-up actions when they materially improve execution.

Evidence Produced

References

• Use the references/ directory for deep detail after reading the core workflow below.

Overview

Our apps use Room for local persistence and custom REST API backends for cloud data. This skill covers every storage method and when to use each.

Android 10+ required.

Architecture: Offline-first with API sync via Repository pattern.

Offline-First is MANDATORY. Every app we build MUST work fully offline. Users in areas with poor or intermittent network must never be blocked. Sync happens automatically when connectivity returns — the user must never know or notice. See references/api-sync-patterns.md for the complete sync engine with guaranteed no-duplicates, no-missing-transactions.

Room Deep Reference: For full Room API (FTS4, views, migrations, encryption, paging, conflict resolution, testing), use the android-room skill alongside this one.

Backend Environments: APIs run on Windows dev (MySQL 8.4.7), Ubuntu staging (MySQL 8.x), Debian production (MySQL 8.x). Use Gradle build flavors for environment-specific base URLs. All backends use utf8mb4_unicode_ci collation.

Icon Policy: If any UI code is included, use custom PNG icons and maintain PROJECT_ICONS.md (see android-custom-icons).

Report Table Policy: If persistence examples include report UIs that can exceed 25 rows, use table layouts (see android-report-tables).

UI (Compose) → ViewModel → Repository → Room (local) + API (remote)

Storage Decision Guide

Quick Decision

"I need to store..."
├── Settings/tokens/flags → DataStore (Preferences)
├── A single file → Internal storage
├── Structured local data → Room
├── Data from our API → Room cache + Repository sync
└── User-generated media → Internal files + API upload

Quick Reference

Room: The Primary Local Database

Room is our standard for all structured local data. It provides compile-time SQL verification, lifecycle-aware queries, and clean integration with ViewModels.

Three Core Components

@Entity       → Defines a database table (data class)
@Dao          → Defines operations (interface)
@Database     → Connects entities and DAOs (abstract class)

Entity (Table Definition)

@Entity(tableName = "products")
data class ProductEntity(
    @PrimaryKey
    @ColumnInfo(name = "product_id")
    val productId: String,

    @ColumnInfo(name = "name")
    val name: String,

    @ColumnInfo(name = "price")
    val price: Double,

    @ColumnInfo(name = "category_id")
    val categoryId: String,

    @ColumnInfo(name = "last_synced")
    val lastSynced: Long = System.currentTimeMillis()
)

DAO (Data Access)

@Dao
interface ProductDao {
    @Query("SELECT * FROM products ORDER BY name ASC")
    fun getAllProducts(): Flow<List<ProductEntity>>

    @Query("SELECT * FROM products WHERE product_id = :id")
    suspend fun getById(id: String): ProductEntity?

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertAll(products: List<ProductEntity>)

    @Update
    suspend fun update(product: ProductEntity)

    @Delete
    suspend fun delete(product: ProductEntity)

    @Query("DELETE FROM products")
    suspend fun deleteAll()
}

Database

@Database(
    entities = [ProductEntity::class, CategoryEntity::class],
    version = 1,
    exportSchema = true
)
@TypeConverters(Converters::class)
abstract class AppDatabase : RoomDatabase() {
    abstract fun productDao(): ProductDao
    abstract fun categoryDao(): CategoryDao
}

Hilt Module for Database

@Module
@InstallIn(SingletonComponent::class)
object DatabaseModule {
    @Provides
    @Singleton
    fun provideDatabase(@ApplicationContext context: Context): AppDatabase {
        return Room.databaseBuilder(
            context,
            AppDatabase::class.java,
            "app_database"
        )
        .addMigrations(MIGRATION_1_2)
        .build()
    }

    @Provides
    fun provideProductDao(database: AppDatabase): ProductDao = database.productDao()
}

Repository Pattern (Room + API)

The Repository is the single source of truth for data:

class ProductRepository @Inject constructor(
    private val productDao: ProductDao,
    private val apiService: ProductApiService
) {
    // Local data as Flow (always fresh from Room)
    fun getProducts(): Flow<List<Product>> =
        productDao.getAllProducts().map { entities ->
            entities.map { it.toDomain() }
        }

    // SIMPLIFIED EXAMPLE — for production offline-first repository with PendingActionDao,
    // SyncCursorDao, and no-duplicate/no-missing-transaction guarantees, see:
    // references/api-sync-patterns.md Section 3 (ProductRepository)

    // Sync: fetch from API, save to Room
    suspend fun refreshProducts(): Result<Unit> {
        return try {
            val response = apiService.getProducts()
            productDao.insertAll(response.map { it.toEntity() })
            Result.success(Unit)
        } catch (e: Exception) {
            Result.failure(e)
        }
    }

    // Create: save locally + push to API
    suspend fun createProduct(product: Product): Result<Product> {
        return try {
            val response = apiService.createProduct(product.toDto())
            val entity = response.toEntity()
            productDao.insertAll(listOf(entity))
            Result.success(entity.toDomain())
        } catch (e: Exception) {
            Result.failure(e)
        }
    }
}

ViewModel Integration

@HiltViewModel
class ProductViewModel @Inject constructor(
    private val repository: ProductRepository
) : ViewModel() {

    val products = repository.getProducts()
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())

    private val _isRefreshing = MutableStateFlow(false)
    val isRefreshing = _isRefreshing.asStateFlow()

    fun refresh() {
        viewModelScope.launch {
            _isRefreshing.value = true
            repository.refreshProducts()
            _isRefreshing.value = false
        }
    }
}

DataStore (Settings & Preferences)

Prefer DataStore over SharedPreferences for new code:

// Define keys
object PrefsKeys {
    val DARK_MODE = booleanPreferencesKey("dark_mode")
    val AUTH_TOKEN = stringPreferencesKey("auth_token")
    val SORT_ORDER = stringPreferencesKey("sort_order")
}

// Read
val darkMode: Flow<Boolean> = context.dataStore.data.map { prefs ->
    prefs[PrefsKeys.DARK_MODE] ?: false
}

// Write
suspend fun setDarkMode(enabled: Boolean) {
    context.dataStore.edit { prefs ->
        prefs[PrefsKeys.DARK_MODE] = enabled
    }
}

TypeConverters (Custom Column Types)

class Converters {
    @TypeConverter
    fun fromTimestamp(value: Long?): Date? = value?.let { Date(it) }

    @TypeConverter
    fun dateToTimestamp(date: Date?): Long? = date?.time

    @TypeConverter fun fromStringList(value: String?): List<String> =
        if (value.isNullOrBlank()) emptyList() else value.split("\u001F")
    @TypeConverter fun toStringList(list: List<String>): String = list.joinToString("\u001F")
    // Using \u001F (unit separator) — commas in values corrupt comma-delimited lists
}

Migrations

Always provide migration paths when changing schema:

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE products ADD COLUMN is_active INTEGER NOT NULL DEFAULT 1")
    }
}

// Register in database builder
Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
    .addMigrations(MIGRATION_1_2, MIGRATION_2_3)
    .build()

Never use fallbackToDestructiveMigration() in production.

Data Layer Mapping

Always separate API DTOs, Room entities, and domain models:

// API DTO (what the server sends)
data class ProductDto(val id: String, val name: String, val price: Double)

// Room Entity (what's stored locally)
@Entity(tableName = "products")
data class ProductEntity(
    @PrimaryKey val productId: String,
    val name: String,
    val price: Double,
    val lastSynced: Long
)

// Domain Model (what the UI uses)
data class Product(val id: String, val name: String, val price: Double)

// Mappers
fun ProductDto.toEntity() = ProductEntity(id, name, price, System.currentTimeMillis())
fun ProductEntity.toDomain() = Product(productId, name, price)
fun Product.toDto() = ProductDto(id, name, price)

Patterns & Anti-Patterns

DO

• Use Room for all structured local data
• Use DataStore for key-value preferences (not SharedPreferences)
• Use Repository pattern as single source of truth
• Separate DTOs, entities, and domain models
• Return Flow from DAOs for reactive UI updates
• Provide proper migrations for schema changes
• Use onConflict = REPLACE for API-synced data
• Export Room schema for migration testing

DON'T

• Access DAOs directly from ViewModels (use Repository)
• Store large blobs in Room (use file storage)
• Use fallbackToDestructiveMigration() in production
• Mix network calls with database operations outside Repository
• Store sensitive data unencrypted (use EncryptedSharedPreferences)
• Skip the entity-to-domain mapping (couples UI to database schema)
• Run Room queries on the main thread

Integration with Other Skills

android-room → Deep Room API (entities, FTS4, views, migrations, SQLCipher, paging)
      ↓
android-data-persistence → Offline sync engine (THIS SKILL)
      ↓
android-development → Clean Architecture, Hilt DI, MVVM
      ↓
android-tdd → DAO tests, migration tests, SyncWorker tests

Key integrations:

• android-room: All Room patterns — always load with this skill for full coverage
• android-tdd: Test DAOs with in-memory DB, SyncWorker with TestWorkerFactory
• api-error-handling: Error patterns for sync failures and HTTP 409 conflicts

References

• Room Guide: developer.android.com/training/data-storage/room
• DataStore: developer.android.com/topic/libraries/architecture/datastore
• Architecture Samples: github.com/android/architecture-samples