Room框架下SQLite外键约束失败(787)及自增ID问题排查

核心问题原因 #

1. 外键引用无效值：插入ShopSectionEntity时，使用的是ShopMenuEntity初始的menuID=0，而非数据库实际生成的自增ID。Room插入实体后不会自动更新原始对象的ID字段，导致后续创建的Section引用了不存在的menuID，触发外键约束失败。
2. 自增ID未被正确获取：虽然实体类设置了autoGenerate=true，但插入操作完成后没有获取数据库生成的真实ID，导致关联数据无法正确绑定。

解决方案 #

步骤1：修改Dao方法，返回插入后的自增ID #

更新NewShopMenuDao的插入方法，让其返回插入记录的ID：

@Dao
interface NewShopMenuDao {
    // 插入单个ShopMenuEntity并返回生成的menuID
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertShopMenu(shopMenuEntity: ShopMenuEntity): Long

    // 插入多个Section
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertSections(shopSectionEntities: List<ShopSectionEntity>)

    // 其他原有方法保持不变...
}

步骤2：调整插入逻辑，先获取真实menuID再创建Section #

修改addSubMenu方法，先插入Menu获取数据库生成的ID，再用该ID创建关联的Section：

private suspend fun addSubMenu(
    shopMenuDao: NewShopMenuDao,
    subMenu: NewShopMenuResponse,
    parentID: Int
) {
    // 创建Menu实体
    val mSubMenu = ShopMenuEntity.mapHttpResponse(subMenu, parentID)
    // 插入Menu并获取数据库生成的ID
    val generatedMenuId = shopMenuDao.insertShopMenu(mSubMenu).toInt()

    // 用真实ID创建Section实体
    val dbSections = subMenu.sections?.mapIndexed { sectionIndex, mSection ->
        ShopSectionEntity.mapHttpResponse(mSection, generatedMenuId, sectionIndex + 1)
    } ?: emptyList()

    // 插入Sections
    shopMenuDao.insertSections(dbSections)
}

步骤3：优化实体类ID字段（可选） #

将ID字段改为val，避免意外修改，同时明确自增配置的语义：

// ShopMenuEntity.kt
@Entity(tableName = ShopMenuEntity.TABLE_NAME)
data class ShopMenuEntity(
    @PrimaryKey(autoGenerate = true)
    @ColumnInfo(name = COLUMN_ID)
    val menuID: Int = 0, // 改为val
    val level: Int? = null,
    @ColumnInfo(name = COLUMN_PARENT_ID)
    val parentId: Int = -1,
) {
    // 伴生对象内容不变...
}

// ShopSectionEntity.kt
@Entity(tableName = ShopSectionEntity.TABLE_NAME,
    foreignKeys = [ForeignKey(
        entity = ShopMenuEntity::class,
        parentColumns = arrayOf(ShopMenuEntity.COLUMN_ID),
        childColumns = arrayOf(ShopSectionEntity.SHOP_MENU_ID),
        onDelete = ForeignKey.CASCADE
    )],
    indices = [Index(ShopSectionEntity.SHOP_MENU_ID)])
data class ShopSectionEntity(
    @PrimaryKey(autoGenerate = true)
    @ColumnInfo(name = COLUMN_ID)
    val sectionID: Int = 0, // 改为val
    @ColumnInfo(name = SHOP_MENU_ID)
    val shopMenuID: Int,
) {
    // 伴生对象内容不变...
}

步骤4：使用事务保证数据一致性（可选） #

如果需要同时插入Menu和多个Section，用事务包裹操作，确保原子性（要么都成功，要么都回滚）：

@Dao
interface NewShopMenuDao {
    @Transaction
    suspend fun insertMenuWithSections(menu: ShopMenuEntity, sections: List<ShopSectionEntity>) {
        val menuId = insertShopMenu(menu).toInt()
        val updatedSections = sections.map { it.copy(shopMenuID = menuId) }
        insertSections(updatedSections)
    }

    // 其他原有方法...
}

调用事务方法的示例：

private suspend fun addSubMenu(
    shopMenuDao: NewShopMenuDao,
    subMenu: NewShopMenuResponse,
    parentID: Int
) {
    val mSubMenu = ShopMenuEntity.mapHttpResponse(subMenu, parentID)
    val sections = subMenu.sections?.mapIndexed { sectionIndex, mSection ->
        ShopSectionEntity.mapHttpResponse(mSection, 0, sectionIndex + 1) // 临时用0，事务内会替换为真实ID
    } ?: emptyList()

    shopMenuDao.insertMenuWithSections(mSubMenu, sections)
}

关键说明 #

• Room的@Insert方法返回值：插入单个实体返回该实体的自增ID（Long类型），插入多个返回ID列表。
• 外键约束要求子表引用的父表记录必须存在，因此必须先插入父表（Menu）并获取真实ID，再插入子表（Section）。
• 若之前数据库已有错误数据，建议卸载App清除旧数据库，或在Database类中增加版本号并编写迁移脚本。

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