3 自动迁移 fallbackToDestructiveMigration 实现：声明式降级策略、数据丢失风险、使用场景

3.1 原理：声明式降级 vs 显式崩溃

当用户数据库版本低于当前 Room 声明的 version，而开发者未提供对应升级 Migration 时，Room 默认行为是抛出 IllegalStateException 并崩溃应用。这种严格模式可防止数据错乱，但也带来恶劣的用户体验。

fallbackToDestructiveMigration() 允许开发者声明：“如果找不到升级迁移路径，就销毁旧数据库并重建空库”。这是一种 声明式降级策略 —— 不写具体迁移逻辑，但接受数据丢失的风险以换取应用可用性。

3.2 实现流程与 API

在 Room.databaseBuilder 链式调用中追加 fallbackToDestructiveMigration() 即可启用。

// Kotlin 示例
val db = Room.databaseBuilder(
    context,
    AppDatabase::class.java,
    "app_database"
)
    .version(3)                // 当前 schema 版本
    .fallbackToDestructiveMigration()   // 声明兜底破坏性迁移
    .build()

若数据库当前磁盘版本为 1（或 2），而 Room 只提供了从 1→2 的迁移，未提供 1→3 或 2→3，则触发兜底行为。

3.2.1 配置清单与参数

3.3 数据丢失风险

破坏性迁移会 完全清空所有表中的行数据，包括 @Entity 标识的表以及 @DatabaseView 等附属结构。Room 不会保留任何 log 或备份。

3.4 使用场景决策

• ✅ 适用场景：
  • 本地配置型数据库（如主题设置、缓存，数据可后台拉取）
  • 演示/Demo 应用，无持久用户数据依赖
  • 开发阶段，配合 deleteDatabase() 或 .createFromAsset() 快速迭代
• ❌ 不适用场景：
  • 用户笔记、订单、医疗等不能丢失的数据
  • 有严格数据审计要求的系统
  • 多版本共存且需要向后兼容的模块化应用

3.5 调试与日志验证

启用 .fallbackToDestructiveMigration() 后，Room 在触发时会输出日志：

Room: Migration from version 1 to 3 is not provided.
Room: Falling back to destructive migration.
Room: Deleting and rebuilding all tables.

可通过 adb logcat -s Room 观察是否触发了兜底。若未触发预期行为，检查：

• 是否已调用 .fallbackToDestructiveMigration()（顺序需在 .build() 之前）
• 是否同时存在可用的 Migration 对象 —— Room 会优先使用显式迁移，只有当完全找不到迁移时才走兜底
• 数据库版本号是否已写入 @Database(version = X) 注解

3.6 常见错误与避坑

3.7 性能与稳定性优化建议

• 组合使用：对已知的升级路径编写 Migration，仅对无法预料的版本跳转使用 fallbackToDestructiveMigration()，减少不必要的数据丢失。
• 预检查版本：在 OpenHelper 回调中记录每次触发兜底的频率，若过于频繁应审查发布流程。
• 备份机制：可在 createFromAsset() 中预置一个“空壳”数据库，使破坏重建后应用仍能展示基本界面。
• 测试覆盖：在集成测试中添加 MigrationTestHelper，验证不同版本组合下兜底行为是否按预期触发，并确认数据已完全清空。

3.8 工作流程 SVG 图

下图展示了 Room 版本检查 → 搜索 Migration → 决策是否触发破坏性重建的完整流程：

3.9 内联代码示例（完整声明式降级配置）

@Database(entities = [User::class, Task::class], version = 5, exportSchema = true)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
    abstract fun taskDao(): TaskDao

    companion object {
        @Volatile
        private var INSTANCE: AppDatabase? = null

        fun getInstance(context: Context): AppDatabase {
            return INSTANCE ?: synchronized(this) {
                val builder = Room.databaseBuilder(
                    context.applicationContext,
                    AppDatabase::class.java,
                    "example_db"
                )
                .version(5)
                .fallbackToDestructiveMigration()  // 声明兜底策略
                .build()
                INSTANCE = builder
                builder
            }
        }
    }
}