原生移动开发 / 系统课时
处理数据库与配置升级
处理数据库与配置升级
应用升级不只是替换 APK。旧版本可能已经留下数据库表、SharedPreferences 键值和缓存文件;如果新代码直接按新结构读取,轻则配置丢失,重则启动崩溃。本节建立一套可验证的本地数据迁移流程,让新版本能够安全接管旧数据。
学习目标
- 识别数据库、SharedPreferences 与缓存结构变化带来的升级风险
- 为需要保留的数据设计有版本、有顺序且可重复执行的迁移
- 通过旧版本数据样本验证升级成功与失败路径
先区分哪些数据必须迁移
发布前先列出新旧版本的本地数据差异,不要看到文件变化就全部迁移。数据库中的用户业务数据通常需要保留;SharedPreferences 中的登录状态、功能开关或用户设置要判断键名和类型是否变化;可重新下载或计算的缓存则优先失效重建。
| 数据 | 常见变化 | 推荐处理 |
|---|---|---|
| Room 数据库 | 新增列、拆表、索引变化 | 编写显式 Migration |
| SharedPreferences | 键改名、类型变化、默认值调整 | 按数据版本迁移键值 |
| 本地缓存 | JSON 字段或目录结构变化 | 删除不兼容缓存并重新生成 |
不要把缓存和业务数据放在同一套“全部清空”逻辑里。升级时直接清除数据库虽然简单,却可能把真实用户数据一起删除。

给数据库变化写显式迁移
以 Room 从版本 2 升到版本 3 为例,如果 user 表新增一个非空时间字段,就必须为已有行提供默认值。不要依赖卸载重装,因为真实用户设备上已经存在旧数据库。
片段示例:以下代码假设项目已经使用 Room,并且 AppDatabase 的新 Schema 版本为 3。
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,并保证重复启动不会反复修改。
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,而不是只验证最近一个版本。