MyBatis缓存机制与注解式开发实战指南

项目标题: MyBatis-缓存与注解式开发

搞Java后端的兄弟应该都有同感，MyBatis这玩意儿上手容易，但真要把它用好、用明白，尤其是缓存机制和注解式开发这两块，坑是真不少。我前前后后用MyBatis做了好几个项目，从最早的XML堆SQL，到后面全面转向注解，再到处理各种缓存不一致的线上故障，可以说把能踩的坑都踩了一遍。今天这篇文章，我就把我在实际项目里关于MyBatis缓存和注解式开发的理解、配置方式以及踩坑经验一次性讲清楚，希望能给正在用或者准备用MyBatis的朋友一些参考。

这篇文章适合谁看？如果你是刚开始接触MyBatis的新手，可以把它当成一份进阶的实战笔记，把缓存和注解这两块从原理到应用一次性理顺；如果你已经用了很久MyBatis，那可以直接跳到第4章看问题排查的部分，这些坑都是我实际在线上环境中遇到的，绝对有参考价值。文中所有内容基于MyBatis 3.x版本，结合Spring Boot 2.x/3.x环境来讲解，我尽量做到既有原理拆解，又有可以直接抄的配置。

1. 先从缓存聊起：MyBatis缓存体系到底怎么运作的

1.1 一级缓存与二级缓存的本质区别

很多初学者问我，MyBatis的缓存到底分几级？其实标准答案就两级：一级缓存是SqlSession级别的，二级缓存是mapper级别的。但很多人只记住了这个结论，并不知道背后到底是怎么回事，我在这里用最直白的方式说清楚。

一级缓存是MyBatis默认开启的，它的作用范围是同一个SqlSession。在同一个SqlSession中执行两次完全相同的查询，第二次不会走数据库，而是直接返回缓存里的结果。这个机制在底层是通过一个PerpetualCache对象来实现的，这个对象本质上就是一个HashMap，key是缓存的标识，value是查询结果。为什么MyBatis要默认开一级缓存？因为SqlSession的生命周期通常很短，在Spring中每次请求都会新建SqlSession，所以它的缓存作用域非常有限，几乎不存在缓存与数据库不一致的风险，但也不排除某些极端情况，这个我后面专门用一节来讲。

二级缓存是mapper级别的，它的作用范围可以跨越多个SqlSession。也就是说，多个SqlSession执行同一个mapper中的相同查询，如果是第二次以后执行的，可以直接命中二级缓存，而不需要经过一级缓存再查数据库。二级缓存默认是关闭的，需要你在mapper的XML文件里显式配置<cache/>标签或者在Mapper接口上使用@CacheNamespace注解来开启。

我打个比方，一级缓存就像你办公桌上的便签纸，自己记自己看，转身可能就扔了；二级缓存就像团队共享的公共知识库，大家都能用，但也需要额外的维护成本。所以二级缓存的开启必须谨慎，不是所有查询都适合放进二级缓存的。

这里要额外提一个概念，很多人会问MyBatis是不是有三级缓存？其实标准的MyBatis只有两级，网络上传的"三级缓存"通常是指集成Spring或第三方缓存框架（比如Redis）之后的说法，比如Spring的Cache Abstraction就是在MyBatis之外再包一层，那是另一套体系，不在本节讨论范围内。不过在实际项目中，我们经常是MyBatis二级缓存和Redis缓存一起用，这就需要在架构设计时想清楚边界，我在第3章会专门展开这一块。

1.2 缓存Key的生成机制与命中条件

想真正理解缓存，就必须搞清楚缓存的key是怎么算出来的。不看源码的话，很多人在排查缓存命中率问题时，都会一头雾水。我直接说结论：MyBatis的缓存key是由CacheKey对象生成的，它由以下几个要素组合而成：

• Mapper的ID（也就是namespace加上方法名）
• 查询的SQL语句
• SQL语句中传递的参数值
• 环境ID（environment id）

也就是说，你和朋友两个人，用同一个SqlSession，执行同一个Mapper的同一个方法，传入完全相同的参数，那就能命中同一个缓存key。如果SQL里多了一个空格或者参数顺序不一样，key就变了，缓存自然就命不中。

在实际开发中，有一个很容易被忽视的点：MyBatis缓存key包含的是参数的"值"而不是参数的"引用"。如果参数是一个Java对象，那MyBatis会遍历对象的属性来生成key。这就带来一个问题：如果你传入的对象属性值没变，但对象本身被修改了，缓存的key不会变，命中的还是旧值。我在项目中就遇到过类似问题，这里先埋个伏笔，第4章会详细说怎么排查。

另外还有一个关键点，一级缓存的命中是依赖SqlSession的。在Spring集成环境下，如果你用SqlSessionTemplate，它默认会为每次数据库操作创建新的SqlSession，这也就是为什么很多人反映Spring集成MyBatis后，一级缓存好像"失效"了——其实不是失效，而是SqlSession变了。这个问题在Spring事务环境下又会有所不同，如果开启了事务，Spring会把SqlSession绑定到当前线程上，事务范围内的多个查询可以共享一级缓存。搞清楚这一点，对理解后面的缓存失效问题至关重要。

1.3 缓存失效的四大典型场景

我在面试候选人的时候，特别喜欢问一个问题："什么情况下MyBatis缓存会失效？"能完整答出来的人确实不多。我梳理一下实际开发中最常见的四类缓存失效场景，大家可以对照自己的代码排查。

第一种是手动清空缓存。在Mapper中执行任何新增、修改、删除操作时，MyBatis默认会清空当前mapper的缓存（包括一级和二级），这是为了避免脏读。这个机制在XML和注解模式下都生效，没法通过配置关掉。很多人的理解误区是：mysBatis的缓存清空粒度是整个mapper，而不是具体某条数据。也就是说，你更新了一条记录，整个mapper的缓存全部失效。这在数据量大的时候会带来明显的性能波动。

第二种是跨SqlSession操作。一级缓存的作用域只在同一个SqlSession内，如果你开了两个SqlSession，第一个查完之后，第二个再查同样的数据，根本不会命中一级缓存。这个场景在Spring集成下特别常见，因为Spring容器管理的SqlSession是不固定的。

第三种是自动提交与事务边界导致缓存失效。如果MyBatis的localCacheScope配置为STATEMENT，那么每执行一条SQL语句之后，一级缓存就会立即被清空，这样一级缓存就形同虚设。SESSION是默认值，保留了SqlSession级别的缓存，但如果事务提交或回滚，缓存也会清理。

第四种是查询返回了List等集合对象，但是使用方修改了集合内容。因为二级缓存存储的是对象引用，如果查询出来后直接修改了集合里的对象属性，下次命中缓存时拿到的就是被修改过的数据。这个问题非常隐蔽，我在一个报表项目中就踩过，当时查出来的列表被业务代码改了字段值，结果后续所有查询都返回了脏数据，排查了很久才发现是缓存里存的对象被外部修改了。

2. 注解式开发：用代码代替XML的实战之道

2.1 核心注解逐一拆解

MyBatis从3.0开始支持注解式开发，到现在已经完全成熟了。很多人还在纠结到底用XML还是注解，其实没必要对立起来，完全可以混合使用。我自己的习惯是：简单的CRUD用注解，复杂的动态SQL用XML，这样既简洁又不失灵活性。

先来说说最常用的四个增删改查注解：

• @Select：用于查询语句，比如@Select("SELECT * FROM user WHERE id = #{id}")
• @Insert：用于插入语句，@Insert("INSERT INTO user(name, age) VALUES(#{name}, #{age})")
• @Update：用于更新语句
• @Delete：用于删除语句

这四个注解的参数都是SQL字符串。需要注意的是，注解里的SQL是不会经过XML解析的，所以<、>这些特殊符号在注解中不需要转义，但如果你需要动态拼接SQL，就不能直接用字符串拼接，得靠<script>标签（在注解里可以这样写：@Select("<script>SELECT * FROM user WHERE 1=1 <if test='name != null'>AND name = #{name}</if></script>")）或者@SelectProvider来实现。

除了上面四个，还有几个注解在开发中也很关键：

@Param：用来给SQL参数命名。如果你的方法有多个参数，不添加@Param注解时，MyBatis只能通过arg0、arg1或者param1、param2来引用参数，可读性很差。加了@Param("userId")之后，SQL里就可以直接写#{userId}了。另外还有一个重要原因：当参数列表大于1时，MyBatis默认会把参数包装成一个Map，@Param的值就是这个Map的key。

@Results和@Result：用于结果集映射。如果数据库字段名和Java属性名不一致，可以用这两个注解来做映射。比如：

java复制@Select("SELECT id, user_name AS userName, age FROM user WHERE id = #{id}")
@Results(id = "userMap", value = {
    @Result(property = "id", column = "id"),
    @Result(property = "userName", column = "user_name"),
    @Result(property = "age", column = "age")
})
User getUserById(Long id);

这里有几点要注意。第一，@Results有一个id属性，这个id可以复用，在其它方法上通过在@ResultMap("userMap")中引用。第二，如果你定义了@Results但没有指定id，MyBatis默认会把它挂在方法名下，想跨方法复用就不太方便。第三，如果是多表关联查询，还要用到@One和@Many，这两个注解分别对应一对一和一对多的关联映射，不过我个人建议复杂关联查询还是别用注解，直接用XML的<resultMap>更清晰。

2.2 注解式开发的适用边界

说完了核心注解，再来聊聊什么时候该用注解，什么时候不建议用。这算是我写了几年MyBatis之后总结出来的经验，不一定适用于所有团队，但值得参考。

注解开发最大的优势是快。单表的增删改查，一个注解搞定，代码量比XML少很多，可读性也更高，而且类型安全有保障。其次，注解开发不需要维护独立的XML文件，不会出现"改了XML忘了重启"这种典型问题。

但注解开发也有明显的劣势。第一，动态SQL的表达能力受限。虽然可以用<script>标签来写动态SQL，但在一段Java注解字符串里写复杂的动态SQL，可读性和维护性都很差，编译器也帮不了你。第二，SQL和Java代码耦合在一起，一旦SQL需要调整，就得改Java代码重新编译部署，对于需要频繁调优SQL的项目来说并不友好。第三，团队协作时冲突概率增加，大家同改一个Java文件，Git冲突是常有的事，而XML文件是独立的，冲突面会小一些。

所以我的建议是：单表CRUD、简单条件查询可以用注解；涉及多表关联、复杂动态条件、批量操作、需要复用SQL片段的，一律用XML。另外还有一个点，如果你的项目里有DBA角色会直接修改SQL，那最好还是用XML，因为DBA通常不希望在Java代码里翻SQL。

2.3 注解开发中的动态SQL实现方案

既然说到了注解开发的边界问题，那就绕不开动态SQL。实际上注解开发里也是可以做动态SQL的，只是要选对方案。

最直接的方式就是前面提到的<script>标签。在注解里直接把动态SQL用<script>包起来，比如：

java复制@Select("<script>" +
        "SELECT * FROM user " +
        "WHERE 1=1 " +
        "<if test='name != null and name != \"\"'>" +
        "AND name LIKE CONCAT('%', #{name}, '%')" +
        "</if>" +
        "</script>")
List<User> searchUsers(@Param("name") String name);

这种方式虽然能用，但字符串拼接的体验确实不好，如果SQL特别长，整段代码可读性会急剧下降。我建议只在动态条件不超过两个的情况下使用。

如果动态SQL比较复杂，更推荐用@SelectProvider。它的原理是把SQL的生成逻辑抽取到一个独立的类中，用Java代码来动态拼SQL。比如：

java复制@SelectProvider(type = UserSqlProvider.class, method = "searchUsers")
List<User> searchUsers(@Param("name") String name, @Param("age") Integer age);

对应的Provider类：

java复制public class UserSqlProvider {
    public String searchUsers(Map<String, Object> params) {
        return new SQL() {{
            SELECT("*");
            FROM("user");
            if (params.get("name") != null) {
                WHERE("name LIKE CONCAT('%', #{name}, '%')");
            }
            if (params.get("age") != null) {
                WHERE("age = #{age}");
            }
        }}.toString();
    }
}

这里用到了MyBatis自带的SQL类，它提供了一种类似流式编程的方式来构建SQL，比字符串拼接要安全得多。不过要注意，@SelectProvider方法的返回值只能是String，而且方法的入参需要和Mapper方法的入参保持一致，或者直接接收一个Map。

实际上，在注解中用Provider方式写动态SQL的场景，我个人感觉已经比较少了，因为MyBatis-Plus的Wrapper机制解决了很多动态拼SQL的痛点。但如果你想保持纯MyBatis，Provider还是个非常可靠的方案，尤其是遇到那种条件特别多，又不想写XML的场景。

3. 缓存与注解结合实战：Spring Boot项目里的正确姿势

3.1 注解模式下如何开启与配置二级缓存

前面聊了缓存原理和注解开发的基础，现在把两者结合起来，聊聊在Spring Boot项目中，使用注解式开发时如何正确配置和使用缓存，以及有哪些需要特别注意的地方。

首先明确一个概念：二级缓存的开启和代码形式没有直接关系。不管你是用XML还是注解开发，二级缓存的开启方式在原则上是相同的——需要在Mapper上做标记。区别只是标记的形式：XML中加<cache/>标签，注解开发中则是在Mapper接口上添加@CacheNamespace注解。

实际开发中，我见过很多朋友在注解式开发的项目里尝试开启二级缓存，最后都遇到一个问题：注解开发时，二级缓存默认只对查询方法生效，但缓存刷新（即执行增删改后清空缓存）的行为，在注解模式下需要额外配置。因为XML中<cache/>标签自带了一些刷新策略的参数，而@CacheNamespace注解的属性有限。我通常的做法是这样的：

java复制@CacheNamespace(flushInterval = 60000, size = 1024, readWrite = true)
public interface UserMapper {
    @Select("SELECT * FROM user WHERE id = #{id}")
    User getUserById(Long id);

    @Insert("INSERT INTO user(name, age) VALUES(#{name}, #{age})")
    int insertUser(User user);
}

这里有三个核心参数需要解释一下：

flushInterval：缓存刷新间隔，单位是毫秒。上面配置的是60秒刷新一次。如果不配置，默认情况下缓存只有在执行增删改语句时才会刷新，这在某些数据变更不频繁的场景下可能造成老数据长期驻留。

size：缓存可以存储的条目数量上限。默认值是1024，如果超过这个数，MyBatis会按照LRU（最近最少使用）策略移除部分缓存。

readWrite：是否为读写缓存。默认为true，表示返回给调用方的是一个缓存对象的序列化副本，相当于每次拿到的都是"复制品"，修改它不会影响缓存中的原始对象；如果是false，那返回的就是缓存对象的引用，性能更好但是有脏数据风险。

这里要特别提醒一个点，使用@CacheNamespace时，缓存默认是基于当前Mapper命名空间的，不参与全局缓存共享。如果想让多个Mapper共享同一个缓存区域，需要使用@CacheNamespaceRef注解来指定引用其他的namespace。这个机制在使用注解开发时很容易被忽视，但如果你在一个业务流程里要跨多个Mapper查同一份基础数据，共享缓存能少查很多次数据库。

3.2 集成Spring缓存：用注解管理更复杂的缓存策略

单纯用MyBatis自带的二级缓存，有一个绕不过去的局限：它只能作用于Mapper层，没法做方法级别的粒度控制。比如我想对某个Service方法做缓存，而且这个Service方法内部调用了好几个Mapper，用MyBatis二级缓存就很难实现，因为缓存是挂在mapper上的，跨mapper的数据一致性没法保证。这时候通常的做法是把Spring的@Cacheable、@CacheEvict等注解集成进来，在Service层做缓存管理。

Spring的缓存抽象和MyBatis的二级缓存并不冲突，它们可以叠加使用。我比较推荐的组合方案是：MyBatis二级缓存关闭，使用Spring Cache + Redis来做业务级缓存。这样既保留了MyBatis查询数据库的能力，又能在Service层灵活控制缓存策略。

举个例子：

java复制@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;

    @Cacheable(value = "user", key = "#id")
    public User getUserById(Long id) {
        return userMapper.getUserById(id);
    }

    @CacheEvict(value = "user", key = "#user.id")
    public void updateUser(User user) {
        userMapper.updateUser(user);
    }
}

这种方式的优势很明显：

第一，缓存粒度从"整个mapper"细化到了"单个方法+参数"，控制更灵活。第二，缓存存储介质可以选Redis，天然支持分布式环境，而MyBatis默认的二级缓存是本地内存缓存，在多实例部署情况下，每个实例各缓存各的，数据一致性很难保证。第三，Spring Cache的注解表达力更强，@Cacheable、@CacheEvict、@CachePut、@Caching组合使用，可以实现很多复杂的缓存策略。

不过，集成Spring Cache也有一个需要特别注意的坑：@Cacheable的失效场景很多，且不易察觉。比如同一个类内部方法调用，@Cacheable是不生效的，因为Spring AOP代理没有介入内部调用。再比如方法不是public的，也不生效。这些坑我在第4章会结合实际排查过程详细说明。

3.3 生产环境下的缓存参数配置建议

聊完了缓存和注解怎么结合，再来说说生产环境下的实际配置建议。这些参数在不同的项目规模下有不同的最佳实践，我给出的是我自己经验里比较稳妥的默认值，大家可以根据项目实际情况做调整。

先看MyBatis本身的几个关键配置：

yaml复制mybatis:
  configuration:
    cache-enabled: true
    local-cache-scope: SESSION
    map-underscore-to-camel-case: true

第一个cache-enabled控制全局二级缓存的开关，默认就是true。如果全局关了，就算Mapper上加了@CacheNamespace也不生效。第二个local-cache-scope控制一级缓存的作用域，建议保持SESSION。第三个map-underscore-to-camel-case虽然不是缓存配置，但在注解开发中非常重要，它可以让你少写很多@Results映射，直接把数据库的下划线字段自动映射成驼峰属性。

再来看Spring Cache + Redis的配置。这里有一个特别关键的参数，就是Redis的timeout和连接池大小。如果并发高而连接池不够，缓存操作就会成为瓶颈。我通常这样配置：

yaml复制spring:
  cache:
    type: redis
    redis:
      time-to-live: 3600000
      cache-null-values: false
  redis:
    timeout: 2000ms
    lettuce:
      pool:
        max-active: 16
        max-idle: 8
        min-idle: 2

time-to-live是默认的缓存过期时间，我建议按业务类型拆分不同的缓存区域，比如用户基本信息缓存5分钟，配置类缓存1小时，而不是所有缓存都用一个统一的过期时间。cache-null-values建议设置为false，也就是不缓存空值，这样可以防止缓存穿透。但也有些场景需要缓存空值来保护数据库，这里没有绝对，只能根据业务来权衡。

还有一个经常被忽略的配置，是Redis序列化方式的设置。Spring Boot默认用的是JDK序列化，会有两个问题：一是序列化内容有较多冗余信息，占用内存大；二是可读性差，用redis-cli查看缓存数据时完全看不懂。我建议自定义一个RedisCacheManager，把key和value都改为StringRedisSerializer，value里存JSON字符串。长这样：

java复制@Bean
public RedisCacheManager cacheManager(RedisConnectionFactory factory) {
    RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
            .serializeKeysWith(SerializationPair.fromSerializer(new StringRedisSerializer()))
            .serializeValuesWith(SerializationPair.fromSerializer(new GenericJackson2JsonRedisSerializer()))
            .entryTtl(Duration.ofMinutes(30));
    return RedisCacheManager.builder(factory)
            .cacheDefaults(config)
            .build();
}

这样设置完之后，Redis里存的key和value都肉眼可读，排查问题时清爽很多。

4. 常见问题排查与避坑指南实录

4.1 二级缓存导致的数据脏读，一次线上故障复盘

这个故障我记得特别清楚，发生在一次版本发布后的第三天。当时线上报了一个问题：用户修改了自己的昵称，页面显示已经修改成功，但刷新之后偶尔会变成旧昵称。一开始我们怀疑是Redis缓存的问题，查了一圈后发现Redis的ttl设置也正常。

后来我们把目光聚焦到MyBatis的二级缓存上。排查发现，用户信息这个Mapper开启了@CacheNamespace，而我们的Service层在更新用户信息时，调用的是另一个Mapper（比如UserInfoMapper）里的方法。由于二级缓存是以namespace为隔离单位的，UserInfoMapper执行了update操作后，只清空了UserInfoMapper自己的缓存，UserMapper里的缓存完全不受影响。

而查询用户信息走的是UserMapper，它的缓存里存着的还是旧昵称，所以刷新页面后就会读到旧数据。这就是典型的跨namespace缓存数据不一致问题，非常隐蔽。

解决方案有两个：第一种是把用户信息相关的所有查询和更新都放在同一个Mapper中，让缓存失效动作覆盖到所有相关操作；第二种是在更新操作时，主动调用SqlSession.clearCache()来清空一级缓存，或者通过@CacheEvict类似的机制去清理对应的二级缓存。我更推荐第一种，从设计上规避，而不是靠"记得去清理"来兜底。

4.2 注解SQL拼接报错与参数绑定异常排查

注解开发另一个常见坑是SQL拼接和参数绑定问题。我见过最多的一种报错是：

code复制org.apache.ibatis.binding.BindingException: Parameter 'xxx' not found. Available parameters are [arg0, param1, ...]

这个报错的原因很直接：方法有多个参数，却没有给每个参数加@Param注解。MyBatis在为SQL语句绑定参数时，不知道#{xxx}里的xxx指的是哪个参数。解决办法也很简单，给每个参数加上@Param("xxx")就行。

还有一种很隐蔽的SQL拼接错误，出现在<script>标签里写动态条件时。比如：

java复制@Select("<script>" +
        "SELECT * FROM user " +
        "<where>" +
        "<if test='name != null'>" +
        "AND name = #{name}" +
        "</if>" +
        "</where>" +
        "</script>")

注意看，<where>标签会自动处理掉开头多余的AND或OR，这是MyBatis给我们省事的地方。但当你把<where>改成自己手写WHERE 1=1的时候，如果没有妥善处理每个条件前的AND，SQL就会变成SELECT * FROM user WHERE 1=1 AND name = ?，虽然也能跑，但总感觉味道不对。我在代码Review中发现很多同事喜欢写WHERE 1=1，这算是历史遗留习惯，如果可以还是尽量用<where>或者<trim>来生成动态条件，阅读性和安全性都会更好。

另外要提醒大家，注解SQL里的#{}和${}的用法和XML完全一致，但${}直接做字符串替换，存在SQL注入风险，且不会走预编译。在注解开发的场景中，很多人因为图省事直接用${}拼接排序字段或者表名，这在我来看非常危险，一定要在代码层面做白名单校验之后再拼接。

4.3 缓存命中率低怎么自查

最后说一个生产运维中经常遇到的问题：缓存配置明明开了，但数据库压力还是很大，缓存命中率低得可怜。这种情况怎么自查？我分享一下自己的排查顺序。

第一步，确认缓存是否真的开启。用mybatis-plus或者原生MyBatis时，项目启动日志里一般会打印配置信息，也可以直接连上线上环境，用一个已知的查询语句执行两次，在数据库端同步观察SQL执行次数。如果两次都会打印出SQL，那就说明缓存没有命中。

第二步，检查SqlSession是否每次操作都新建。在Spring集成环境下，如果你没有加事务，那SqlSessionTemplate每次执行都会新开Session，一级缓存必然命不中。如果你的业务依赖一级缓存来提高性能，那要么加事务让多个查询共享Session，要么换到二级缓存或者Service层的缓存方案。

第三步，检查查询参数是否处于"不可控"的状态。比如查询条件里加了时间戳或者随机数，那每次生成的缓存key都不一样，缓存完全形同虚设。我在代码Review中经常看到有人在查询参数里带了new Date()作为查询条件，这种写法一出来，等于宣告了这个查询放弃了所有缓存能力。

第四步，检查Mapper方法是否直接或间接执行了flushCache=true的操作。MyBatis默认在增删改操作后都会清空缓存，如果你在某个查询方法上设置了@Options(flushCache = Options.FlushCachePolicy.TRUE)，那这个查询也会主动清空缓存。翻一下代码，看看有没有这种"隐藏"的清空操作，有时候一个高频查询会把整个namespace的缓存反复清空，导致缓存形同虚设。

4.4 日常开发中的避坑清单

最后整理一份我自己坚持了很久的避坑清单，都是一个个真实的故障换来的经验，每一条都值得收藏：

• 能不开启二级缓存，就不开启二级缓存，尤其是在分布式环境下，本地的二级缓存很容易变成"脏数据制造机"。如果有缓存需求，优先考虑Redis等外部缓存。
• 如果确实要开二级缓存，请一定将readWrite设为true，虽然会有序列化和反序列化的性能开销，但能保证返回给业务层的是副本，避免缓存对象被修改。
• 多表查询的Mapper，建议不要开启二级缓存。多表关联查询的数据变化方位不可控，任何一张表的数据变更都可能影响到查询结果，而MyBatis只会清空当前mapper的缓存，很难做到精准失效。
• 注解开发和XML开发不要混用在同一个Mapper上。如果你有一个UserMapper用注解，另一个UserMapper用XML，很容易造成两个namespace之间的缓存混乱，排查起来特别费劲。
• 在Spring Boot项目中使用@Cacheable时，相同类内部调用无法触发缓存代理，这是使用Spring Cache最容易踩的坑，需要通过注入自身代理或者把方法抽到另一个Service中来解决。
• 批量操作后主动清理缓存。MyBatis的批量操作有时不会触发每个单条的缓存失效逻辑，比如通过SqlSessionTemplate执行批量更新时，缓存清理的粒度可能和你预想的不一致，最稳妥的做法是在批量操作后手动刷新相关缓存。

5. 写在最后的个人体会

这篇文章写到这里，核心内容基本都覆盖了。说实话，MyBatis的缓存和注解开发本身并不复杂，真正复杂的，是业务代码里各种变量的组合，以及分布式环境下数据一致性的保障。我见过太多项目在初期图省事直接开启二级缓存，上线后遇到各种奇怪问题，最后不得不把二级缓存全部关掉，改用Redis来做统一缓存管理。

在我个人的实践里，缓存不是越高级越好，而是越可控越好。MyBatis的一级缓存、二级缓存可以让步于更清晰的架构设计：Mapper层老老实实做数据读写，Service层用Spring Cache做方法级缓存，分布式场景再用Redis做共享缓存。每一层各司其职，出了问题也知道去哪一层排查。

最后一个隐藏小技巧：在本地开发调试时，如果你想确认某条SQL到底有没有走缓存，可以在MyBatis的配置文件里把日志级别调到TRACE，这样MyBatis会打印出每次执行SQL的缓存命中信息，比如==> Parameters:和<== Total:，以及缓存命中的相关日志。有日志在手，排查缓存问题会轻松很多。希望这篇文章对你有用，也欢迎在评论区聊聊你在MyBatis缓存和注解开发中遇到的那些坑，我们一起交流。