mybatis官方文档（超详细）

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

• 新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;
• 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 82w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 2900+ 小伙伴加入学习 ，欢迎点击围观

在 Java 后端开发领域，MyBatis 官方文档始终是开发者高效使用这一持久层框架的重要指南。无论你是刚接触数据库操作的编程新手，还是希望提升 SQL 编写能力的中级开发者，理解 MyBatis 的核心机制和文档中的最佳实践都至关重要。本文将以循序渐进的方式，结合具体案例和代码示例，带你系统性地探索 MyBatis 的核心知识点，并深入解析官方文档中未完全展开的进阶技巧。

一、MyBatis 核心概念解析

1.1 MyBatis 是什么？

MyBatis 是一个基于 Java 的持久层框架，它简化了传统 JDBC 的繁琐操作。你可以将它想象为一位“数据库翻译官”——开发者只需用面向对象的思维编写代码，MyBatis 会自动将这些代码翻译成对应的 SQL 语句，并管理数据库连接与结果映射。这种设计思想让开发者能够专注于业务逻辑，而非底层细节。

1.2 核心接口与类

MyBatis 的运行依赖几个核心组件：

• SqlSessionFactory：数据库连接工厂，类似于“数据库入口”，通过它获取 SqlSession。
• SqlSession：执行 SQL 的核心接口，负责管理事务、查询与更新操作。
• Mapper 接口：定义 SQL 方法的接口，通过 XML 或注解与 SQL 语句绑定。

示例代码：基础配置与使用

// 创建 SqlSessionFactory
String resource = "mybatis-config.xml";
InputStream inputStream = Resources.getResourceAsStream(resource);
SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);

// 获取 SqlSession 并执行查询
try (SqlSession session = sqlSessionFactory.openSession()) {
    UserMapper mapper = session.getMapper(UserMapper.class);
    User user = mapper.selectUserById(1);
    System.out.println(user.getName());
}

二、MyBatis 配置详解

2.1 全局配置文件 mybatis-config.xml

该文件是 MyBatis 的“中枢神经”，控制框架的核心行为。以下是常见配置项的分类说明：

数据源类型对比

在 <dataSource> 配置中，POOLED 类型通过连接池管理资源，适合高并发场景；而 UNPOOLED 则每次请求都新建连接，适合低频操作。

<dataSource type="POOLED">
    <property name="driver" value="com.mysql.cj.jdbc.Driver"/>
    <property name="url" value="jdbc:mysql://localhost:3306/test"/>
    <property name="username" value="root"/>
    <property name="password" value="123456"/>
</dataSource>

三、动态 SQL 的魔法

3.1 条件判断与循环语句

动态 SQL 是 MyBatis 的核心优势之一。通过 <if>、<choose>、<foreach> 等标签，开发者可以灵活生成复杂 SQL 语句。

案例：多条件查询

<select id="selectUsersByCondition" resultType="User">
    SELECT * FROM users 
    WHERE 1=1
    <if test="name != null">
        AND name LIKE CONCAT('%', #{name}, '%')
    </if>
    <if test="age > 0">
        AND age > #{age}
    </if>
</select>

循环处理集合参数

<foreach item="id" collection="ids" open="(" separator="," close=")">
    #{id}
</foreach>

四、对象关联与嵌套结果映射

4.1 一对一与一对多关系

当数据库表存在关联时（如用户与订单），需通过 <resultMap> 定义映射规则。

示例：用户与订单的一对多关系

<resultMap id="userOrderMap" type="User">
    <id property="id" column="user_id"/>
    <result property="name" column="user_name"/>
    <collection property="orders" ofType="Order">
        <id property="orderId" column="order_id"/>
        <result property="amount" column="order_amount"/>
    </collection>
</resultMap>

<select id="selectUserWithOrders" resultMap="userOrderMap">
    SELECT 
        u.id AS user_id,
        u.name AS user_name,
        o.id AS order_id,
        o.amount AS order_amount
    FROM users u
    LEFT JOIN orders o ON u.id = o.user_id
    WHERE u.id = #{id}
</select>

五、性能优化与常见问题

5.1 延迟加载与二级缓存

• 延迟加载：通过 lazyLoadingEnabled 和 aggressiveLazyLoading 配置，避免一次性加载关联对象，节省资源。
• 二级缓存：默认按命名空间（Namespace）划分缓存，需在 mapper 标签中启用 cache。

<!-- 开启二级缓存 -->
<cache/>

5.2 SQL 注入防范与空值处理

始终使用 #{} 替代 $ 进行参数绑定，防止 SQL 注入。对于空值字段，可结合 <where> 标签自动过滤无效条件：

<where>
    <if test="name != null">
        AND name = #{name}
    </if>
</where>

六、最佳实践与进阶技巧

6.1 分页查询的两种方案

• RowBounds 分页：通过 RowBounds 对象传递偏移量和数量，适合简单场景。
• LIMIT 语法：直接在 SQL 中使用 LIMIT #{offset}, #{limit}，需注意数据库方言差异。

6.2 事务管理与资源释放

MyBatis 事务需显式提交或回滚，且 SqlSession 必须在 finally 块中关闭：

SqlSession session = sqlSessionFactory.openSession();
try {
    // 执行操作
    session.commit();
} catch (Exception e) {
    session.rollback();
    throw e;
} finally {
    session.close();
}

结论

MyBatis 官方文档不仅提供了框架的基本用法，更隐藏着大量优化技巧与设计哲学。通过本文的解析，开发者应能掌握从基础配置到复杂场景的完整技术链路。建议读者在实践中结合官方文档中的“Language Reference”和“API”章节，逐步探索如插件开发、自定义类型处理器等高级功能。记住，MyBatis 的灵活性正源于其对 SQL 的尊重——理解 SQL 本质，才能真正驾驭这一框架的力量。