原生移动开发 / 系统课时

迁移、缓存与离线优先

迁移、缓存与离线优先

这一节解决两个最容易破坏本地体验的问题:数据库升级时保住旧数据,以及网络不稳定时仍让页面读取可靠缓存。最终结构是“界面始终读本地库,网络只负责刷新本地库”。

学习目标

  • 为 Room 版本升级编写可追踪、可验证的迁移
  • 让本地数据库成为离线优先读取的单一事实来源
  • 设计安全的缓存刷新、失败保留和后续同步边界

把本地库设为读取事实来源

离线优先不等于“没网时才读缓存”。更稳定的做法是:UI 始终观察 Room,Repository 在合适时机请求网络,成功后把新数据事务性写入 Room。网络失败只影响“数据是否足够新”,不应把已经存在的本地数据一起清掉。

离线优先的本地事实来源与刷新链路

这种结构让在线和离线使用同一条读取路径。是否联网只决定 Repository 能不能得到更新数据,而不是决定 UI 改用另一套数据源,因此页面状态更容易保持一致。

升级数据库时显式迁移

假设版本 1 的 tasks 表只有 id 和 title,版本 2 新增非空 note 字段。旧设备上已经存在数据,不能直接修改实体后提高版本号而不提供迁移路径。

下面是片段示例,展示 1 → 2 的手动迁移。给非空列提供默认值,才能让已有行顺利补齐新字段。

kotlin
import android.content.Context
import androidx.room.Database
import androidx.room.Entity
import androidx.room.PrimaryKey
import androidx.room.Room
import androidx.room.RoomDatabase
import androidx.room.migration.Migration
import androidx.sqlite.db.SupportSQLiteDatabase

@Entity(tableName = "tasks")
data class TaskEntity(
    @PrimaryKey val id: Long,
    val title: String,
    val note: String
)

@Database(
    entities = [TaskEntity::class],
    version = 2,
    exportSchema = true
)
abstract class AppDatabase : RoomDatabase()

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(db: SupportSQLiteDatabase) {
        // 已有记录需要一个合法的非空默认值。
        db.execSQL(
            "ALTER TABLE tasks ADD COLUMN note TEXT NOT NULL DEFAULT ''"
        )
    }
}

fun buildDatabase(context: Context): AppDatabase =
    Room.databaseBuilder(
        context,
        AppDatabase::class.java,
        "app.db"
    )
        .addMigrations(MIGRATION_1_2)
        .build()

预期结果

text
安装过版本 1 的用户升级后可以继续打开数据库。
原有 tasks 记录保留,新增 note 列的旧记录值为 ""。
如果缺少 1 → 2 的迁移路径,数据库打开阶段会失败,而不是静默猜测表结构。

生产数据通常不应依赖破坏性迁移,因为它可能通过重建表来解决版本不匹配,同时丢掉用户数据。更稳妥的做法是保留导出的 schema 历史,并测试每一条仍受支持的升级路径。

缓存刷新只在成功后覆盖本地数据

刷新时最危险的顺序是“先清空 Room,再发网络请求”:只要请求失败,用户就从“旧数据”退化成“空白页”。应先拿到完整且可接受的远端结果,再用事务更新本地表。

下面的片段让 Repository 只向上暴露 Room 的 Flow;网络响应成功后才替换缓存,失败时原有数据保持不变。

kotlin
import androidx.room.Dao
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.Query
import androidx.room.Transaction
import kotlinx.coroutines.flow.Flow

data class NetworkTask(
    val id: Long,
    val title: String,
    val note: String
)

interface TaskApi {
    suspend fun getTasks(): List<NetworkTask>
}

@Dao
abstract class TaskDao {
    @Query("SELECT * FROM tasks ORDER BY id")
    abstract fun observeAll(): Flow<List<TaskEntity>>

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    abstract suspend fun insertAll(items: List<TaskEntity>)

    @Query("DELETE FROM tasks")
    abstract suspend fun deleteAll()

    @Transaction
    open suspend fun replaceAll(items: List<TaskEntity>) {
        deleteAll()
        insertAll(items)
    }
}

class OfflineFirstTaskRepository(
    private val api: TaskApi,
    private val dao: TaskDao
) {
    fun observeTasks(): Flow<List<TaskEntity>> = dao.observeAll()

    suspend fun refresh(): Result<Unit> = runCatching {
        // 先完成网络读取,失败时不会动本地缓存。
        val remote = api.getTasks()
        val local = remote.map {
            TaskEntity(id = it.id, title = it.title, note = it.note)
        }
        dao.replaceAll(local)
    }
}

预期结果

text
网络可用:refresh() 成功,远端数据一次性写入 Room,观察 Room 的界面随后更新。
网络不可用:refresh() 返回失败,已有 Room 数据不被清空,界面继续显示最后一次成功缓存。

这里的“缓存”不是额外的内存列表,而是可持久化、可观察的本地数据源。对于大列表或部分更新,可以把“整表替换”改成基于主键、版本号或更新时间的增量合并,但仍应保持“先确定远端结果,再原子更新本地”的边界。

离线写入需要独立同步策略

离线优先至少要保证关键读取在断网时可用;是否允许离线写入则取决于业务。如果任务编辑必须在断网时也不丢失,可以先把变更写入 Room,并记录“待同步”状态,再交给 WorkManager 在网络恢复后持久重试。

这种写法还必须明确冲突规则,例如服务器版本优先、最后写入优先,或需要用户人工合并。没有冲突策略的“自动重试”只是在延迟暴露问题。

数据库迁移解决“旧安装如何进入新结构”,离线优先解决“新旧网络状态如何使用同一份可靠数据”。两者共同的原则都是先保护本地事实来源,再让升级或网络同步以可验证、可回退的方式修改它。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

迁移、缓存与离线优先

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通