原生移动开发 / 系统课时

处理数据库与配置升级

处理数据库与配置升级

应用升级不只是替换 APK。旧版本可能已经留下数据库表、SharedPreferences 键值和缓存文件;如果新代码直接按新结构读取,轻则配置丢失,重则启动崩溃。本节建立一套可验证的本地数据迁移流程,让新版本能够安全接管旧数据。

学习目标

  • 识别数据库、SharedPreferences 与缓存结构变化带来的升级风险
  • 为需要保留的数据设计有版本、有顺序且可重复执行的迁移
  • 通过旧版本数据样本验证升级成功与失败路径

先区分哪些数据必须迁移

发布前先列出新旧版本的本地数据差异,不要看到文件变化就全部迁移。数据库中的用户业务数据通常需要保留;SharedPreferences 中的登录状态、功能开关或用户设置要判断键名和类型是否变化;可重新下载或计算的缓存则优先失效重建。

数据 常见变化 推荐处理
Room 数据库 新增列、拆表、索引变化 编写显式 Migration
SharedPreferences 键改名、类型变化、默认值调整 按数据版本迁移键值
本地缓存 JSON 字段或目录结构变化 删除不兼容缓存并重新生成

不要把缓存和业务数据放在同一套“全部清空”逻辑里。升级时直接清除数据库虽然简单,却可能把真实用户数据一起删除。

Android 本地数据升级链路

给数据库变化写显式迁移

以 Room 从版本 2 升到版本 3 为例,如果 user 表新增一个非空时间字段,就必须为已有行提供默认值。不要依赖卸载重装,因为真实用户设备上已经存在旧数据库。

片段示例:以下代码假设项目已经使用 Room,并且 AppDatabase 的新 Schema 版本为 3。

kotlin
val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(db: SupportSQLiteDatabase) {
        // 已有行必须能获得合法值,否则 ALTER TABLE 会失败。
        db.execSQL(
            "ALTER TABLE user " +
                "ADD COLUMN last_synced_at INTEGER NOT NULL DEFAULT 0"
        )
    }
}

val database = Room.databaseBuilder(
    context,
    AppDatabase::class.java,
    "app.db"
)
    .addMigrations(MIGRATION_2_3)
    .build()

预期结果:设备中存在版本 2 数据库时,Room 打开数据库前执行 MIGRATION_2_3,原有 user 行得到 last_synced_at = 0,随后按版本 3 Schema 正常访问。实际迁移仍应使用旧版本真实数据库样本测试,而不是只验证全新安装。

配置迁移要处理键名和类型

SharedPreferences 没有数据库那样的 Schema 约束,因此更容易出现“没有崩溃但配置悄悄失效”。可以保存独立的数据版本,并让迁移逻辑只在旧版本上执行;迁移完成后再更新版本标记。

片段示例:下面把旧键 api_base_url 迁移到 server_url,并保证重复启动不会反复修改。

kotlin
fun migratePreferences(prefs: SharedPreferences) {
    val dataVersion = prefs.getInt("data_version", 1)
    if (dataVersion >= 2) return

    val oldUrl = prefs.getString("api_base_url", null)

    prefs.edit()
        .remove("api_base_url")
        .putString("server_url", oldUrl ?: "https://api.example.com")
        .putInt("data_version", 2)
        .apply()
}

预期结果:第一次从数据版本 1 启动时保留原 URL 并改用新键;之后 data_version 已为 2,再次启动不会重复迁移。若字段类型也发生变化,应先读取旧类型并显式转换,不能直接用新类型读取旧值。

缓存优先失效而不是复杂迁移

图片缩略图、接口响应 JSON、搜索索引等可再生成数据通常不值得设计多级迁移。更稳妥的方式是给缓存目录或缓存格式维护版本,新版本发现不兼容时删除对应缓存,再由正常业务流程重建。

迁移执行顺序应按依赖关系确定。例如配置迁移需要查询数据库时,应先完成数据库升级;缓存依赖新的用户 ID 或配置格式时,则放在持久数据迁移之后。任何一步失败,都不要提前写入“迁移完成”标记。

用旧版本数据做升级验收

只测试全新安装无法发现迁移问题。发布候选版本至少应准备一个由上一正式版本产生的数据样本,覆盖数据库已有记录、非默认用户设置以及可失效缓存,然后直接安装新版本升级。

验收时确认旧业务数据仍可读取、配置值符合预期、新增字段有合法默认值、旧缓存不会导致解析异常,并再次冷启动验证迁移不会重复执行。涉及多个历史版本时,还要确保当前支持的每条升级路径都能连续迁移到最新 Schema,而不是只验证最近一个版本。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理数据库与配置升级

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

登录哪都通