为什么你的MyBatis缓存没生效？10个关键配置点逐一排查

第一章：MyBatis缓存机制概述

MyBatis 作为一款优秀的持久层框架，提供了强大的 SQL 映射与对象关系映射功能。其中，缓存机制是提升数据库操作性能的关键特性之一。通过合理利用缓存，可以有效减少对数据库的重复查询，显著提高系统响应速度。

缓存的基本分类

MyBatis 的缓存体系主要分为两种类型：

• 一级缓存（Local Cache）：默认开启，作用范围为 SqlSession 级别。在同一个 SqlSession 中，执行相同 SQL 查询时，会从缓存中直接返回结果，避免重复访问数据库。
• 二级缓存（Global Cache）：作用范围为 Mapper namespace 级别，多个 SqlSession 可共享此缓存。需手动启用，并要求返回对象实现 Serializable 接口。

缓存工作流程示意

graph TD A[发起查询请求] --> B{一级缓存是否存在?} B -->|是| C[直接返回缓存结果] B -->|否| D{二级缓存是否存在?} D -->|是| E[写入一级缓存并返回] D -->|否| F[执行数据库查询] F --> G[将结果写入一级和二级缓存] G --> H[返回查询结果]

启用二级缓存配置示例

在 Mapper XML 文件中添加以下配置以启用二级缓存：

<!-- 开启当前命名空间的二级缓存 -->
<cache eviction="LRU" flushInterval="60000" size="512" readOnly="true"/>

上述代码中：

• eviction="LRU" 表示使用最近最少使用策略清除缓存；
• flushInterval="60000" 指定每隔 60 秒刷新一次缓存；
• size="512" 表示最多缓存 512 个查询结果；
• readOnly="true" 表示缓存返回只读对象，可提升性能。

缓存类型	作用域	默认状态	是否共享
一级缓存	SqlSession	开启	否
二级缓存	Namespace	关闭	是

第二章：一级缓存失效的常见原因与解决方案

2.1 理解SqlSession级别缓存的作用域

SqlSession级别的缓存是MyBatis提供的默认一级缓存，其作用域限定在同一个SqlSession实例内。这意味着在该会话中执行的相同SQL查询将优先从缓存中获取结果，从而减少数据库访问次数。

缓存生命周期与会话绑定

一级缓存的生命周期与SqlSession完全一致。一旦会话关闭或清空，缓存数据即被清除。这保证了数据的隔离性，避免跨会话的数据污染。

查询流程示例

<select id="selectUser" resultType="User">
  SELECT * FROM users WHERE id = #{id}
</select>

当同一SqlSession中重复调用此语句时，MyBatis首先检查本地缓存是否存在对应键值。若命中，则直接返回结果；否则访问数据库并缓存结果。

• 缓存基于SQL语句、参数、环境生成唯一键
• 任何增删改操作会清空当前缓存
• 不同SqlSession之间缓存不共享

2.2 不同线程或SqlSession导致缓存隔离的实践分析

在MyBatis中，一级缓存默认基于SqlSession生命周期存在。当多个线程操作同一数据时，即使使用相同Mapper接口，若各自持有独立SqlSession，则彼此之间无法共享缓存。

缓存隔离示例

// 线程1
SqlSession session1 = sqlSessionFactory.openSession();
UserMapper mapper1 = session1.getMapper(UserMapper.class);
User u1 = mapper1.selectById(1); // 查询并缓存

// 线程2
SqlSession session2 = sqlSessionFactory.openSession();
UserMapper mapper2 = session2.getMapper(UserMapper.class);
User u2 = mapper2.selectById(1); // 无法命中session1的缓存

上述代码中，session1 和 session2 分属不同线程，其一级缓存互不相通，导致相同查询被执行两次。

核心机制说明

• 一级缓存作用域为SqlSession实例级别
• 不同SqlSession拥有独立的缓存Map
• 线程间无法直接共享本地缓存数据

该设计保障了事务隔离性，但也要求开发者在高并发场景下关注缓存一致性问题。

2.3 增删改操作如何触发一级缓存清空

缓存一致性机制

MyBatis 一级缓存位于 SqlSession 级别，当执行增、删、改操作时，为保证数据一致性，框架会自动清空当前会话中的缓存。这一机制避免了脏读问题。

触发清空的操作类型

以下操作将触发缓存清空：

• INSERT：新增记录后，原有查询结果可能失效
• UPDATE：数据变更直接影响缓存中的旧值
• DELETE：删除操作导致缓存中部分数据不完整

<update id="updateUser" parameterType="User">
  UPDATE users SET name = #{name} WHERE id = #{id}
</update>

该 SQL 执行后，SqlSession 内所有先前的查询缓存将被清除，确保后续查询获取最新数据。

底层执行流程

清空流程：执行更新语句 → 检测操作类型 → 调用 clearLocalCache() → 清空 HashMap 缓存实例

2.4 预编译语句与参数变化对缓存命中率的影响

预编译语句（Prepared Statements）通过将SQL模板预先解析并缓存执行计划，显著提升数据库查询效率。然而，参数的变化方式直接影响执行计划的复用性。

参数敏感性与执行计划缓存

当参数值导致数据分布差异较大时，优化器可能为同一SQL生成不同执行计划。若缓存策略未识别这种差异，将降低缓存命中率。

参数类型	缓存命中率	说明
固定范围	高	如 WHERE id = ?，值稳定时易命中
动态范围	低	如 WHERE age > ?，值跨度大导致重编译

PREPARE stmt FROM 'SELECT * FROM users WHERE age > ?';
SET @age = 18;
EXECUTE stmt USING @age;

上述代码中，首次执行会生成并缓存执行计划。若后续@age值频繁变动且统计信息差异显著，优化器可能拒绝复用原计划，触发重新编译，从而降低缓存利用率。

2.5 手动控制缓存刷新时机的最佳实践

在高并发系统中，缓存的刷新时机直接影响数据一致性与系统性能。手动控制缓存刷新可避免自动刷新带来的资源浪费。

使用显式刷新命令

通过调用明确的刷新接口，开发者可在关键业务操作后主动更新缓存：

// 手动触发缓存刷新
cacheManager.refresh("productList");

该方式适用于数据变更频繁但非实时同步的场景，确保在事务提交后执行，避免脏读。

结合事件驱动机制

• 监听数据库变更事件（如 Binlog）
• 通过消息队列异步通知缓存节点
• 由消费者执行具体刷新逻辑

此模式解耦数据源与缓存层，提升系统可维护性。

刷新策略对比

策略	实时性	系统开销
定时刷新	低	中
手动触发	高	低

第三章：二级缓存配置的核心要素

3.1 启用二级缓存的必要条件与全局配置

在 MyBatis 中启用二级缓存前，需满足若干必要条件：映射的 POJO 类必须实现 Serializable 接口，且对应的 SQL 映射文件中需显式开启缓存支持。

全局配置开启

在 mybatis-config.xml 中启用二级缓存：

<settings>
  <setting name="cacheEnabled" value="true"/>
</settings>

该配置默认为 true，表示全局允许使用二级缓存。若关闭，则所有命名空间的缓存功能将被禁用。

映射级别启用

在特定的 *Mapper.xml 中添加缓存声明：

<cache/>

此标签表示当前命名空间启用 LRU 缓存机制，默认清空策略为最近最少使用，缓存容量为 1024 条记录。

属性	说明
eviction	回收策略：LRU、FIFO 等
flushInterval	刷新间隔（毫秒）
size	最大缓存条目数

3.2 使用@CacheNamespace注解定制缓存策略

在MyBatis中，`@CacheNamespace`注解用于为特定的Mapper接口配置自定义的二级缓存策略，提升数据访问性能。

基本用法

通过在Mapper接口上添加注解，可启用缓存并指定相关属性：

@CacheNamespace(
  eviction = FifoEvictionPolicy.class,
  flushInterval = 60000,
  size = 512,
  readWrite = false
)
public interface UserMapper {
  User selectById(int id);
}

上述代码配置了FIFO（先进先出）淘汰策略，缓存刷新间隔为60秒，最大缓存512个对象，且为只读模式。其中： - `eviction`：指定缓存回收策略； - `flushInterval`：定期清空缓存的时间间隔（毫秒）； - `size`：最多缓存对象数； - `readWrite`：是否支持读写，设为false时使用序列化克隆避免共享引用问题。

缓存策略对比

策略	适用场景	特点
Lru	高频热点数据	移除最近最少使用对象
Fifo	定时批量处理	按进入顺序移除

3.3 缓存序列化与结果映射兼容性问题解析

在分布式缓存场景中，对象序列化方式与ORM结果映射的结构兼容性直接影响数据一致性。若缓存使用JSON序列化而实体类字段变更，易导致反序列化失败。

常见序列化方案对比

• JSON：可读性好，但不支持类型保留
• Protobuf：高效紧凑，需预定义schema
• Kryo：Java本地序列化，性能高但跨语言支持差

典型异常示例

com.fasterxml.jackson.databind.exc.MismatchedInputException: 
Cannot construct instance of `com.example.User` (although at least one Creator exists): 
cannot deserialize from Object value (no delegate- or property-based Creator)

该错误通常因缓存中的JSON字段与目标类属性不匹配引发，如数据库查询返回的别名未映射到DTO。

解决方案建议

方案	适用场景	注意事项
统一使用DTO进行缓存序列化	微服务间数据交换	避免直接缓存Entity
启用Jackson的@JsonIgnoreProperties(ignoreUnknown = true)	字段频繁变更	防止新增字段导致反序列化失败

第四章：影响缓存生效的关键外部因素

4.1 Mapper接口方法返回类型对缓存的支持差异

在MyBatis中，Mapper接口的返回类型直接影响二级缓存的行为表现。不同的返回类型会触发不同的结果处理机制，进而影响缓存的写入与命中。

支持缓存的返回类型

当方法返回类型为以下类型时，查询结果会被正常缓存：

• 实体类对象（如 User）
• List<T>
• Map<String, Object>

<select id="selectUserById" resultType="User" useCache="true">
  SELECT * FROM user WHERE id = #{id}
</select>

该配置下，返回单个User对象或List<User>时，结果将被存入二级缓存，后续相同SQL可直接命中。

不支持缓存的返回类型

若返回类型为void、int等原始操作类型，即使设置useCache="true"，也不会写入缓存。

int updateUser(@Param("id") Long id);

此类方法用于增删改操作，执行后还会**清空**当前命名空间的缓存，以保证数据一致性。

4.2 关联查询与嵌套结果中的缓存共享陷阱

在使用MyBatis等ORM框架进行关联查询时，嵌套结果（nested result）映射常用于处理一对多或多对一关系。然而，当多个查询共用同一缓存区域（cache namespace）时，容易引发缓存共享陷阱。

缓存命中的副作用

若主查询与嵌套子查询均启用二级缓存，更新操作可能导致部分数据未及时失效。例如：

<select id="selectBlogWithAuthor" resultMap="blogMap" useCache="true">
  SELECT * FROM blog b JOIN author a ON b.author_id = a.id
</select>

该查询将博客与作者信息一并加载，若其他语句仅更新author表但未清除博客缓存，则可能返回过期的联表数据。

规避策略

• 为不同实体划分独立缓存命名空间
• 在关联查询中显式设置useCache="false"
• 结合flushCache属性控制刷新行为

4.3 第三方缓存集成（如Redis）配置验证要点

在集成Redis作为第三方缓存时，首先需验证连接配置的正确性。常见配置项包括主机地址、端口、密码及数据库索引。

spring:
  redis:
    host: 192.168.1.100
    port: 6379
    password: mysecretpassword
    database: 0
    timeout: 5s

上述YAML配置中，host和port定义了Redis服务位置，password用于认证，database指定逻辑数据库编号，timeout防止阻塞过久。

连接健康检查

应用启动后应主动执行PING命令检测连通性。可通过Spring Boot Actuator暴露/actuator/health端点，观察Redis状态是否为UP。

序列化兼容性验证

确保客户端与服务端数据序列化格式一致，推荐使用JSON或JDK序列化。若使用自定义RedisTemplate，需检查Key和Value的序列化器设置，避免反序列化失败。

4.4 事务边界与提交行为对缓存可见性的影响

在分布式系统中，事务的边界定义直接影响缓存数据的可见性与一致性。当一个事务提交时，其对数据库的修改是否立即反映到缓存层，取决于事务提交时机与缓存更新策略的协同。

缓存更新时机

常见的策略包括“写直达”（Write-Through）和“写回”（Write-Behind）。若缓存更新发生在事务提交前，其他事务可能读取到尚未持久化的数据，导致脏读。

事务提交与缓存同步

推荐在事务成功提交后更新缓存，确保数据最终一致。以下为典型处理流程：

func updateUser(db *sql.DB, cache Cache, user User) error {
    tx, err := db.Begin()
    if err != nil {
        return err
    }
    defer tx.Rollback()

    // 在事务中更新数据库
    _, err = tx.Exec("UPDATE users SET name = ? WHERE id = ?", user.Name, user.ID)
    if err != nil {
        return err
    }

    // 仅在事务提交成功后更新缓存
    if err = tx.Commit(); err != nil {
        return err
    }
    cache.Set(fmt.Sprintf("user:%d", user.ID), user) // 缓存可见性生效
    return nil
}

该代码确保缓存更新发生在事务提交之后，避免其他事务读取到未提交数据，保障了缓存的可见性与一致性。

第五章：缓存调试与性能优化建议

监控缓存命中率

缓存命中率是衡量缓存系统效率的核心指标。可通过 Redis 的 INFO 命令实时获取统计信息：

redis-cli INFO stats | grep -E "keyspace_hits|keyspace_misses"

理想命中率应高于 90%。若命中率偏低，需分析热点数据分布并调整缓存策略。

使用短 TTL 避免雪崩

大量缓存同时失效易引发数据库雪崩。推荐为不同业务设置差异化过期时间，并引入随机抖动：

• 基础 TTL 设置为 30 分钟
• 附加 1~5 分钟的随机偏移
• 关键数据启用后台异步刷新

ttl := time.Minute*30 + time.Duration(rand.Intn(300))*time.Second
client.Set(ctx, key, value, ttl)

合理选择序列化方式

序列化直接影响缓存体积与读写性能。常见格式对比：

格式	体积	编解码速度	适用场景
JSON	中等	快	跨语言服务
Protobuf	小	极快	高性能内部通信
Gob	较大	慢	纯 Go 环境

启用连接池与 Pipeline

单连接频繁访问会成为瓶颈。使用连接池控制并发，并通过 Pipeline 批量执行命令：

客户端 → 连接池（max=100） → Redis 实例 多请求合并 → 单次网络往返 → 批量响应返回