其实Spring和MyBatis这套组合几乎是国内Java后端开发的“国民级配置”。凡是做业务系统、后台管理的朋友大概率都跟它打过交道。为什么这样说因为Spring负责把对象之间的依赖关系管起来MyBatis负责把你跟数据库打交道这件事做简单——你不需要像JDBC那样写一堆try-catch和资源释放代码也不需要像Hibernate那样去记复杂的HQL和关联映射SQL怎么写就怎么写灵活、直接、可控。这套组合能解决的问题很明确第一让业务代码里的数据库操作变得整洁SQL语句集中管理或写在Mapper接口的注解里不再散落各处第二让事务、连接池、Mapper代理这些底层逻辑交给框架开发者只关注业务本身第三对于团队里熟悉SQL而未必熟悉ORM的同事非常友好SQL调优就是写SQL的问题不用绕弯。适合谁来学习呢如果你是刚入行的Java开发、准备上手Spring Boot项目的实习生或者是从其他技术栈转过来想快速了解主流Java Web数据访问方案的朋友这篇文章都能提供一个完整的视角。我会尽量把集成步骤、底层原理、实战案例和排查经验揉在一起讲因为只讲用法不讲原理遇到问题还是会抓瞎只讲原理不讲用法看完也上不了手。1. 为什么Spring要配上MyBatis1.1 项目里的真实痛点我先问你一个问题你现在做项目写数据访问层的时候最怕什么我自己的经验是最怕的不是SQL写错而是下面这几个问题。第一连接管理。每次操作数据库都要打开连接、用完再关一旦某个分支忘了关连接池就慢慢耗尽线上偶发的Connection timeout基本都是这么来的。第二参数与结果的转换。JDBC里面给占位符赋值、从ResultSet里取字段都是手工一行一行地setString、getInt。表一多字段一多这些代码又臭又长还特别容易下标写错。第三SQL与代码的割裂。业务逻辑写在Service层SQL散落在DAO类里改一个字段要全项目搜索命名还不统一。而MyBatis恰好把这些痛点都堵上了。它帮你把连接创建、参数绑定、结果映射全部封装掉你只需要定义Mapper接口再写SQL语句剩下的映射和参数处理都让框架来做。Spring再补上事务管理和数据源注入整个数据访问层就非常清爽了。1.2 Spring与MyBatis各自擅长什么很多人把Spring和MyBatis放在一起说但其实它们干的事情完全不同。Spring的核心是IoC容器和AOP它管理的是“对象之间怎么协作”MyBatis的核心是SQL执行引擎它管理的是“Java对象与数据库之间怎么转换”。打个比方Spring是一个公司的行政部门负责人员调度、资源分配和制度执行MyBatis是具体干活的技术小组负责把需求SQL落地成产出数据。没有SpringMyBatis也能单独运行但你在每个业务调用里都得自己去创建SqlSession、控制事务、管理连接没有MyBatisSpring连数据库就只剩JdbcTemplate或者JPA要么你写更多模板代码要么你把SQL的灵活性交出去。所以Spring和MyBatis不是竞争关系而是互补关系。Spring Boot出现之后两者集成更加顺理成章spring-boot-starter-jdbc负责数据源和事务mybatis-spring-boot-starter负责把MyBatis的生命周期托管给Spring。2. 环境准备与依赖引入2.1 Maven坐标怎么配先上结论一个基于Spring Boot 2.7的项目pom.xml里要加这么几样东西dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.1/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency这里我特意没有加spring-boot-starter-jdbc因为mybatis-spring-boot-starter已经传递依赖了spring-boot-starter-jdbcDataSource、JdbcTemplate、事务管理器这些都已经准备好了。版本选择上我多说一句如果你是Spring Boot 2.xMyBatis starter用2.3.x如果是Spring Boot 3.xstarter要用3.0.x及以上同时JDK也得升到17以上。这个版本对应关系是踩坑高发区别问问就是我当时因为版本不匹配折腾了一下午。2.2 配置文件详解依赖加好之后application.yml里最基本的配置长这样spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/test_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.demo.entity configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl每个配置项我都解释一下因为这个看似简单的配置背后藏着很多细节。driver-class-name如果你用的是MySQL 8.x必须写成com.mysql.cj.jdbc.Driver老版本的com.mysql.jdbc.Driver已经废弃了。url里面的serverTimezone参数也必须有不写的话高版本的MySQL驱动会抛出一个时区相关的异常说是SQLException其实就是驱动检测不到默认时区。map-underscore-to-camel-case这个配置是我强烈建议打开的。因为很多表设计是user_name这种下划线命名而Java实体类约定是userName这种驼峰命名打开这个开关自动映射就能完成下划线到驼峰的转换不用你每个字段都写resultMap。但注意它只对自动映射生效如果你用了resultMap就得在resultMap的column和property里显式指定。log-impl配合StdOutImpl可以在控制台直接看到每次执行的SQL语句、参数和返回结果对于开发调试来说非常有用。生产环境建议关掉或者在日志框架里按级别过滤避免敏感SQL全部打到日志文件里。2.3 日志与SQL打印说到日志很多人有个误区以为配置了log-impl就能打印SQL了。其实MyBatis打印SQL需要日志框架在DEBUG级别输出对应的logger。如果你只用StdOutImpl它是直接System.out输出日志级别不受log4j2控制。我更推荐用slf4j的方式在logback.xml里加上logger namecom.example.demo.mapper leveldebug/这样就能按包名精确控制哪些Mapper的SQL需要打印线上出了问题再开某个包不用把整个应用的SQL都暴露出来。这个经验是我在生产环境排查慢SQL时总结出来的好几次线上问题都靠这个定位。3. 核心配置与初始化原理3.1 SqlSessionFactoryBean与MyBatis的初始化流程配置搞定了接下来聊聊它是怎么跑起来的。很多人知道Spring集成MyBatis是个可用的黑盒但对于里面到底发生了什么不清楚。其实整个过程就三步。第一步Spring容器启动时mybatis-spring-boot-starter里的MybatisAutoConfiguration会自动生效。它读取你yml里mybatis.*开头的配置生成一个SqlSessionFactoryBean。第二步SqlSessionFactoryBean实现了Spring的FactoryBean接口和InitializingBean接口。在afterPropertiesSet方法里它会调用MyBatis本身的XMLConfigBuilder和XMLMapperBuilder把配置文件解析成Configuration对象把每个Mapper XML文件解析成MappedStatement集合。第三步Configuration对象构建出SqlSessionFactory这个工厂再产生SqlSession也就是MyBatis对一次数据库会话的封装。Spring为你做了一层包装SqlSessionTemplate它实现了SqlSession接口并且把每一次方法调用都委托给线程绑定的SqlSession。所以你会发现你在业务代码里从没直接new过SqlSessionFactory都是注入Mapper接口然后框架在背后完成了一切。这里有一个很关键的细节Spring容器里真正放的是SqlSessionTemplate你注入的SqlSessionFactory其实是它内部的成员。3.2 Mapper扫描机制还有一个你需要知道的关键点Mapper接口为什么注入进来就能用Spring Boot集成MyBatis时默认会扫描启动类所在包以及子包下的所有Mapper接口。你只需要在启动类上加MapperScan(com.example.demo.mapper)或者给每个Mapper接口加Mapper注解。两者区别在于MapperScan是批量扫描建议在启动类上加一次Mapper是单个标记适合接口不多的时候而且每个都要加比较啰嗦。扫描到Mapper接口之后MyBatis会为每个接口生成一个动态代理对象。这个代理对象在调用方法时会根据方法名找到MappedStatement把参数通过TypeHandler转成数据库需要的类型交给Executor执行最后再把ResultSet映射回Java对象。这就是为什么你定义接口、写SQL就能直接用因为代理帮你做了所有事情。3.3 XML配置的工作流程与XMLConfigBuilder很多面试题里会问你MyBatis的初始化工作流程我这里把基于XML的场景完整串一遍。MyBatis在Spring环境下启动时首先通过XMLConfigBuilder解析mybatis-config.xml如果没有Spring Boot会自动生成一个带所有必要配置的Configuration对象。解析顺序是properties、settings、typeAliases、typeHandlers、objectFactory、objectWrapperFactory、plugins、environments、databaseIdProvider、mappers。其中mappers节点或者Spring Boot环境下的Mapper XML location配置会触发XMLMapperBuilder解析每个Mapper XML。XMLMapperBuilder把、 、 、 标签解析成一条条MappedStatement每个MappedStatement里面包含SQL语句、参数映射、结果映射、缓存配置等信息存放到Configuration对象的mappedStatements这个Map里。等你执行Mapper方法的时候Executor会根据MappedStatement的id通常就是Mapper接口的全限定类名加方法名找到对应的SQL调用JDBC执行。这个过程听起来不复杂但你真的理解了这套流程后面排查各种“为什么我改了XML不生效”“为什么Mapper扫描不到”的问题就会非常从容因为你已经知道去哪看发生了什么。4. 实战从Mapper接口到CRUD4.1 一个完整的注册功能纸上谈兵没意思直接来一个用户注册功能的实操这次代码尽量完整因为我知道很多人要的就是这种能直接抄的。表结构很简单CREATE TABLE sys_user ( id BIGINT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL, password VARCHAR(100) NOT NULL, nickname VARCHAR(50), created_time DATETIME DEFAULT CURRENT_TIMESTAMP );实体类public class SysUser { private Long id; private String username; private String password; private String nickname; private LocalDateTime createdTime; // getters/setters 省略 }Mapper接口public interface SysUserMapper { int insert(SysUser user); }Mapper XMLinsert idinsert parameterTypecom.example.demo.entity.SysUser INSERT INTO sys_user (username, password, nickname) VALUES (#{username}, #{password}, #{nickname}) /insertService层Service public class UserServiceImpl implements UserService { Autowired private SysUserMapper sysUserMapper; Transactional public Long register(SysUser user) { sysUserMapper.insert(user); return user.getId(); } }这里有个细节我要特别提醒主键回填。MySQL的AUTO_INCREMENT字段如果不在INSERT语句里写数据库会自动生成但Java对象里的id依然是null。解决办法有两种第一种在insert标签里加useGeneratedKeys和keyPropertyinsert idinsert useGeneratedKeystrue keyPropertyid这样MyBatis执行完JDBC的Statement.getGeneratedKeys()把数据库自增的id填回user对象的id字段。第二种是手动在insert之前生成一个分布式ID比如雪花算法然后显式插入id字段。业务系统里这种情况更常见一点。4.2 参数传递的坑参数传递是我见过翻车最多的地方。新手最容易遇到的是接口方法有两个参数比如ListSysUser selectByUsernameAndStatus(String username, Integer status);SQL里如果直接写#{username}大概率会报错告诉你找不到参数。原因很直接Java编译后参数名默认是arg0、arg1不会保留源码里的名字。MyBatis在解析单个参数时可以直接用任意名字取值但一旦有两个或以上参数就必须通过Param注解显式指定名字ListSysUser selectByUsernameAndStatus(Param(username) String username, Param(status) Integer status);SQL里写#{username}、#{status}完美对应。还有一种新手特别容易绕晕的情况SQL里用了#{}传进去一个List。你可能会想当然地写出WHERE id IN (#{list})结果SQL执行报错或者查出来结果不对。IN查询的正确姿势是使用foreach标签select idselectByIds resultTypecom.example.demo.entity.SysUser SELECT * FROM sys_user WHERE id IN foreach collectionlist itemid open( separator, close) #{id} /foreach /select#{}是预编译占位符它只会把一个值安全地放到占位符里就像JDBC的PreparedStatement而${}是字符串拼接直接把值拼进SQL里存在SQL注入风险除非你是动态表名列名否则不要用${}。这个区别我在文章里反复强调因为我真的见过同事把用户输入的排序字段直接${}拼接被扫描工具扫出高危漏洞的案例。4.3 结果映射与TypeHandler结果映射相对简单但有两个话题值得展开一个是resultType和resultMap的选择一个是TypeHandler机制。如果你只是查询结果映射到实体类字段名能对得上驼峰开关开了那直接用resultType就够了。但如果你要做关联查询比如查用户信息的时候顺带查出该用户的一篇博客然后要把博客作为一个嵌套对象放进去那就必须用resultMap的association。如果你要查一对多比如一个用户有多篇文章就用collection。TypeHandler则是MyBatis很不起眼但非常强大的扩展点。它解决的问题是Java类型和JDBC类型之间的双向转换。默认情况下基础类型、String、Date、LocalDate这些框架都内置了TypeHandler但遇到一些特殊类型比如一个JSON字段想映射成ListMapString,Object一个枚举想映射成数据库的字符串默认就不够了。解决办法是自定义TypeHandler核心是继承BaseTypeHandler实现setNonNullParameter和getNullableResult。举一个最简单的例子把Java层的一个枚举直接映射成数据库的Int值。MappedTypes(StatusEnum.class) public class StatusEnumTypeHandler extends BaseTypeHandlerStatusEnum { Override public void setNonNullParameter(PreparedStatement ps, int i, StatusEnum parameter, JdbcType jdbcType) throws SQLException { ps.setInt(i, parameter.getCode()); } Override public StatusEnum getNullableResult(ResultSet rs, String columnName) throws SQLException { return StatusEnum.of(rs.getInt(columnName)); } Override public StatusEnum getNullableResult(ResultSet rs, int columnIndex) throws SQLException { return StatusEnum.of(rs.getInt(columnIndex)); } Override public StatusEnum getNullableResult(CallableStatement cs, int columnIndex) throws SQLException { return StatusEnum.of(cs.getInt(columnIndex)); } }配置在yml里加一行mybatis: type-handlers-package: com.example.demo.handler或者给字段单独指定在XML的resultMap里加typeHandler属性。两种方式各有适用场景包扫描适合全局通用类型单独指定适合某个特殊字段。实际项目里TypeHandler用的最多的是枚举转换、JSON字符串与对象互转、密文字段加解密。这三个场景都值得生产级应用。5. 缓存机制详解5.1 一级缓存MyBatis的缓存分为两级很多人面试被问到但实操中往往没有感知。一级缓存是SqlSession级别的默认开启你没法完全关掉它只能通过配置把localCacheScope从SESSION改成STATEMENT把缓存作用范围改成每次语句执行完就清空。概念是这样同一个SqlSession对象执行完全相同的SQL包括相同的参数第二次执行时直接命中一级缓存不查数据库。Spring中由于SqlSessionTemplate默认绑定在当前线程的事务范围内所以一次事务里多次查询同一个Mapper的同一个方法、同样的参数第二次会直接走缓存。这一点在开发中其实是把双刃剑。好的方面是在一个事务里你查一次用户信息后续接口多次用到不用重复查库。坏的方面是如果有人在同一个事务里把用户信息更新了但更新操作没用MyBatis的Mapper去执行或者干脆直接改数据库一级缓存里还是旧数据就会出现“在一个事务里先查后改再查第二次查出来还是旧值”的现象。解决办法很简单用同一个Mapper的update操作MyBatis会在更新时自动清除一级缓存。5.2 二级缓存二级缓存是Mapper级别的也就是跨SqlSession共享。它默认是关闭的需要开启cache evictionLRU flushInterval60000 size1024 readOnlyfalse/开启之后同一个Mapper下的查询结果会保存在二级缓存中并且可以配置为跨Session共享。但我要泼一盆冷水业务系统里二级缓存真的用得很少原因在于缓存一致性太难控制。你只要有一条UPDATE、INSERT、DELETE语句执行MyBatis会立即清空该Mapper的二级缓存但如果你的数据被别的系统、别的Mapper、或者直接通过SQL工具修改了缓存就成了脏数据。所以我的建议是二级缓存适合那种数据基本不变、查询频率极高、接受一定时间不一致的场景比如字典表、省份城市列表、静态配置等。核心业务表尤其是用户相关的数据不要开二级缓存用Redis做业务缓存才是常规选择。6. 常见问题与排查6.1 条件不生效等常见坑先列一个常见问题速查表都是我实际遇到的。现象原因解决办法Mapper方法报Invalid bound statement (not found)Mapper接口扫描到了但XML没被解析检查mapper-locations路径是否和XML实际位置一致配置文件里的SQL不生效改了半天没反应项目热部署没有重新编译资源文件mvn clean或者确保mapper XML在classpath下查询返回null字段全是null驼峰映射没开启或者字段名对不上打开map-underscore-to-camel-case或写resultMap多参数查询报参数找不到没加Param加注解SQL里有大于号小于号报错XML标签被当作标签解析用 和 或返回List但MyBatis报TooManyResultsException期望单条结果但SQL返回多条检查SQL或改用List接收这些坑每一个我都踩过。最典型的就是Invalid bound statement我当时花了很多时间检查接口名和XML的namespace最后发现是mapper-locations路径写错了。配置路径一定要和实际放置Mapper XML的目录完全一致比如你把XML放在src/main/resources/mapper/下配置就是classpath:mapper/*.xml。6.2 排查技巧排查MyBatis问题我有一套自己比较固定的打法。第一步开日志。开发环境把log-impl设为StdOutImpl或者按包名把Mapper包日志级别调到debug。你看到SQL语句执行情况很多问题当场就能定位。第二步检查启动日志。Spring Boot启动时MyBatis会打出TypeHandler注册信息、Mapper扫描到了哪些接口。如果你的Mapper没有被扫描到启动日志里会有体现。第三步如果是SQL执行异常不用急着看Java堆栈先把堆栈里的Caused by拉到最后通常是SQLException的具体原因。比如“Unknown column xxx in field list”就是列名写错了。第四步如果怀疑一级缓存导致数据不一致可以在事务里画出一条完整的查询链路逐个排查最后一次查询结果来源。更快的办法把localCacheScope改成STATEMENT用日志确认是否还重复查询数据库如果还是查的旧值那基本是事务隔离级别或者缓存没刷新的问题不是MyBatis的锅。最后分享一点我在实际项目里的体会。Spring集成MyBatis这件事入门确实简单几个注解加一个XML就能跑起来但真正想用好理解框架背后那套初始化流程、Mapper代理机制和缓存模型才是关键。很多生产环境里诡异的线上问题最后定位下来都不是MyBatis本身的bug而是使用姿势出了问题——要么参数没加Param要么路径没对准要么就是动了不该动的缓存。如果你现在刚接触这套组合建议按我上面第4节的注册功能完整跑一遍然后手动制造几个故障比如故意把路径写错、故意不加Param看看报错长什么样。这种“主动制造故障”的方式比背面试题有效得多。等你对报错信息有了肌肉记忆再去看那些面试题你会发现答案其实都在报错里了。