如何在Room数据库实体中为labelId和taskId添加联合唯一约束

AI 小北

2026-5-19

要在Room实体中实现labelId和taskId的组合唯一约束，其实很简单，直接通过Room的注解就能搞定，我给你详细说下具体实现：

核心实现方式：给`@Entity`添加联合唯一索引

你只需要在实体类的@Entity注解里，配置一个包含labelId和taskId的索引，并将该索引的unique属性设为true。Room会自动在生成的SQL Schema中创建对应的联合唯一约束。

Kotlin代码示例：

@Entity(
    indices = [
        Index(value = ["labelId", "taskId"], unique = true)
    ]
)
data class YourEntity(
    @PrimaryKey(autoGenerate = true) val id: Long = 0,
    val labelId: Long,
    val taskId: Long,
    // 这里添加你的其他业务字段
)

Java代码示例：

@Entity(
    indices = {
        @Index(value = {"labelId", "taskId"}, unique = true)
    }
)
public class YourEntity {
    @PrimaryKey(autoGenerate = true)
    private long id;
    private long labelId;
    private long taskId;
    
    // 构造方法、getter和setter方法
}

几个关键细节要注意

约束生效后，SQLite会确保表中不存在labelId和taskId完全相同的两行数据。如果插入或更新时出现重复组合，Room会抛出SQLiteConstraintException异常。
如果你需要自定义冲突处理逻辑（比如用新数据替换旧数据），可以在@Insert或@Update注解中指定冲突策略：
```
@Insert(onConflict = OnConflictStrategy.REPLACE)
suspend fun insertEntity(entity: YourEntity)
```
若你的App已经上线（数据库表已存在），添加这个约束后必须编写数据库迁移代码，否则会触发数据库升级失败。开发阶段可以临时用fallbackToDestructiveMigration()快速测试，但生产环境绝对不能使用这个方法。