原生移动开发 / 系统课时
迁移、缓存与离线优先
迁移、缓存与离线优先
这一节解决两个最容易破坏本地体验的问题:数据库升级时保住旧数据,以及网络不稳定时仍让页面读取可靠缓存。最终结构是“界面始终读本地库,网络只负责刷新本地库”。
学习目标
- 为 Room 版本升级编写可追踪、可验证的迁移
- 让本地数据库成为离线优先读取的单一事实来源
- 设计安全的缓存刷新、失败保留和后续同步边界
把本地库设为读取事实来源
离线优先不等于“没网时才读缓存”。更稳定的做法是:UI 始终观察 Room,Repository 在合适时机请求网络,成功后把新数据事务性写入 Room。网络失败只影响“数据是否足够新”,不应把已经存在的本地数据一起清掉。

这种结构让在线和离线使用同一条读取路径。是否联网只决定 Repository 能不能得到更新数据,而不是决定 UI 改用另一套数据源,因此页面状态更容易保持一致。
升级数据库时显式迁移
假设版本 1 的 tasks 表只有 id 和 title,版本 2 新增非空 note 字段。旧设备上已经存在数据,不能直接修改实体后提高版本号而不提供迁移路径。
下面是片段示例,展示 1 → 2 的手动迁移。给非空列提供默认值,才能让已有行顺利补齐新字段。
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()预期结果
安装过版本 1 的用户升级后可以继续打开数据库。
原有 tasks 记录保留,新增 note 列的旧记录值为 ""。
如果缺少 1 → 2 的迁移路径,数据库打开阶段会失败,而不是静默猜测表结构。生产数据通常不应依赖破坏性迁移,因为它可能通过重建表来解决版本不匹配,同时丢掉用户数据。更稳妥的做法是保留导出的 schema 历史,并测试每一条仍受支持的升级路径。
缓存刷新只在成功后覆盖本地数据
刷新时最危险的顺序是“先清空 Room,再发网络请求”:只要请求失败,用户就从“旧数据”退化成“空白页”。应先拿到完整且可接受的远端结果,再用事务更新本地表。
下面的片段让 Repository 只向上暴露 Room 的 Flow;网络响应成功后才替换缓存,失败时原有数据保持不变。
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)
}
}预期结果
网络可用:refresh() 成功,远端数据一次性写入 Room,观察 Room 的界面随后更新。
网络不可用:refresh() 返回失败,已有 Room 数据不被清空,界面继续显示最后一次成功缓存。这里的“缓存”不是额外的内存列表,而是可持久化、可观察的本地数据源。对于大列表或部分更新,可以把“整表替换”改成基于主键、版本号或更新时间的增量合并,但仍应保持“先确定远端结果,再原子更新本地”的边界。
离线写入需要独立同步策略
离线优先至少要保证关键读取在断网时可用;是否允许离线写入则取决于业务。如果任务编辑必须在断网时也不丢失,可以先把变更写入 Room,并记录“待同步”状态,再交给 WorkManager 在网络恢复后持久重试。
这种写法还必须明确冲突规则,例如服务器版本优先、最后写入优先,或需要用户人工合并。没有冲突策略的“自动重试”只是在延迟暴露问题。
数据库迁移解决“旧安装如何进入新结构”,离线优先解决“新旧网络状态如何使用同一份可靠数据”。两者共同的原则都是先保护本地事实来源,再让升级或网络同步以可验证、可回退的方式修改它。