Room TypeConverter导致数据无法保存问题求助

当使用Room的TypeConverter处理嵌套数据类或列表时，数据无法保存到数据库；但移除需要TypeConverter的字段后，数据能正常保存（已通过App Inspection验证）。

相关代码 #

@Entity
data class User(
    @PrimaryKey val uid: Int,
    @ColumnInfo(name = "first_name") val firstName: String?,
    @ColumnInfo(name = "last_name") val lastName: String?,

    //Nested Data Class cause of values not being saved
    @ColumnInfo(name = "WOW") val wow:Wow
)
data class Wow(val a: String,val b:String)

@Dao
interface UserDao {
    @Query("SELECT * FROM user")
    fun getAll():LiveData<List<User>>

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    fun loadAllByIds(userIds: IntArray): List<User>

    @Query("SELECT * FROM user WHERE first_name LIKE :first AND last_name LIKE :last LIMIT 1")
    fun findByName(first: String, last: String): User

    @Insert
    fun insertAll(vararg users: User)

    @Delete
    fun delete(user: User)
}
class TypeConverterWOW(){
    @TypeConverter
    fun listToJson(value:Wow) = Json.encodeToString(value)
    @TypeConverter
    fun jsonToList(value:String) = Json.decodeFromString<Wow>(value)
}
@Database(entities = [User::class], version = 1)
@TypeConverters(TypeConverterWOW::class)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
    companion object{
        //singleton prevents multiple instance of database opened at the same time
        @Volatile
        private var INSTANCE : AppDatabase? = null
        fun getDataBase(context: Context): AppDatabase{
            val tempInstance = INSTANCE
            if(tempInstance != null) return tempInstance
            synchronized(this){
                val instance = Room.databaseBuilder(context.applicationContext, AppDatabase::class.java, "database-name").build()
                INSTANCE = instance
                return instance
            }
        }
    }
}

问题排查与修复方案 #

1. 补全嵌套类的序列化注解 #

kotlinx.serialization要求被序列化的数据类必须添加@Serializable注解，否则无法完成序列化/反序列化：

import kotlinx.serialization.Serializable

@Serializable
data class Wow(val a: String, val b: String)

2. 配置Json序列化实例 #

默认Json实例可能缺少必要配置，导致序列化失败。显式配置参数确保兼容性：

class TypeConverterWOW(){
    private val json = Json {
        ignoreUnknownKeys = true // 避免因未知字段解析失败
        encodeDefaults = true // 确保所有字段都被序列化
    }
    
    @TypeConverter
    fun listToJson(value:Wow) = json.encodeToString(value)
    @TypeConverter
    fun jsonToList(value:String) = json.decodeFromString<Wow>(value)
}

3. 确保TypeConverter的可见性 #

将TypeConverterWOW类改为公开可见，或直接内嵌到AppDatabase中，避免Room无法识别：

@Database(entities = [User::class], version = 1)
@TypeConverters(AppDatabase.TypeConverterWOW::class)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao

    class TypeConverterWOW(){
        private val json = Json { ignoreUnknownKeys = true }
        
        @TypeConverter
        fun wowToJson(value: Wow): String = json.encodeToString(value)
        
        @TypeConverter
        fun jsonToWow(value: String): Wow = json.decodeFromString(value)
    }

    // 单例代码...
}

4. 处理数据库表结构变更 #

添加WOW列属于表结构变更，需更新数据库版本并处理迁移。测试环境可临时使用破坏性迁移重建数据库：

val instance = Room.databaseBuilder(
    context.applicationContext,
    AppDatabase::class.java,
    "database-name"
)
.fallbackToDestructiveMigration() // 仅测试用，生产环境需编写迁移逻辑
.build()

5. 捕获插入操作异常 #

修改Dao插入方法返回插入结果，并捕获异常排查问题：

@Dao
interface UserDao {
    // ... 其他方法
    @Insert
    suspend fun insertAll(vararg users: User): List<Long>
}

调用时捕获异常：

try {
    userDao.insertAll(user)
} catch (e: Exception) {
    Log.e("RoomError", "插入失败: ${e.message}")
}

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