Android Room查询未调用预期匹配参数构造函数问题

问题背景 #

将原有基于Java开发的SQLite Android应用重构为Kotlin+Room+Jetpack Compose架构的应用，开发进度过半时出现异常：DAO查询未返回预期的完整数据，排查后发现数据模型类中定义的目标构造函数未被调用。
印象中在新增firearm_image数据表之前，目标构造函数可以正常被调用，但无法100%确认。

相关实现 #

数据库表结构 #

数据模型定义 #

为关联firearm_image表的imageFile字段，在Firearm类中添加了被@Ignore注解标记的firearmImageUrl属性作为Firearm对象的成员。这种表关联实现方式并非最优，但应用体量极小，预期仅个人使用。

@Entity(tableName = "firearm")
class Firearm {
    @ColumnInfo(name = "_id")
    @PrimaryKey(autoGenerate = true)
    var id = 0

    var name: String = ""

    var notes: String? = null

    @Ignore
    var shotCount = 0

    @Ignore
    var firearmImageUrl: String = ""

    @Ignore
    constructor()

    @Ignore
    constructor(
        name: String,
        notes: String?
    ) {
        this.name = name
        this.notes = notes
    }

    @Ignore
    constructor(
        name: String,
        notes: String?,
        shotCount: Int
    ) {
        this.name = name
        this.notes = notes
        this.shotCount = shotCount
    }

    @Ignore
    constructor(
        id: Int,
        name: String,
        notes: String?,
        shotCount: Int
    ) {
        this.id = id
        this.name = name
        this.notes = notes
        this.shotCount = shotCount
    }

    // 预期被调用但实际未命中的构造函数，此前曾添加@Ignore注解，移除后无效果
    constructor(
        id: Int,
        name: String,
        notes: String?,
        shotCount: Int,
        firearmImageUrl: String
    ) {
        this.id = id
        this.name = name
        this.notes = notes
        this.shotCount = shotCount
        this.firearmImageUrl = firearmImageUrl
    }

    // 实际被Room调用的构造函数，参数和查询返回字段不匹配
    constructor(
        id: Int,
        name: String,
        notes: String?,
    ) {
        this.id = id
        this.name = name
        this.notes = notes
    }
}

DAO层实现 #

临时移除了方法的suspend关键字以便命中调试断点；已验证SQL语句可正常运行：将SQL复制到Database Inspector中执行，可以正确返回包含firearmImageUrl路径的完整数据。

@Query(
        "SELECT f._id, " +
                  "f.name, " +
                  "f.notes, " +
                  "CASE WHEN SUM(s.roundsFired) IS NULL THEN 0 " +
                  "ELSE SUM(s.roundsFired) " +
                  "END shotCount, " +
                  "fi.imageFile firearmImageUrl " +
              "FROM firearm f " +
              "LEFT JOIN shot_track s ON f._id = s.firearmId " +
              "LEFT JOIN firearm_image fi ON f._id = fi.firearmId " +
              "WHERE f._id = :firearmId " +
              "GROUP BY f._id " +
              "ORDER BY f.name"
    )
    fun getFirearm(firearmId: Int): Firearm?

Repository层实现 #

override fun getFirearm(firearmId: Int): Firearm? {
        return dao.getFirearm(firearmId)
    }

UseCase层实现 #

项目采用Clean Architecture设计，对于该小体量应用属于过度设计，UseCase仅作为中间层调用Repository方法：

data class FirearmUseCases(
    val getFirearms: GetFirearms,
    val getFirearm: GetFirearm
)

class GetFirearm(private val repository: FirearmRepository) {
    operator fun invoke(firearmId: Int): Firearm? {
        return repository.getFirearm(firearmId)
    }
}

ViewModel层实现 #

init {
        savedStateHandle.get<Int>("firearmId")?.let { firearmId ->
            if (firearmId > 0) {
                viewModelScope.launch {
                    firearmUseCases.getFirearm(firearmId)?.also { firearm ->
                        _currentFirearmId.value = firearm.id
                        // 后续逻辑在此块中处理获取到的对象
                    }
                }
             }
        }
}

问题现象 #

DAO实例化Firearm对象时，未调用包含id、name、notes、shotCount、firearmImageUrl五个参数的预期构造函数，反而调用了仅包含id、name、notes三个参数、与查询返回字段不匹配的构造函数。移除预期构造函数上的@Ignore注解后问题没有任何改善，三参数构造函数依旧被调用。

问题原因 #

Room的构造函数匹配和字段映射逻辑是固定的，出现这个问题是两个规则共同导致的：

1. 字段上的@Ignore注解会告知Room完全忽略该字段：不管是建表、写入数据还是从查询结果映射赋值，Room都不会处理标记了@Ignore的字段，哪怕查询结果里存在同名列，也不会给该字段赋值。代码里的shotCount、firearmImageUrl都被标记了@Ignore，Room从设计上就不会给这两个字段赋值。
2. Room选择构造函数时，只会在未被@Ignore标记的构造函数中，匹配参数列表和「实体类对应表的持久化字段（即未被@Ignore标记的字段）」重合度最高的选项。当前有两个未被@Ignore标记的构造函数：三参数构造函数的参数正好对应firearm表的三个持久化字段（id、name、notes），五参数构造函数多了两个被Room忽略的字段，因此Room必然选择三参数构造函数，和SQL语句返回多少列没有关系。

解决方案 #

根据项目需求二选一即可：

方案1：最小改动（适合个人小项目快速修复） #

不需要新建类，调整现有实体类注解即可：

1. 移除shotCount和firearmImageUrl字段上的@Ignore注解
2. 给两个字段补充默认值注解，避免旧版本表结构不存在这两列时崩溃：

   @ColumnInfo(defaultValue = "0")
   var shotCount = 0
   
   @ColumnInfo(defaultValue = "")
   var firearmImageUrl: String = ""
   

3. 给无参、双参数、三参数、四参数构造函数全部加上@Ignore注解，只保留五参数构造函数作为Room使用的唯一构造函数。
   如果是个人本地使用，不需要做数据库迁移，直接在Room数据库构建时加上fallbackToDestructiveMigration()即可，改完后Room会正确识别五个字段，命中五参数构造函数完成赋值。唯一的小问题是firearm表会多两个实际不存储业务数据的冗余列，对个人小项目没有影响。

方案2：规范写法（长期可维护，避免后续踩坑） #

Room的设计规范是@Entity标记的实体类只对应单表结构，跨表查询结果不要直接用实体类接收，用专门的DTO（数据传输对象）接收即可：

1. 精简Firearm实体类：删除shotCount、firearmImageUrl两个跨表字段，删除多余的构造函数，只保留对应firearm表三个字段的构造函数。
2. 新建专门的查询结果DTO类，不需要加任何实体类注解：

   data class FirearmWithDetails(
       @ColumnInfo(name = "_id") val id: Int,
       val name: String,
       val notes: String?,
       val shotCount: Int,
       val firearmImageUrl: String?
   )
   

3. 修改DAO方法的返回值为FirearmWithDetails?，Room会自动根据查询返回的列名匹配DTO的主构造函数参数，不会出现构造函数匹配错误的问题。
   这种写法只需要多写一个简单的数据类，完全符合Room的设计逻辑，后续修改表结构、调整查询字段都不会出现奇怪的映射问题，即便是小项目也推荐使用。

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