MyBatis基础教程：Java持久层框架入门
记得我刚入职那会儿，团队正在开发一个中小型的ERP系统，后端是基于Spring Boot搭建的。我们当时的数据库访问层还是用JDBC手动拼SQL写的，代码冗长不说，维护起来也特别费劲。那时候每天最怕的就是遇到数据库字段变更，一改就是一堆DAO层都要动，简直心累。
后来公司开始引入MyBatis作为ORM工具，说实话刚开始接触的时候确实有点摸不着头脑。XML怎么写？映射关系怎么配？动态SQL咋玩？各种疑问扑面而来。但真正上手之后才发现，它比单纯的JDBC灵活太多，又不像Hibernate那样“太重”，简直是中间派的首选。
今天我就结合自己几年来的实战经验，带大家从零了解MyBatis的基础使用和一些常见问题的应对方式。这篇文不是纯理论堆砌，而是基于我在多个项目中踩过的坑、优化过的点，真心希望能让刚入行或者准备用MyBatis的朋友少走些弯路。
初识MyBatis：为什么会选择它？
在ERP项目的中期，我们面临了一个棘手的问题：随着功能模块越来越多，DAO层代码量也飞速增长，每个实体几乎都有一整套CRUD方法，重复劳动严重。更糟糕的是，不同业务逻辑之间还经常混用相同的SQL语句，导致SQL语句散落在各个类中，维护起来极其困难。
这时候有位老同事提出：“不如我们试试MyBatis？” 一开始我还纳闷，为什么不用Hibernate？他笑了笑说：“Hibernate太‘重’了，而且封装得太深，有时候你想查个字段还要绕半天；而MyBatis则是半自动化的ORM，既能保持灵活性，又能通过映射文件统一管理SQL，更适合我们这种需要精细控制查询结果的场景。”
于是我们决定在新模块中尝试接入MyBatis。虽然初期配置有些麻烦，但很快我们就尝到了甜头：
- SQL集中管理，减少冗余；
- 操作灵活，适合复杂查询；
- 易于调试，出问题也能快速定位；
- 性能可控，不需要像Hibernate那样担心缓存或N+1查询问题。
从那一刻起，我就明白了：MyBatis不是一个完全意义上的ORM框架，而是介于原生SQL与完整ORM之间的桥梁，它的核心价值在于“灵活性”与“可控制性”。
初学MyBatis时遇到的那些坑
当然，学习过程也没那么顺利，尤其是刚开始接触的一些配置细节和映射机制，让我一度怀疑人生。
坑一：XML配置写错了却找不到错误源头
第一次尝试整合MyBatis和Spring Boot时，我按照网上的例子照搬了一个mapper.xml文件，并且在application.yml里配好了扫描路径，结果启动时报错“无法找到映射器接口”，查了半天也不知道哪出了问题。
后来才意识到，MyBatis要求接口与XML必须严格对应命名空间（namespace）以及方法名，哪怕是一个字母错了，都会导致绑定失败。而且这种错误不会抛出详细的异常信息，只能靠日志一点一点排查，非常痛苦。
解决办法：
- 使用IDEA插件如
MyBatis plugin自动提示接口与XML匹配情况； - 启动时加上
mybatis.mapper-locations=classpath*:mapper/**/*.xml这样的精准路径配置； - 日志设置为DEBUG级别，方便查看MyBatis内部加载过程。
坑二：动态SQL写得一脸懵逼
有一次要做一个条件筛选功能，用户可以选择不同的搜索条件组合进行查询。刚开始我很天真地想着“这还不简单？把条件判断放到Java代码里，根据参数拼接字符串嘛”。
结果写了半天发现越来越难看，而且容易出现SQL注入隐患。这时候我才认真研究了MyBatis的 <if> 标签和 <where> 标签，真是打开了新世界的大门。
举个例子：
<select id="selectByCondition" resultType="User">
SELECT * FROM users
<where>
<if test="name != null and name != ''">
AND name LIKE CONCAT('%', #{name}, '%')
</if>
<if test="age != null">
AND age = #{age}
</if>
</where>
</select>
这样就能实现动态条件拼接，既优雅又安全，关键是不容易出错。
坑三：事务处理不一致
还有一个让我印象深刻的案例是关于事务处理的。我们在一个业务方法里调用了多个MyBatis操作，但是由于其中某个SQL语句报错，整个事务没有回滚，数据就乱了。
后来才发现，MyBatis本身并不提供完整的事务管理机制，它是依赖Spring来控制事务边界的。 我们当时只在Service层加了注解 @Transactional，但在实际执行中有个地方调用了另一个没加事务的方法，导致部分更新成功、部分失败。
这个问题提醒我们：
- 所有关联的DAO方法都应该放在同一个事务边界内；
- 注意避免“自我调用”的陷阱（即一个Service类内部调用自己的其他方法时，
@Transactional可能不起作用）； - 如果涉及到分布式事务或跨库操作，要考虑引入Seata等分布式事务组件。
实际应用中的技巧与优化
除了基础用法，我在实际项目中还总结出了一些MyBatis的进阶玩法，下面分享几个我认为比较实用的：
技巧一：合理设计Mapper接口与XML结构
我们通常会按业务模块划分mapper目录结构，比如：
src/
└── main/
└── resources/
└── mapper/
├── user/
│ └── UserMapper.xml
├── order/
│ └── OrderMapper.xml
└── ...
对应的接口：
@Mapper
public interface UserMapper {
List<User> selectByCondition(String name, Integer age);
void insert(User user);
}
这样做的好处是后期维护起来逻辑清晰，尤其是在大项目中，能快速定位某个实体的操作。
技巧二：合理使用ResultMap
MyBatis默认支持将表字段自动映射到Java对象的属性中，但如果数据库字段命名风格不一样，或者想做一些特殊转换（比如枚举），就需要使用<resultMap>标签来自定义映射关系。
例如：
<resultMap id="userResultMap" type="User">
<id property="id" column="user_id"/>
<result property="name" column="user_name"/>
<result property="gender" column="gender" typeHandler="com.example.GenderTypeHandler"/>
</resultMap>
<select id="getUserById" resultMap="userResultMap">
SELECT * FROM users WHERE user_id = #{userId}
</select>
这里我们还引入了一个typeHandler，用于处理性别字段的枚举类型，这个在实际项目中也很常见。
技巧三：合理使用二级缓存提升性能
在读多写少的场景下，MyBatis的二级缓存可以显著提高查询效率。但需要注意的是，默认情况下，每个mapper都是独立缓存区域的，如果两个mapper都关联了同一张表的数据，可能会造成数据不一致。
为了避免这种情况，我们可以开启eviction策略，或者在关键操作后主动清空缓存：
<cache eviction="LRU" flushInterval="60000" size="512" readOnly="true"/>
同时，在更新操作后加上清除缓存的操作：
<update id="updateUser">
UPDATE users SET name = #{name} WHERE id = #{id}
<clearCache/>
</update>
不过要注意：生产环境一般不会直接依赖MyBatis的二级缓存，因为缓存一致性很难保证。建议优先考虑Redis + 本地Caffeine缓存的组合方式，性能更稳定、维护也更方便。
接口设计与数据库设计中的取舍
说到接口设计，其实MyBatis虽然是持久层框架，但也间接影响了我们的接口设计思路。
比如我们有一个需求是“获取用户基本信息 + 订单数量”。如果按照传统方式，我们会分两次调用：
User user = userMapper.selectById(userId);
int orderCount = orderMapper.countByUserId(userId);
但这样做会有两个问题：
- 多次数据库查询导致延迟增加；
- 如果用户数据不存在，order那边也会做一次无意义查询。
于是我们最终改为联合查询：
SELECT u.*, COUNT(o.id) AS order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
WHERE u.id = #{userId}
GROUP BY u.id
然后返回一个包含扩展字段的UserInfoVO对象。这样不仅提高了性能，也减少了不必要的远程调用。
这说明什么呢？MyBatis虽然不是真正的ORM，但它迫使我们去思考数据库的设计是否合理、接口的颗粒度是否合适——这些恰恰是很多自动ORM框架容易忽视的地方。
生产环境中的运维经验分享
讲完开发层面的内容，再聊聊我们在生产环境维护MyBatis的经验教训：
日志监控很重要！
上线之前务必在测试环境开启MyBatis的SQL日志输出，观察是否有全表扫描、慢SQL等问题。可以通过log4j或slf4j配合stdout打印SQL语句：
logging.level.com.example.mapper=DEBUG
一旦发现慢查询，立刻分析执行计划，添加索引或重构查询逻辑。
避免SQL注入的关键点
虽然MyBatis推荐使用#{}来防止注入，但有时为了拼接IN子句，我们会误用${}，这就有潜在风险。
正确做法是使用MyBatis提供的集合遍历语法：
<select id="selectByIds" parameterType="list" resultType="User">
SELECT * FROM users WHERE id IN
<foreach item="id" collection="list" open="(" separator="," close=")">
#{id}
</foreach>
</select>
分页性能优化
对于大数据量表，使用LIMIT进行分页很容易造成性能瓶颈。MyBatis默认的分页是物理分页，如果你的表数据很大，建议使用游标分页（cursor-based pagination）或者借助Elasticsearch来做分页检索。
结语：技术选型的背后是权衡和理解
回头看看这些年用MyBatis的经历，真是一段成长的过程。它不像Hibernate那样“傻瓜化”，也不像JDBC那样裸奔，它更像一个聪明的助手，给你足够的自由，也要求你有一定的掌控力。
如果你现在正处在技术选型的十字路口，不妨问问自己几个问题：
- 是否需要对SQL有较强的控制能力？
- 是否担心某些ORM框架带来的性能损耗？
- 是否愿意花时间学习并掌握MyBatis的配置和使用技巧？
如果是的话，那就大胆上吧！毕竟在如今微服务架构盛行的时代，MyBatis依然是一个值得信赖的老朋友。
最后送给大家一句话：好的工具不是帮你省事，而是让你更懂事情的本质。
愿你在编程的路上越走越远，别怕踩坑，因为每一个坑都藏着一份成长。如果你也有MyBatis相关的经验和坑，欢迎留言交流，咱们一起进步！
评论 0