Spring Boot整合MyBatis全解析：从自动装配到分页缓存与慢SQL排查

1. 写在前面MyBatis 和 Spring Boot 这对组合到底该怎么用不踩坑做 Java 后端这些年MyBatis 和 Spring Boot 基本是绑定出现的一对。我刚接触 Spring Boot 那会儿最头疼的不是写 SQL而是搞明白 mybatis-spring-boot-starter 到底帮我省了多少事。后来做过几个中小型管理系统也接手过遗留的 SSM 项目又花了时间翻过 MyBatis 的源码才慢慢摸清这里面的门道。这篇内容不是教科书是我在实际项目里反复验证过的一套经验总结从整合配置、分页插件、缓存机制到源码层面的性能排查和版本兼容问题都涉及。适合两种人看一种是把 MyBatis 配通了但不知道底层怎么跑的初学者另一种是已经用了很久却总被诡异的缓存、分页、慢 SQL 问题折磨的开发同学。看完你至少能少走一半弯路。2. 整合核心MyBatis 在 Spring Boot 里的运行基座2.1 starter 自动装配给你省了哪些事以前用 SSM 整合 MyBatis要写 SqlSessionFactoryBean、MapperScannerConfigurer、DataSourceTransactionManager一堆 XML 配置任何一个路径写错都能折腾半天。Spring Boot 的自动配置把这些全部包装进了mybatis-spring-boot-starter核心就是MybatisAutoConfiguration。它在应用启动时做了这么几件事读取application.yml里的mybatis.*配置初始化Configuration对象根据数据源构建SqlSessionFactory注册SqlSessionTemplate作为 MyBatis 执行 SQL 的门面然后配合MapperScan扫描 Mapper 接口生成代理对象注入容器。我建议你有空翻一下MybatisAutoConfiguration源码它内部有两个关键条件注解ConditionalOnClass({SqlSessionFactory.class, SqlSessionFactoryBean.class})和ConditionalOnBean(DataSource.class)。这意味着只要你引入了 starter 并配置了数据源MyBatis 的默认行为就已经就位了。2.2 配置文件里值得深挖的六个参数很多人配置 MyBatis 就只写一个 mapper-locations其实下面这些参数在特定场景下能救命配置项作用建议mybatis.configuration.map-underscore-to-camel-case数据库下划线字段自动映射驼峰 Java 属性强烈建议设为truemybatis.configuration.cache-enabled全局二级缓存开关默认 true但建议生产按需开启mybatis.configuration.log-impl指定日志实现调试期用StdOutImpl生产用Slf4jImplmybatis.mapper-locationsXML 文件位置多模块项目最容易配错mybatis.type-aliases-package实体类别名包配了之后 resultType 可以直接写类名mybatis.configuration.default-executor-type执行器类型默认 SIMPLE批量操作可改 BATCH我踩过最大的坑是map-underscore-to-camel-case没开导致user_name映射不到userName查询结果全是 null。这类问题不会报错排查起来很费劲。2.3 从 Mapper 接口到数据库调用中间发生了什么很多新手以为 Mapper 接口是直接用 JDBC 调数据库其实不是。MyBatis 在启动时会给每个 Mapper 接口创建一个MapperProxy代理你在 Service 里注入的UserMapper本质上是这个代理对象。每次调用userMapper.selectById(1)流程是这样的SqlSessionTemplate把调用交给SqlSessionSqlSession根据 Mapper 接口的全限定名加方法名查找对应的MappedStatement然后通过Executor执行器走StatementHandler、ParameterHandler、ResultSetHandler完成 JDBC 操作。源码层面最有意思的是MapperMethod类。它把参数封装成ParamMap把方法返回类型和 SQL 模式绑定比如查询走select更新走update。如果 XML 里没有匹配的 id启动时就会报BindingException这种问题通常在项目一启动就暴露平时多留意那串红色报错定位很快。3. 分页插件PageHelper 和 MyBatis-Plus必须掌握的用法与原理3.1 PageHelper 的核心用法与 ThreadLocal 背后的风险分页插件是 MyBatis 生态里使用率最高的组件之一PageHelper 是其中之一。引入依赖dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.7/version /dependency然后代码里这样写PageHelper.startPage(pageNum, pageSize); ListUser userList userMapper.selectAll(); PageInfoUser pageInfo new PageInfo(userList);startPage之后PageHelper 会把分页参数塞进一个ThreadLocal接着执行的第一个查询会被拦截器拦截自动拼接LIMIT。它底层是通过MyBatis的Interceptor机制在Executor.query执行前改写 SQL 原文并把查出来的总条数放到Page对象里。这里有个特别容易翻车的点startPage之后必须紧跟一条查询中间不能插入别的 Mapper 调用否则分页会加错地方。我见过同事在startPage后先调了一个日志插入方法结果分页作用到了插入语句上直接报错。正确的做法是把PageHelper.startPage和查询写在一起中间不要有任何其他数据库操作。3.2 MyBatis-Plus 分页插件更适合工程化项目如果你用的是 MyBatis-Plus分页方式不太一样。首先配置拦截器Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }查询时直接传Page对象PageUser page new Page(1, 10); IPageUser result userMapper.selectPage(page, new QueryWrapperUser().eq(status, 1));MyBatis-Plus 的分页插件比 PageHelper 更推荐的原因在于它不需要ThreadLocal通过分页参数直接传入Page对象线程安全问题少很多而且支持多数据库方言。如果是新项目我更建议直接用 MyBatis-Plus省心。3.3 分页常见的三个坑个个都让人头皮发麻第一个坑是 count 查询性能差。PageHelper 在分页时会自动生成 count 语句如果 SQL 很复杂count 改写可能不正确或者 count 查询比实际列表查询还慢。解决办法是手动写一个 count 方法或者把PageHelper的reasonable参数设为 false避免极端页码导致全表扫描。第二个坑是嵌套查询。当主查询里有子查询或者LEFT JOIN时某些版本的 MyBatis-Plus 可能无法正确解析 count 语句导致分页结果总数错误。干脆把复杂 SQL 拆成两条一条查总数一条查列表。第三个坑是和resultMap的 collection 嵌套集合一起用时分页只对主表生效但collection标签里的子查询可能被循环执行出现 N1 问题。这种情况建议改用嵌套结果映射的方式避免多次查询。4. 缓存机制一级缓存、二级缓存和 Redis 整合的实战心得4.1 一级缓存的“伪失效”现象MyBatis 一级缓存是SqlSession级别的默认开启。在 Spring Boot 中因为每次 Mapper 方法执行往往使用新的SqlSession在没有开启事务的情况下所以一级缓存的作用范围变得非常局限。我最初不明白为什么同一个selectById在同一个方法里调用两次日志里还是打印了两条 SQL。后来才知道Spring 的SqlSessionTemplate为了让 Mapper 线程安全默认情况下代理模式会每次调用都创建独立的SqlSession一级缓存就失效了。只有在Transactional包裹的方法里多个查询共享同一个 SqlSession一级缓存才真正生效。这个逻辑的理解很重要别指望一级缓存帮你减少 SQL它更多是为了数据库事务内的一致性。如果你发现某两个查询之间用了缓存导致数据看不到更新多半是同一个 SqlSession 内执行了 select 又执行 update 后没清缓存这种问题只需要强制刷新或在大事务里注意隔离。4.2 二级缓存开启的正确姿态与脏数据风险二级缓存是 Mapper namespace 级别的跨 SqlSession 共享。开启方式是在 XML 中加入cache/标签然后实体类需要实现Serializable。如果你在多个 Mapper 中 join 查询同一个表问题就来了更新其中一个表的 Mapper 只会清自己 namespace 的缓存另一个 namespace 的旧数据还在导致脏读。我踩过这样一个坑订单表和订单明细表分属两个 Mapper查询订单时关联查询明细数据用了二级缓存。某个同事更新明细后再查订单明细还是老数据排查了半天才发现是缓存导致的。后来统一做法是涉及多表关联的查询一律不开二级缓存只有独立单表查询且数据变更不频繁时才开。更稳妥的方案是把缓存开关从 XML 层面去掉改为mybatis.configuration.cache-enabledfalse全部交给 Redis 或本地缓存框架来做这样可控性更强。4.3 把 Redis 整合成 MyBatis 的二级缓存如果你想用 Redis 缓存 MyBatis 查询结果可以实现org.apache.ibatis.cache.Cache接口把自己的缓存类配置到cache typecom.demo.RedisCache/中。核心需要实现两个方法public class RedisCache implements Cache { private final String id; private RedisTemplateObject, Object redisTemplate; public RedisCache(String id) { this.id id; this.redisTemplate SpringContextHolder.getBean(redisTemplate); } Override public void putObject(Object key, Object value) { redisTemplate.opsForValue().set(id : key, value, 30, TimeUnit.MINUTES); } Override public Object getObject(Object key) { return redisTemplate.opsForValue().get(id : key); } }需要注意的地方有两个一是缓存 key 要包含 namespace 和方法的 id避免不同 Mapper 之间 key 冲突二是 RedisTemplate 的序列化器一定要用 JSON 或 JDK 序列化否则存进去读出来类型不对。另外Cache接口里还有removeObject、clear等生命周期方法更新操作时要主动清掉相关 key否则缓存和数据不一致的问题会再次出现。5. 源码与性能排查从绑定到慢 SQL一步步定位根因5.1 学会看 Mapper 绑定和 PreparedStatement 的生成过程遇到“查询结果不对”或者“参数没生效”这类问题最好的办法是开启 MyBatis 的 SQL 日志看到底生成了一句什么 SQL。配置很简单logging: level: com.demo.mapper: debug除了日志源码层的绑定逻辑也要有概念。MapperRegistry.addMapper会扫描接口并注册MapperProxyFactoryMapperMethod.execute会根据SqlCommandType调不同的方法参数是通过DynamicContext解析的#{}会被替换成?然后走PreparedStatement设置参数${}是直接拼接字符串。我见过不少人因为分页插件、MyBatis-Plus 的自动填充和自定义拦截器同时存在导致 SQL 被多重改写最后的语句完全不是自己写的样子。遇到这种情况先把自定义拦截器排除了再测试通常能很快锁定是谁改写的问题。5.2 Update 执行慢先查这四件事热词里提到“mybatis update 执行慢”这个我在实际项目里处理过好几次。慢不一定和 MyBatis 有关但 MyBatis 的一些用法会放大问题。第一确认更新条件是否走索引。用EXPLAIN UPDATE ...或者EXPLAIN SELECT同条件查询看 key 字段。如果走了全表扫描SQL 再简单也快不了。第二注意批量更新。如果你用 foreach 拼接多条 update 成一个语句MySQL 默认驱动允许rewriteBatchedStatementstrue才高效需要配置 JDBC URL 参数。否则逐条更新的网络往返开销极大。第三检查是否多次执行同一条 update。一级缓存不参与 update但如果你在事务里 select 了某些行又 update 这些行锁等待可能造成慢。用数据库的show processlist看看是不是卡在Waiting for table metadata lock。第四和 MyBatis 本身关系不大的连接池问题。HikariCP连接池默认 maximumPoolSize 是 10如果慢查询占满连接后续所有更新都会排队。日志里一般会看到Connection is not available, request timed out。5.3 打印 SQL 和慢 SQL 日志的实操配置除了logging.level也可以直接指定 MyBatis 的日志实现mybatis: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl这样控制台会直接输出完整的 SQL 和参数。生产环境不建议用 StdOutImpl推荐Slf4jImpl配合 logback 的慢 SQL 过滤器或者用阿里 druid 的慢 SQL 统计。如果你用 MyBatis-Plus可以直接在拦截器里记录执行耗时Intercepts({ Signature(type StatementHandler.class, method query, args {Statement.class, ResultHandler.class}) })这个属于进阶玩法但排查慢查询非常好用。我在一个老项目里就靠这种拦截器把所有超过 500ms 的 SQL 都打印出来然后逐个优化效果显著。6. Spring Boot 整合 MyBatis 的常见问题与避坑清单6.1 版本兼容问题比你想的更坑Spring Boot 2.7.18 是 2.x 的最后一个版本配套的mybatis-spring-boot-starter用 2.3.1 基本没问题。如果是 Spring Boot 3.x必须用mybatis-spring-boot-starter3.0.3 以上因为 Spring Boot 3 基于 Jakarta EE包名从javax改成jakarta老版本的 MyBatis 包会直接启动失败。我建议新项目统一用 Spring Boot 2.7.18 MyBatis 2.3.x这套组合在社区验证足够久各种踩坑文档最全。如果一定要升 Spring Boot 3请把 MyBatis 相关依赖也一起升级不要只升主框架否则可能出现ClassNotFoundException: javax.sql.DataSource这种莫名其妙的问题。还有一个版本坑是 PageHelper 在 Spring Boot 3 下的兼容性早期 1.4.x 不支持需要升级到 2.x。这类问题表现很迷启动时报错找不到拦截器类或者分页不生效。我的排查经验是先看依赖树mvn dependency:tree确认有没有旧版本 mybatis 或 mybatis-spring 冲突。6.2 参数映射与数据类型导致的隐藏问题Oracle 查询时间字段映射到 Java 的LocalDateTime时如果列类型是DATE而 JDBC 驱动默认返回java.sql.Timestamp需要显式指定jdbcTypeDATE或者用TypeHandler。MySQL 的datetime和 Postgres 的timestamp也一样建议在 XML 中显式声明jdbcType避免不同数据库切换时行为不一致。插入自增主键时记得设置insert idinsertUser useGeneratedKeystrue keyPropertyid如果不设置插入后实体对象的 id 是 null后面拿 id 去关联其他表就会出错。#{}传参会自动加单引号${}是字符串替换。前者安全但有 SQL 注入风险其实#{}才是安全做法${}有注入风险。动态排序列名、表名只能用${}但必须自己校验白名单否则被攻击者拼接语句不说性能也可能被恶意查询拖死。6.3 项目结构与打包相关的几个高频问题多模块项目里XML 文件如果放在src/main/java下Maven 打包默认不会把它带进 jar。这个问题特别常见本地测试明明能跑打包部署到服务器就报Invalid bound statement (not found)。解决办法是在 pom.xml 里加 resources 配置resources resource directorysrc/main/java/directory includes include**/*.xml/include /includes /resource /resources或者更好的习惯是 XML 统一放在src/main/resources/mapper下然后配置mybatis.mapper-locationsclasspath:mapper/*.xml。有人会把 Mapper 接口和 XML 放在不同模块这时MapperScan扫描的是接口所在包而 XML 对应的 namespace 必须和接口全限定名一致否则报错。另外一个跟 Spring Boot 项目打包相关但又常被忽略的是线上出了问题本地没有源码怎么排查有人会把 Spring Boot 的 fat jar 反编译。这里提一个简单思路用 IDEA 打开 jar 包里的.class文件反编译工具可以生成 Java 源码。但 MyBatis 的 Mapper XML 是基于 XML 的直接看 class 无法还原建议从一开始就用 MyBatisX 插件把 XML 和接口双向跳转减少这类问题。6.4 日常开发体验提升工具与调试建议在 IDEA 上建 Spring Boot 项目选 Spring Initializr 时Java 版本要匹配 Spring Boot 版本。2.7.18 支持 Java 8 到 173.x 要求 Java 17 起步。建议本地开发直接用 17但部署环境如果是老 JDK 8就不要用 3.x。调试 MyBatis 的痛点主要是 XML 写错参数没提示。装一个 MyBatisX 插件可以直接从 Mapper 接口方法跳转到 XML还能自动提示参数名和 resultMap。它还有个代码生成功能能根据表结构生成实体、Mapper 和 XML少写很多模板代码。如果遇到“jar 包反编译成项目”的需求我提一个经验反编译只能还原代码逻辑还原不了配置文件里的注释和原始结构特别是 MyBatis 的 XML 可能包含动态 SQL 的取舍逻辑。与其反编译不如把项目从最开始就用 Maven 多模块和资源分离工程化线上运行包保留源码版本映射方便快速定位。最后分享一个我个人的实操体会和 MyBatis 打交道这几年我最大的收获不是背了多少面试题而是养成了“看日志、翻源码、写小例子验证”的习惯。很多东西在网上一搜一堆答案但真正让你成长的是自己动手定位那个诡异问题。比如一级缓存到底什么时候生效、PageHelper 的分页参数为什么会串线程、二级缓存为什么会读到脏数据这些问题只有亲手查过才会真正理解。如果你正在做 Spring Boot MyBatis 项目我建议你在项目里加一根简单的 SQL 耗时拦截器把所有慢 SQL 都暴露出来。别急着上缓存、上分库分表先把慢查询干掉。MyBatis 只是帮你把 SQL 跑起来跑得好不好永远取决于你的 SQL 质量和对数据结构的理解。顺手也给自己留个小任务把MybatisAutoConfiguration的关键方法读一遍把MapperMethod的执行逻辑过一遍。读完之后再看那些“为什么这么配置”的问题就会有豁然开朗的感觉。