第3章 Room的事务注解：@Transaction用法、自动与手动事务边界

3.1 事务在Room中的必要性

Room 默认将所有数据库操作串行化到单个工作线程，但这仅保证线程安全，不保证多个操作的原子性和隔离性。当需要一次性执行多条写操作（如批量插入、级联删除、转账逻辑）且要求“全做或全不做”时，必须使用数据库事务。

Room 提供两种事务边界控制方式：声明式（@Transaction 注解） 和 编程式（手动调用 beginTransaction / endTransaction）。理解两者的自动与手动边界差异，是稳定实现数据隔离的基础。

3.2 @Transaction 注解：声明式自动事务

在 DAO 方法上添加 @Transaction 注解，Room 会在方法执行前后自动管理数据库事务的开始与提交/回滚。

3.2.1 基本原理

  • 自动开始：方法首次访问数据库时，Room 打开一个事务。
  • 自动提交：方法正常结束，自动调用 setTransactionSuccessful() 并提交。
  • 自动回滚：方法抛出任何未捕获的异常，事务自动回滚，不提交任何修改。
  • 嵌套支持：如果多个 @Transaction 方法相互调用，Room 会复用最外层事务（除非使用 @Transaction(rollbackFor = ...) 等高级选项）。

3.2.2 基本用法示例

@Dao
public interface UserDao {
    @Transaction
    @Insert
    void insertUsers(List<User> users);

    @Transaction
    @Query("DELETE FROM users WHERE age < :minAge")
    int deleteByAge(int minAge);
}

上述代码中，insertUsers 和 deleteByAge 各自拥有独立的自动事务边界。若在调用层需要将两个操作合并为一个原子事务，则应在调用方法上标注 @Transaction：

@Transaction
public void replaceUsers(List<User> newUsers, int minAge) {
    userDao.deleteByAge(minAge);
    userDao.insertUsers(newUsers);
}

此时，replaceUsers 方法整个执行过程处于同一事务中。

3.3 手动事务边界：beginTransaction / endTransaction

当需要更精细的控制（如混合不同 DAO、包含条件判断、或需要在事务内调用非 DAO 方法）时，可以使用 RoomDatabase 提供的手动事务方法。

3.3.1 标准模板

database.beginTransaction();
try {
    // 执行多个数据库操作
    userDao.insertUsers(newUsers);
    userDao.deleteByAge(minAge);

    database.setTransactionSuccessful(); // 标记成功
} finally {
    database.endTransaction(); // 提交或回滚
}
  • beginTransaction()：开启事务（如果已有外层事务，则增加嵌套计数）。
  • setTransactionSuccessful()：标记事务成功，否则 endTransaction 会回滚。
  • endTransaction()：提交或回滚（取决于是否调用了 setTransactionSuccessful），并释放连接。

3.3.2 手动事务 vs. @Transaction 核心差异

对比维度@Transaction 声明式手动编程式
边界控制自动围绕方法完全由代码控制
异常处理自动回滚（未捕获异常）需要 try/finally 保证 endTransaction
嵌套事务自动复用外层手动控制，容易嵌套错误
跨 DAO 混合通过 @Transaction 方法组合直接混合任意 DAO 调用
可读性高，声明即意图低，需理解模板
灵活性中（不能中途判断是否回滚）高（可根据业务条件调用 setTransactionSuccessful）

3.4 事务边界流程图：自动 vs 手动

事务边界执行流程对比：自动（@Transaction） vs 手动 自动事务 @Transaction DAO方法被调用 自动 beginTransaction() 执行所有 DAO 操作 异常？ 自动提交 自动回滚 方法返回 手动事务编程式 调用 beginTransaction() try 块内执行操作 setTransactionSuccessful() finally 内 endTransaction() 提交事务 回滚事务 结束
最佳实践：优先使用 @Transaction 声明式事务，代码更简洁、不易遗漏 endTransaction()。仅当需要条件性提交/回滚（例如业务逻辑决定是否保存）或必须混合多个 DAO 且无法通过方法组合时，才使用手动事务模板。

3.5 调试与常见错误

3.5.1 未调用 setTransactionSuccessful

手动事务中最常见错误：在 finally 块中直接 endTransaction() 但忘记调用 setTransactionSuccessful()，导致每次事务都回滚。

// 错误示例：始终回滚
database.beginTransaction();
try {
    userDao.update(user);
    // 忘记调用 setTransactionSuccessful()
} finally {
    database.endTransaction(); // 总是回滚
}

3.5.2 嵌套事务不当导致死锁或性能下降

@Transaction 方法嵌套调用时，内层实际使用外层事务，不会真正嵌套。但如果内层使用手动 beginTransaction()，Room 会增加内部计数器，只有最外层 endTransaction() 才会提交。错误的嵌套层级可能造成事务过长时间持有锁。

3.5.3 跨线程事务风险

事务必须与同一个 RoomDatabase 实例在同一线程内完成。如果在事务中开启子线程操作同一数据库，SQLite 会立即抛出 SQLiteDatabaseLockedException。

database.beginTransaction();
new Thread(() -> {
    // 错误：不同线程操作同一数据库
    userDao.insert(user); // 抛出异常
}).start();
注意：Room 默认不允许在主线程执行数据库操作（除非调用 allowMainThreadQueries()），但事务同样禁止跨线程。请确保 beginTransaction 和 endTransaction 在同一个工作线程内成对出现。

3.6 性能与稳定性优化建议

  • 事务粒度：尽量缩短事务持续时间。将 IO 操作、网络请求等排除在事务外部，仅包裹 SQL 语句。
  • 批量操作：使用 @Transaction + @Insert(onConflict = OnConflictStrategy.REPLACE) 一次性传入 List，比逐条插入效率高 10-20 倍。
  • 避免大事务：单事务内操作超过 500 行数据时，考虑分片提交，防止 WAL 文件膨胀或超时锁定。
  • 读写分离：对于只读事务（如复杂查询），同样可以标注 @Transaction 以保证一致性快照，但注意会获取读锁，高并发下考虑使用 @RawQuery 配合 SupportSQLiteQuery 的 query 模式减少锁竞争。
  • 使用 allowMainThreadQueries() 时，事务仍会在主线程阻塞 UI，务必迁移至协程或 RxJava 线程池。

3.7 总结

@Transaction 注解提供了最简洁的声明式事务边界，适用于绝大多数原子性场景。手动事务则保留了全部控制权，适合异常分支复杂的业务逻辑。无论使用哪种方式，都要牢记事务的原子性、隔离性和单一线程原则，并结合 Room 的默认串行化调度，才能构建稳定、高效的系统应用数据层。

← 上一章 📖 返回目录 下一章 →