异常教程

mybatis 文档（超详细）

更新时间:

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

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

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

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

在 Java 后端开发领域，mybatis 文档作为一款轻量级持久层框架，凭借其灵活的 SQL 写法和高度的可定制性，成为许多开发者构建数据库交互逻辑的首选工具。无论是刚接触 Java 的编程初学者，还是有一定经验的中级开发者，掌握 MyBatis 的核心原理与实践技巧，都能显著提升开发效率。本文将通过 mybatis 文档的视角，系统性地讲解 MyBatis 的基础概念、核心组件、配置方法以及高级功能，结合实际案例与代码示例，帮助读者逐步构建对框架的全面认知。

一、MyBatis 的核心设计理念

1.1 什么是 MyBatis？

MyBatis 是一个基于 Java 的持久层框架，它简化了传统 JDBC 的繁琐操作，通过 XML 或注解方式将 SQL 语句与 Java 对象（POJO）进行映射。其核心设计理念可以概括为 “让开发者更专注于 SQL 的编写，而非数据库连接的细节”。

比喻说明：
可以将 MyBatis 想象成一位“翻译官”。当开发者需要操作数据库时，只需用 Java 对象描述业务需求（如“查询用户信息”），MyBatis 就会自动将这些需求“翻译”成对应的 SQL 语句，并将数据库返回的结果“翻译”成 Java 对象返回。

1.2 MyBatis 与 ORM 框架的差异

与 Hibernate 等全 ORM 框架不同，MyBatis 采用 半自动化映射 方式，即开发者需要手动编写 SQL 语句，但框架会自动处理 SQL 参数绑定、结果集映射等底层操作。这种设计既保留了 SQL 的灵活性，又避免了 ORM 框架的“黑箱”问题。

二、快速入门：MyBatis 的基础配置

2.1 环境搭建

要使用 MyBatis，需先在项目中引入其核心依赖。以 Maven 为例，可在 pom.xml 中添加以下配置：

<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.10</version>
</dependency>

2.2 核心配置文件 mybatis-config.xml

所有 MyBatis 应用的核心配置均通过 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>
  <environments default="development">
    <environment id="development">
      <transactionManager type="JDBC"/>
      <dataSource type="POOLED">
        <property name="driver" value="com.mysql.cj.jdbc.Driver"/>
        <property name="url" value="jdbc:mysql://localhost:3306/mydb"/>
        <property name="username" value="root"/>
        <property name="password" value="123456"/>
      </dataSource>
    </environment>
  </environments>
  <mappers>
    <mapper resource="mappers/UserMapper.xml"/>
  </mappers>
</configuration>

关键点解析：

  • <environments> 定义数据库连接环境，支持多种事务管理器（如 Jdbc、Jta）。
  • <dataSource> 配置数据源参数，此处使用 POOLED 类型实现连接池功能。
  • <mappers> 指定 SQL 映射文件的路径，后续需将 SQL 逻辑与 Java 方法绑定。

三、核心组件详解

3.1 SqlSession

SqlSession 是 MyBatis 提供的接口，用于执行 SQL 语句、提交或回滚事务。通过 SqlSessionFactory 可创建 SqlSession 实例：

SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder()
    .build(Resources.getResourceAsStream("mybatis-config.xml"));
SqlSession session = sqlSessionFactory.openSession();

比喻说明：
SqlSession 可类比为“数据库连接会话”，开发者通过它向数据库发送 SQL 请求，并接收执行结果。

3.2 映射器（Mapper）

映射器是 MyBatis 的核心概念，通过 XML 或注解定义 SQL 语句与 Java 方法的对应关系。以下是一个 XML 映射文件示例：

<mapper namespace="com.example.mapper.UserMapper">
  <select id="selectUserById" resultType="com.example.model.User">
    SELECT * FROM users WHERE id = #{id}
  </select>
</mapper>

配合接口定义：

public interface UserMapper {
    User selectUserById(int id);
}

关键点解析：

  • namespace 指定接口的全限定名，确保 SQL 语句与接口方法一一对应。
  • #{id} 是 MyBatis 的参数占位符，框架会自动将 Java 方法参数绑定到 SQL 语句中。

四、动态 SQL 与高级功能

4.1 动态 SQL 的语法

MyBatis 提供了丰富的动态 SQL 标签（如 <if>、<choose>、<foreach>），用于根据条件生成不同的 SQL 语句。例如，实现条件查询：

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

比喻说明：
动态 SQL 好比“智能拼图”，开发者通过条件标签将 SQL 片段组合成最终的查询语句，避免硬编码多条相似的 SQL。

4.2 缓存机制

MyBatis 支持一级缓存（默认启用）和二级缓存（需手动配置），可显著提升查询性能。例如，开启二级缓存需在映射器 XML 中添加：

<cache/>

缓存工作原理：

  • 一级缓存：作用域为 SqlSession，在同一个会话内重复查询同一对象时，直接返回缓存结果。
  • 二级缓存：作用域为 Mapper，跨会话共享数据，但需确保数据对象实现 Serializable 接口。

五、常见问题与解决方案

5.1 SQL 参数绑定的注意事项

在 MyBatis 中，#{} 和 ${} 的使用有本质区别：

  • #{} 是预编译占位符，防止 SQL 注入，适合参数绑定。
  • ${} 是直接字符串替换，需谨慎使用，避免安全风险。

案例对比：

<!-- 安全写法 -->
WHERE id = #{id}

<!-- 风险写法（可能引发 SQL 注入） -->
WHERE id = ${id}

5.2 一对一与一对多关联查询

通过 <association> 和 <collection> 标签实现复杂对象映射。例如，用户与订单的关联查询：

<select id="selectUserWithOrders" resultType="User">
  SELECT 
    u.id AS userId,
    u.name AS userName,
    o.id AS orderId,
    o.amount AS orderAmount
  FROM users u
  LEFT JOIN orders o ON u.id = o.user_id
  <resultMap id="userResultMap" type="User">
    <id property="id" column="userId"/>
    <result property="name" column="userName"/>
    <collection property="orders" ofType="Order">
      <id property="id" column="orderId"/>
      <result property="amount" column="orderAmount"/>
    </collection>
  </resultMap>
</select>

六、总结与进阶建议

通过本文的学习，读者应已掌握 MyBatis 的核心概念、配置方法以及常见场景的实现技巧。建议进一步深入 mybatis 文档，重点关注以下内容：

  1. 事务管理：理解 @Transactional 注解与 MyBatis 的集成方式。
  2. 分页插件：如使用 MyBatis-PageHelper 实现通用分页逻辑。
  3. 性能优化：通过 SQL 解析 和 缓存策略 提升系统响应速度。

最后提醒：
MyBatis 的灵活性源于其“半自动化”设计，开发者需平衡“代码量”与“可维护性”。建议在复杂项目中采用 Mapper 接口 + XML 的分层设计，避免 SQL 语句与业务逻辑耦合过紧。

希望本文能成为您掌握 MyBatis 的起点，后续可通过实践项目或参与开源社区，持续提升数据库交互能力！

最新发布

查看更多文章