Kotlin数据类新增字段导致数据库查询崩溃的解决方法

这个问题我碰到过好几次了——新增数据类字段后Room查询崩溃，本质是旧数据库的users表没有对应的gender列，Room没法把查询结果映射到新的User数据类上（毕竟你的数据类里gender是必填的val字段）。下面给你几个可行的解决方案，按生产环境友好程度排序：

方案1：数据库迁移+数据类默认值（生产环境首选） #

这是最规范的做法，既能保留旧数据，又能让新结构正常工作。

步骤1：修改User数据类，给新增字段加默认值 #

这样即使Room暂时拿不到gender的值，也能用上默认值，不会因为构造参数缺失崩溃：

data class User(
    val name: String,
    val age: Int,
    val gender: String = "unknown" // 新增字段并设置默认值，适配旧数据
)

步骤2：升级数据库版本并添加迁移规则 #

告诉Room如何把旧版本的数据库表升级到新版本，给users表新增gender列：

@Database(
    entities = [User::class],
    version = 2, // 版本号从原来的1（假设）升到2
    exportSchema = true // 建议开启，方便后续迁移管理
)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao

    companion object {
        // 定义从版本1到版本2的迁移逻辑
        private val MIGRATION_1_2 = object : Migration(1, 2) {
            override fun migrate(database: SupportSQLiteDatabase) {
                // 给users表添加gender列，默认值设为'unknown'，和数据类的默认值保持一致
                database.execSQL("ALTER TABLE users ADD COLUMN gender TEXT DEFAULT 'unknown'")
            }
        }

        // 构建数据库实例时加入迁移规则
        fun getInstance(context: Context): AppDatabase {
            return Room.databaseBuilder(context, AppDatabase::class.java, "your_db_name")
                .addMigrations(MIGRATION_1_2) // 加入迁移规则
                // 开发阶段如果不怕丢数据，可以用这个快速测试，但生产环境绝对不能用！
                // .fallbackToDestructiveMigration()
                .build()
        }
    }
}

步骤3：Dao层无需修改 #

你的原查询语句@Query("SELECT*FROM users WHERE name =:name")可以保持不变，因为迁移后表已经有gender列，Room能正常映射到数据类。

方案2：在查询语句中手动补默认值（临时快速修复） #

如果不想立刻做数据库迁移，也可以在SQL查询里给gender字段补默认值，让查询结果符合新数据类的结构：

@Query("SELECT name, age, COALESCE(gender, 'unknown') AS gender FROM users WHERE name = :name")
suspend fun getUser(name: String): Flow<User>

COALESCE函数会取第一个非null的值——如果旧表没有gender列，就用'unknown'代替。不过这个方案只是临时救急，长期来看还是建议做数据库迁移，否则后续表结构不一致会埋下隐患。

方案3：把字段设为可空（不推荐，除非业务允许） #

如果业务上允许gender为null，可以把数据类字段改成可空类型：

data class User(
    val name: String,
    val age: Int,
    val gender: String? = null // 设为可空并给默认值
)

这种方式不需要迁移，但你得在业务代码里处处处理gender为null的情况，容易引入bug，所以除非必要不推荐。

内容的提问来源于stack exchange，提问作者Exron