说实话，做Java后端这么多年，面试过不少人，MyBatis几乎是绕不开的话题。我并不是想让大家去背面试题，而是这框架确实和日常开发绑得太紧了：你写SQL、配映射、调缓存、搭批量，本质都是在和MyBatis打交道。很多同学用了两三年的MyBatis，连SqlSessionFactory是怎么从一份XML配置里“长”出来的都说不清楚，缓存被问两句就露馅，TypeHandler就更不用说了——工作里没遇到过就永远处于“知道名字、不知道干嘛”的状态。
这篇教程我按自己带新人时的讲法来写，核心围绕MyBatis的初始化流程、Mapper机制、动态SQL、缓存机制、TypeHandler、Spring Boot整合和排坑经验，既照顾刚入门的朋友，也把源码级的工作流程、面试容易踩的坑一并讲透。内容比较长，但照着读下来，你对MyBatis的理解会比很多工作两年的人更扎实。
1. 为什么Java后端绕不开MyBatis
1.1 从JDBC的痛点说起
如果你去翻老项目的代码，还能看到一批用原生JDBC写的数据访问层：DriverManager.getConnection()、PreparedStatement、ResultSet、手动关闭资源，再配合一堆if (rs.next())和rs.getString("xxx")。代码写起来啰嗦是一回事，更麻烦的是SQL和Java代码强耦合——SQL拼在Java字符串里，换一个数据库要小心翼翼地查兼容性，同时连接管理、事务边界、异常处理这些事还得自己操心。
MyBatis解决的核心问题，就是把这层样板代码砍掉：SQL语句写在XML或者注解里，Java只保留业务方法；连接管理、参数传入、结果集映射、事务回调全部交给框架处理。你只要关心SQL本身怎么写，剩下的脏活累活框架帮你干完了。这也是它和Hibernate这类全自动ORM最大的差异——MyBatis是半自动的，SQL由开发者掌控，框架只负责“在正确的时间把外面的值填进去、把数据库返回的结果转成对象”。
1.2 为什么选MyBatis而不是JPA/Hibernate
每个团队选型都有自己的理由，我这些年用下来，我的判断是这样的：
| 对比维度 | MyBatis | Hibernate/JPA |
|---|---|---|
| SQL控制力 | 完全手动，SQL明确可见 | 自动生成，复杂查询需要HQL/JPQL |
| 学习曲线 | 相对平缓，会SQL就上手快 | 概念多，关联映射、缓存策略需要长时间消化 |
| 性能调优 | 直接改SQL即可，优化直观 | 需要理解缓存机制和懒加载策略 |
| 复杂查询 | 适合多表join、报表类SQL | 复杂查询容易生成糟糕SQL |
| 数据库依赖 | 如果SQL写得原生，换库成本高 | 自动方言适配较好 |
这里面没有绝对优劣，但国内大量业务场景是“报表多、查询逻辑复杂、SQL需要精细控制”的，MyBatis这条路更适合大部分互联网团队。你把SQL握在手里，就等于把性能命脉握在自己手里。而且Spring Boot对MyBatis的整合非常省事，mybatis-spring-boot-starter一加，配置一写，马上就能跑。
1.3 SqlSessionFactory是那个“发动机”
MyBatis一切操作都建立在SqlSessionFactory之上。你可以把它理解成一个工厂：负责创建SqlSession，而SqlSession是你操作数据库的“会话入口”。这个工厂在应用启动时创建一次，整个生命周期里反复使用，所以它的构建策略是：SqlSessionFactoryBuilder读取配置文件（或者配置类），解析成一个Configuration对象，再由Configuration生产出工厂实例。
我经常用一句话帮新人建立整体认知：
MyBatis = Configuration（全局配置与映射注册中心）+ SqlSession（一次会话门面）+ Executor（真正执行JDBC操作的人）+ MappedStatement（一条SQL及其映射规则的封装）。
后面讲到初始化流程时，你会发现所有细节都围绕这条主线展开。
2. 初始化到底发生了什么
2.1 mybatis-config.xml的标准骨架
先看一份最常用的配置文件：
<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN" "http://mybatis.org/dtd/mybatis-3-config.dtd"> <configuration> <properties resource="db.properties"/> <settings> <setting name="mapUnderscoreToCamelCase" value="true"/> <setting name="logImpl" value="SLF4J"/> </settings> <typeAliases> <package name="com.example.domain"/> </typeAliases> <environments default="dev"> <environment id="dev"> <transactionManager type="JDBC"/> <dataSource type="POOLED"> <property name="driver" value="${db.driver}"/> <property name="url" value="${db.url}"/> <property name="username" value="${db.username}"/> <property name="password" value="${db.password}"/> </dataSource> </environment> </environments> <mappers> <package name="com.example.mapper"/> </mappers> </configuration>初学者最容易忽略settings的作用。mapUnderscoreToCamelCase这个配置真的很实用：数据库字段是user_name，Java属性是userName，不开这个配置，resultMap里就得一个一个手写映射；开了之后，MyBatis自动帮你把下划线转驼峰，少写一半映射代码。
2.2 XMLConfigBuilder的工作流程
从SqlSessionFactoryBuilder.build(InputStream)进去，MyBatis会创建一个XMLConfigBuilder，它要做的事情就是从XML的<configuration>根节点开始，把每个子节点解析进去。整个流程按顺序大致可以拆成这几步：
properties：先解析外部属性文件，并解析<property>子标签，构成一个初始的属性集合，后面很多地方（比如${db.url}占位符替换）都会用到。settings：把用户配置逐条写入Configuration对象的字段，每个setting名称对应一个setter方法。typeAliases：注册类型别名，比如com.example.domain.User可以简写为user。typeHandlers：注册或定制类型处理器。objectFactory和objectWrapperFactory：指定创建结果对象和包装对象的工厂，绝大多数项目不需要改。plugins：注册拦截器，也就是俗称的插件机制，比如分页插件就是挂在这里。environments：配置事务管理器类型和数据源，组合成Environment对象。databaseIdProvider：用来支持多数据库方言，这个下面我会再细讲。mappers：最后注册Mapper映射文件或Mapper接口，每找到一个Mapper，都会触发绑定。
XMLConfigBuilder.parse()跑完后，得到的Configuration对象已经包含了数据源信息、全局设置、所有MapperStatement。随后拿这个Configuration去创建DefaultSqlSessionFactory，整个初始化就完成了。
2.3 Mapper是如何被“注册”的
重点关注mappers这一步。如果用的是<package name="com.example.mapper"/>，MyBatis会扫描包下所有接口，逐个调用MapperRegistry.addMapper()。这个过程中有两件事：
- 解析对应的XML映射文件（
UserMapper.xml），生成MappedStatement，里面保存了SQL语句、参数映射、结果映射等一切执行所需信息； - 在
MapperRegistry的knownMappers里注册Mapper接口对应的MapperProxyFactory。
面试时经常问“Mapper接口没有实现类，为什么可以直接注入调用”，答案就在这里：MyBatis在运行时通过MapperProxyFactory为接口生成动态代理，你调用userMapper.selectById(1)时，本质上是在调用MapperProxy.invoke()，它会根据方法名和参数找到对应的MappedStatement，再交给SqlSession去执行。
这也解释了为什么要强调namespace必须等于Mapper接口的全限定名，映射文件里语句的id必须等于接口方法名——因为框架就是靠这种一一对应的关系来定位SQL的。
3. Mapper核心用法与动态SQL实战
3.1 XML映射文件的关键点
一个典型的Mapper XML长这样：
<mapper namespace="com.example.mapper.UserMapper"> <resultMap id="BaseResultMap" type="com.example.domain.User"> <id property="id" column="id"/> <result property="userName" column="user_name"/> <result property="email" column="email"/> </resultMap> <select id="selectById" resultMap="BaseResultMap"> select id, user_name, email from user where id = #{id} </select> <insert id="insert" useGeneratedKeys="true" keyProperty="id"> insert into user(user_name, email) values(#{userName}, #{email}) </insert> </mapper>useGeneratedKeys="true"配合keyProperty="id"是从插入后回填自增主键的标准写法。很多人以为插入后需要再查一次数据库才能拿到自增ID，其实不用——JDBC的getGeneratedKeys()就能拿到，MyBatis会直接填到传入对象的id字段上。
3.2 #{}和${}一定要分清楚
这是面试必问，也是实际工作中最容易搞出问题的知识点：
#{name}：走PreparedStatement参数占位（?），MyBatis会用TypeHandler设置参数值。安全、能防止SQL注入，大部分场景都用它。${name}：直接把字符串拼接进SQL语句。灵活但危险，用户可控值传进来可能改SQL语义，更严重的可能被注入。
什么时候用${}？比如动态排序字段order by ${orderByColumn}，因为排序字段不能被参数占位符替代；比如表名是动态的select * from ${tableName}。把这些位置开放给用户前必须做好白名单校验，我在项目里一般用枚举或者常量集合严格限制。
一个反面案例我印象很深：某模块把用户输入的字段名通过${}直接拼进group by，前端随便传入id,1=1，SQL就变成了group by id,1=1，虽然没造成数据泄露，但直接改变了查询语义。千万别贪方便。
3.3 参数映射的几种姿势
单参数基本不用管：基础类型可以直接用#{id}，一个对象参数可以直接写#{userName}。
多参数就有讲究了。这里有个我很希望新人都先知道的规则：不写@Param时，MyBatis给参数取的名字是param1、param2……比如：
User selectByNameAndEmail(String name, String email);XML里可以写#{param1}、#{param2}，但代码可读性极差。正确做法是加@Param("name")、@Param("email")，然后XML里写#{name}、#{email}。加了注解后，MyBatis会以注解值为准，不再依赖paramN这套默认命名。
我在实际项目里还踩过一个坑：如果@Param注解和paramN混着理解，很容易出现“明明只有一个参数但XML里写#{param1}找不到值”的问题。最好约定整个团队统一用@Param，不要依赖默认命名。
3.4 动态SQL的常见组合
动态SQL是MyBatis最大的生产力之一。我按使用频率排个序：
<if>：判断参数是否满足条件，最常用的分支。<where>：自动处理AND/OR前缀，省去“where前面要不要加and”的烦恼。<choose>/<when>/<otherwise>：类似Java的switch，适合分支互斥场景。<set>：配合更新语句，动态去除末尾逗号。<foreach>：处理集合遍历，批量插入或in条件。<trim>：更通用的前缀/后缀处理，where和set本质上是它的简化封装。
一个常见组合是条件查询：
<select id="search" resultMap="BaseResultMap"> select id, user_name, email from user <where> <if test="userName != null and userName != ''"> and user_name like concat('%', #{userName}, '%') </if> <if test="email != null"> and email = #{email} </if> </where> order by id desc </select>注意test表达式用的是OGNL语法：字符串比较要写成userName != ''，数值类型只要判断非null即可；多个条件用and连接。项目里经常有人把SQL写好后，发现某个条件一直不生效，八成是test里的属性名和实体类字段名不一致，或者判断逻辑写反了。
编辑过程中我多强调一句：动态SQL虽好，但别滥用。我见过一段两百多行的动态SQL，光<if>就有十几个，调试时根本找不到问题。可维护性最高的做法是：核心SQL固定下来，个别可选条件用动态SQL控制，实在复杂的查询拆成多个方法。
4. 缓存机制：一级缓存和二级缓存
4.1 一级缓存的生效范围与失效场景
MyBatis默认开启一级缓存，作用域是SqlSession。同一个SqlSession里执行相同的查询两次，第二次会直接命中缓存，不再查数据库。一级缓存底层的实现是PerpetualCache，使用CacheKey作为缓存的key，CacheKey由statementId、SQL语句、参数值、分页条件和环境信息共同组成。
这就引出了一个经典问题：一级缓存什么时候失效？
- 查询参数不同，缓存key不同，肯定不命中；
- 同一个
SqlSession里执行了新增、修改、删除，MyBatis会清空缓存，避免脏数据； SqlSession被关闭，缓存自然消失；- 手动调用
sqlSession.clearCache()。
很多人在Spring环境里对“一级缓存是否生效”没有概念，因为SqlSessionTemplate每次执行都会关闭SqlSession，一级缓存基本用不上。这属于框架整合带来的副作用，不必纠结，明白原理即可。
4.2 二级缓存：namespace级别的缓存
二级缓存默认关闭，需要通过<cache>标签开启。开启后，缓存作用域从单个SqlSession扩展到整个namespace，不同SqlSession之间可以共享。它的底层是装饰器模式：在PerpetualCache外包上SynchronizedCache（线程安全）、LoggingCache（缓存命中记录）、SerializedCache（序列化存储）等装饰器，形成一条装饰链。
听着美好，但二级缓存在实际项目里争议很大。最大的问题是跨namespace的数据一致性问题：如果UserMapper用了二级缓存，但订单表关联查询了用户信息，更新用户时并不会清掉订单查询产生的缓存，就可能读到旧数据。尤其是多表关联、频繁写操作的业务，二级缓存很容易变成“玄学缓存”。
我的个人建议是：
默认关闭二级缓存。如果确实要开，只适合“基本不变的热数据表”的简单查询，且相关表的写操作非常少；同时所有访问这个表的Mapper都要谨慎处理。多数互联网业务场景，把缓存放在Redis这一层更可控。
4.3 缓存相关配置项
习惯上可以在mybatis-config.xml里设置：
<settings> <setting name="cacheEnabled" value="true"/> <!-- 默认就是true，二级缓存总开关 --> <setting name="localCacheScope" value="SESSION"/> <!-- 一级缓存范围，STATEMENT表示每次查询都清缓存 --> </settings>想验证缓存是否命中，可以打开日志，看Cache Hit Ratio这个指标。如果一直是Cache Hit Ratio: 0.0，说明缓存基本没发挥作用，别再调配置了，先查查作用域和SQL参数是否一致。
5. TypeHandler与自定义扩展
5.1 TypeHandler到底在干什么
很多人在MyBatis里配过jdbcType，但TypeHandler真正做的事情，是把Java类型和JDBC类型互相转换：
- 写参数时：
PreparedStatement.setXxx()那一步由TypeHandler完成； - 读结果时：
ResultSet.getXxx()那一步由TypeHandler完成。
MyBatis内置了一大堆TypeHandler，比如StringTypeHandler、IntegerTypeHandler、LocalDateTimeTypeHandler。平时感觉不到它的存在，是因为默认类型基本都覆盖了。但一旦Java类型和数据库类型对不上，就需要自定义。
5.2 自定义枚举TypeHandler实操
实际项目最常见的场景是枚举类。数据库存0、1，Java里用枚举：
public enum Status { DISABLED(0), ENABLED(1); private final int code; Status(int code) { this.code = code; } public int getCode() { return code; } public static Status fromCode(int code) { for (Status status : values()) { if (status.code == code) { return status; } } throw new IllegalArgumentException("unknown code: " + code); } }自定义TypeHandler：
@MappedTypes(Status.class) @MappedJdbcTypes(JdbcType.INTEGER) public class StatusTypeHandler extends BaseTypeHandler<Status> { @Override public void setNonNullParameter(PreparedStatement ps, int i, Status parameter, JdbcType jdbcType) throws SQLException { ps.setInt(i, parameter.getCode()); } @Override public Status getNullableResult(ResultSet rs, String columnName) throws SQLException { return Status.fromCode(rs.getInt(columnName)); } @Override public Status getNullableResult(ResultSet rs, int columnIndex) throws SQLException { return Status.fromCode(rs.getInt(columnIndex)); } @Override public Status getNullableResult(CallableStatement cs, int columnIndex) throws SQLException { return Status.fromCode(cs.getInt(columnIndex)); } }注册方式有两种：在mybatis-config.xml的typeHandlers节点里注册，或者加在字段上：
@TableField(typeHandler = StatusTypeHandler.class) private Status status;我之前在项目里遇到的真实收益是：所有枚举都通过这种方式映射，业务代码里再也看不到if (status == 0)这种魔法数字。扩展性也很好，新增枚举值只要改枚举类本身，不必大范围改动业务逻辑。
5.3 自定义Configuration的作用
热词里提到“自定义Configuration”，这倒是一个进阶话题。XMLConfigBuilder解析出来的Configuration对象只是默认实现，如果你需要在配置阶段注入一些自定义行为，可以继承Configuration并重写部分方法，再通过SqlSessionFactoryBuilder传入：
Configuration configuration = new MyConfiguration(); configuration.setEnvironment(environment); SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(configuration);一些分页插件、逻辑删除插件就是这么干的。不过日常开发里直接用插件机制（Interceptor）更多，自定义Configuration属于相对底层的玩法，面试时能讲清楚它的定位就可以。
5.4 数据库方言适配：比如Gauss能否直接用
热词里有人问“MyBatis支持Gauss吗”。这类国产数据库大多基于PostgreSQL或MySQL协议开发，所以MyBatis本身不支持“某数据库”这个概念——它操作的是JDBC驱动。只要对方提供了符合JDBC规范的驱动，MyBatis就能连上。真正要处理的是SQL语法差异和特殊类型，这时候有两个办法：
- 用
databaseIdProvider给不同数据库配置不同的SQL片段； - 针对特殊数据类型自定义TypeHandler，比如某些库有jsonb类型、数组类型、地理位置类型，内置处理器覆盖不了就一定需要定制。
所以结论是：Gauss能不能用，取决于三点：JDBC驱动是否齐全、SQL语法是否符合你写的标准、特殊类型是否有对应的TypeHandler。这和MyBatis框架本身没太大关系。
6. Spring Boot整合与高频问题排查
6.1 mybatis-spring-boot-starter帮你做了什么
Spring Boot项目接入MyBatis非常无脑，pom.xml加依赖，application.yml里配置数据源和Mapper扫描路径：
spring: datasource: url: jdbc:mysql://localhost:3306/test username: root password: 123456 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.domain configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl启动类上别忘了加@MapperScan("com.example.mapper")，或者在UserMapper接口上单独加@Mapper。两者效果差不多，但全项目统一用@MapperScan更清晰。
mybatis-spring-boot-starter的自动配置核心是MybatisAutoConfiguration，它会在Spring容器里注册SqlSessionFactory和SqlSessionTemplate。也正因为如此，Spring环境下的SqlSession是线程安全的，由Spring管理生命周期，这跟原生MyBatis自己手动 open/close 的模型不一样，刚转过来的人容易懵。
6.2 批量插入怎么写出性能
热词里“mybatis mybatis-plus 批量”被频繁搜，说明大家都在为批量操作效率头疼。最简单的方式是foreach拼一条大SQL：
<insert id="batchInsert"> insert into user(user_name, email) values <foreach collection="list" item="item" separator=","> (#{item.userName}, #{item.email}) </foreach> </insert>效率高，但注意：foreach生成的SQL语句长度随着数据量线性增长，MySQL的max_allowed_packet默认值有限制。一般建议控制在500条以内一次，拆成多批执行，不然会报“Packet too large”。
想再稳一点，可以用ExecutorType.BATCH来跑：
SqlSession session = sqlSessionFactory.openSession(ExecutorType.BATCH); UserMapper mapper = session.getMapper(UserMapper.class); for (User user : userList) { mapper.insert(user); } session.commit();这种模式不是按条提交，而是积攒到一定量后再统一发送，适合数据量特别大的场景。foreach和ExecutorType.BATCH我都用过，前者代码直观适合大多数项目，后者性能上限更高但要多点样板代码，而且增删改操作在这个模式下多条SQL结果返回的是总影响行数，如果业务上依赖insert.getRows()返回具体值，需要额外小心。
6.3 打印SQL到底怎么配
排查问题时看不到SQL，等于闭着眼睛开车。最省事的配置：
mybatis: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl推荐用StdOutImpl，直接输出到控制台，包含参数占位符和实际参数值，调试最直接。项目规模大了可以换Slf4jImpl配debug日志输出到文件，生产环境不建议长期开着SQL打印。
StdOutImpl的输出里会显示类似这样的信息：
==> Preparing: select id, user_name, email from user where id = ? ==> Parameters: 1(Integer) <== Columns: id, user_name, email <== Row: 1, admin, admin@example.com <== Total: 1注意==> Preparing和==> Parameters两行，平时排查“SQL没查到数据”或者“参数绑定报错”全靠它们。
6.4 常见问题速查表与避坑技巧
我在团队里带过不少新人，下面这些问题频率极高，给一张速查表：
| 症状 | 可能原因 | 解决办法 |
|---|---|---|
Invalid bound statement (not found) | Mapper接口方法在XML里没定义，或namespace写错 | 检查namespace与接口全限定名一致，XML中的id与接口方法名一致 |
| 查询条件不生效 | if的test表达式属性名写错 | 对照实体类字段名逐字符检查，利用断点或日志确认参数值 |
BindingException: Parameter 'xxx' not found | 多参数没加@Param | 给每个参数加@Param("名称")，XML用注解名称取值 |
| 插入后拿不到自增ID | useGeneratedKeys没开或keyProperty名不对 | 添加useGeneratedKeys="true"，keyProperty对应Java主键字段 |
| 中文乱码 | JDBC URL缺少useUnicode=true&characterEncoding=utf8 | 在连接URL中明确指定编码 |
| 实体类属性有值但SQL为null | 没开启驼峰映射 | 设置map-underscore-to-camel-case: true，或resultMap中显式映射 |
resultType还是resultMap选错 | 简单查询用resultType；复杂映射用resultMap | 按需选择，二者不能同时使用 |
| 日志打印不出SQL | 没有配log-impl或日志级别不对 | 先切StdOutImpl确认能输出，再调整日志框架 |
这些坑基本都是“配置小错误、排查老半天”，但只要记住一条铁律：看到报错先打印SQL，看Preparing和Parameters，80%的问题一眼就能定位。别一开始就怀疑框架有bug，MyBatis这种级别的框架，绝大多数问题都是使用姿势问题。
6.5 再多说一个动态更新语句的细节
用<set>动态更新时，有一种情况很坑：如果所有条件都是null，<set>标签会自动去掉整个set子句，生成的SQL就是update user where id = ?，这属于语法错误。所以业务上要兜底：要么前端保证至少传一个字段，要么代码里强制加一个更新字段（比如update_time = now()），不要留这个裸奔死角。
<update id="updateById"> update user <set> <if test="userName != null">user_name = #{userName},</if> <if test="email != null">email = #{email},</if> update_time = now() </set> where id = #{id} </update>这样即使业务字段全是null，update_time也会更新，SQL也不会语法错。
6.6 再聊点扩展方向
MyBatis这套机制学透之后，看MyBatis-Plus、PageHelper这类生态工具会轻松很多。它们本质就是在这个框架上的封装和增强：MyBatis-Plus做了通用CRUD和条件构造器，PageHelper利用了插件拦截器改SQL翻页。你理解了MappedStatement、Executor、Interceptor这些概念之后，看这些工具的源码就不至于一头雾水。面试时能说出PageHelper的分页插件是在Executor层拦截SQL、改写limit，这比背一堆工具API有说服力得多。
如果你是从零开始，我建议不要急着上MyBatis-Plus，先用原生MyBatis把XML映射、动态SQL、缓存这些基本功打扎实——工具可以换，但底层原理一通则百通。等哪天你能不看源码就说出一个查询从Mapper接口调用到返回对象的完整链路，那MyBatis这块基本就过关了。根据我个人带项目的经验，再复杂的框架问题，最终都会落到“SQL写得好不好、映射配得对不对、缓存用得稳不稳”这三件事上，把这三点吃透，MyBatis对你来说就不再是黑盒了。
