TransactionalCache是MyBatis二级缓存中保障事务一致性的关键组件，它不直接存储数据，而是作为缓存写入的事务代理：事务未提交前put操作暂存于entriesToAddOnCommit，提交时批量刷入底层缓存，回滚时清空暂存区；若事务内发生增删改，则标记clearOnCommit=true，提交时清空对应namespace缓存；其机制依赖Spring事务上下文，必须在@Transactional方法中使用才能生效，否则缓存更新与数据库不原子对齐。

TransactionalCache 是 MyBatis 二级缓存中保障事务一致性的关键组件，它不直接存储数据，而是作为“缓存写入的事务代理”，确保只有成功提交的事务才将查询结果真正写入二级缓存，避免脏读和缓存污染。

TransactionalCache 的核心作用

它包装了实际的二级缓存（如 PerpetualCache 或 RedisCache），在事务生命周期内拦截所有缓存写入操作：

• 事务未提交前，所有 putObject 操作仅暂存于其内部的 entriesToAddOnCommit 映射中，不会落到底层缓存
• 事务提交时（commit() 被调用），才批量将 entriesToAddOnCommit 中的数据刷入底层二级缓存
• 事务回滚时（rollback() 被调用），直接清空 entriesToAddOnCommit，不修改任何缓存状态
• 事务内执行 insert/update/delete 语句时，TransactionalCache 会标记自身为 “需要清空”（clearOnCommit = true），待提交时一并清空对应 namespace 的整个二级缓存

与 CachingExecutor 的协作流程

当开启二级缓存后，MyBatis 使用 CachingExecutor 包装原始 Executor。每次查询执行完毕、SqlSession 关闭前，CachingExecutor 会触发缓存写入逻辑：

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

• 若当前线程处于 Spring 管理的事务中，CachingExecutor 获取的 Cache 实际是 TransactionalCache 实例
• 查询结果先尝试放入 TransactionalCache 的暂存区，而非直写二级缓存
• 事务由 Spring TransactionSynchronizationManager 触发 commit/rollback 时，自动回调 TransactionalCache 对应方法
• 这样就实现了“缓存更新与数据库更新原子性对齐”——数据库改成功，缓存才更新；数据库回滚，缓存也不更新

为什么必须配合事务使用

TransactionalCache 的机制依赖事务上下文才能生效：

立即学习“Java免费学习笔记（深入）”；

• 非事务方法中，每次 SqlSession 关闭都会立即把一级缓存写入二级缓存（绕过 TransactionalCache 的暂存逻辑）
• 此时若并发写操作发生，可能刚写入缓存就立刻被另一事务的 update 清空，造成无效写入和性能浪费
• 只有在 @Transactional 方法中，多个 DAO 调用共享同一 SqlSession 和同一 TransactionalCache 实例，才能统一协调读写与缓存生命周期
• Spring 的事务同步器确保 TransactionalCache 的 commit/rollback 严格跟随数据库事务状态，不出现时间差

配置与避坑要点

要让 TransactionalCache 正常工作，需满足以下前提：

• 全局 cacheEnabled=true，Mapper 中声明 <cache/> 或 @CacheNamespace
• 实体类实现 Serializable（否则反序列化失败，缓存写入静默失败）
• 所有涉及该 Mapper 的写操作（insert/update/delete）必须在事务中执行，否则无法触发缓存清理
• 避免在事务内混合使用带缓存和不带缓存的查询（如 useCache="false" 与默认缓存混用），易导致状态错乱