返回学习记录

Learning archive

MyBatis 学习记录

系统讲解 MyBatis 核心原理、配置、CRUD、动态 SQL、结果映射及 Spring Boot 整合实践。

2026年7月1日
  • MyBatis
  • Java
  • 持久层

MyBatis 学习记录#

本文档记录 MyBatis 的核心知识点、原理讲解与实战示例代码。 适合作为学习笔记、复习资料与面试准备。


一、MyBatis 简介#

MyBatis 是一款优秀的 持久层框架,原名 iBatis,2010 年迁移到 Google Code 后改名 MyBatis。

1.1 核心特点#

  • 半自动 ORM: SQL 由开发者手动编写,MyBatis 负责参数映射和结果映射
  • SQL 与 Java 解耦: SQL 写在 XML 或注解中,便于维护和优化
  • 灵活的映射: 支持复杂对象映射、关联查询、动态 SQL
  • 轻量级: 无第三方依赖,上手简单
  • 插件机制: 可自定义拦截器(分页、SQL 日志等)

1.2 与其他持久层框架对比#

对比项MyBatisHibernateJPA
类型半自动 ORM全自动 ORM规范
SQL 控制开发者手写自动生成自动生成
灵活性高较低较低
学习成本低高中
适用场景复杂 SQL、性能要求高简单 CRUD标准化项目

一句话: MyBatis 把 SQL 的控制权交还给开发者,灵活且高效。

1.3 核心组件#

组件作用
SqlSessionFactoryBuilder读取配置,构建 SqlSessionFactory
SqlSessionFactory生产 SqlSession,单例存在
SqlSession执行 SQL 的会话,非线程安全
Executor执行器,负责 SQL 执行
MappedStatement封装一条 SQL 语句的配置
Configuration全局配置信息

二、快速入门#

2.1 引入依赖#

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

<!-- MySQL 驱动 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.4.0</version>
</dependency>

2.2 核心配置文件(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>

    <!-- 1. 环境配置 -->
    <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/demo?useSSL=false&amp;serverTimezone=Asia/Shanghai"/>
                <property name="username" value="root"/>
                <property name="password" value="123456"/>
            </dataSource>
        </environment>
    </environments>

    <!-- 2. 注册 Mapper 映射文件 -->
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

2.3 实体类#

public class User {
    private Long id;
    private String username;
    private Integer age;
    private String email;

    // 生成 Getter / Setter / toString
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }

    @Override
    public String toString() {
        return "User{id=" + id + ", username='" + username + "', age=" + age + ", email='" + email + "'}";
    }
}

2.4 Mapper 接口#

import java.util.List;

public interface UserMapper {
    List<User> selectAll();
    User selectById(Long id);
}

2.5 Mapper 映射文件(UserMapper.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.example.mapper.UserMapper">

    <!-- 查询所有 -->
    <select id="selectAll" resultType="com.example.entity.User">
        SELECT id, username, age, email FROM user
    </select>

    <!-- 根据 ID 查询 -->
    <select id="selectById" resultType="com.example.entity.User">
        SELECT id, username, age, email FROM user WHERE id = #{id}
    </select>

</mapper>

2.6 测试代码#

import org.apache.ibatis.io.Resources;
import org.apache.ibatis.session.SqlSession;
import org.apache.ibatis.session.SqlSessionFactory;
import org.apache.ibatis.session.SqlSessionFactoryBuilder;

import java.io.InputStream;
import java.util.List;

public class MyBatisDemo {
    public static void main(String[] args) throws Exception {
        // 1. 读取配置
        InputStream is = Resources.getResourceAsStream("mybatis-config.xml");
        // 2. 构建工厂
        SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(is);
        // 3. 获取会话
        try (SqlSession session = factory.openSession()) {
            // 4. 获取 Mapper 代理
            UserMapper mapper = session.getMapper(UserMapper.class);
            // 5. 执行查询
            List<User> users = mapper.selectAll();
            users.forEach(System.out::println);

            User user = mapper.selectById(1L);
            System.out.println(user);
        }
    }
}

三、核心配置文件详解#

3.1 配置标签顺序#

mybatis-config.xml 的标签顺序有严格要求,否则会报错:

properties → settings → typeAliases → typeHandlers → objectFactory
→ objectWrapperFactory → reflectorFactory → plugins → environments
→ databaseIdProvider → mappers

3.2 properties(属性配置)#

<properties resource="db.properties"/>

<!-- db.properties -->
<!-- driver=com.mysql.cj.jdbc.Driver -->
<!-- url=jdbc:mysql://localhost:3306/demo -->
<!-- username=root -->
<!-- password=123456 -->

使用 ${} 引用:

<dataSource type="POOLED">
    <property name="driver" value="${driver}"/>
    <property name="url" value="${url}"/>
    <property name="username" value="${username}"/>
    <property name="password" value="${password}"/>
</dataSource>

3.3 settings(全局设置)#

设置说明默认值
mapUnderscoreToCamelCase开启驼峰命名映射false
cacheEnabled开启二级缓存true
lazyLoadingEnabled开启延迟加载false
logImpl日志实现自动查找
<settings>
    <setting name="mapUnderscoreToCamelCase" value="true"/>
    <setting name="logImpl" value="STDOUT_LOGGING"/>
</settings>

3.4 typeAliases(类型别名)#

<typeAliases>
    <!-- 方式一:指定类 -->
    <typeAlias type="com.example.entity.User" alias="User"/>
    <!-- 方式二:扫描包(类名首字母小写为别名) -->
    <package name="com.example.entity"/>
</typeAliases>

配置后 resultType 可以直接写 User。

3.5 mappers(映射器注册)#

<mappers>
    <!-- 方式一:XML 资源路径 -->
    <mapper resource="mapper/UserMapper.xml"/>
    <!-- 方式二:接口全限定名(要求 XML 与接口同包同名) -->
    <mapper class="com.example.mapper.UserMapper"/>
    <!-- 方式三:包扫描(推荐) -->
    <package name="com.example.mapper"/>
</mappers>

四、CRUD 操作#

4.1 insert(插入)#

<!-- 插入并返回自增主键 -->
<insert id="insertUser" parameterType="User"
        useGeneratedKeys="true" keyProperty="id">
    INSERT INTO user (username, age, email)
    VALUES (#{username}, #{age}, #{email})
</insert>
int rows = mapper.insertUser(user);
// user.getId() 此时已被填充为自增主键

4.2 update(更新)#

<update id="updateUser" parameterType="User">
    UPDATE user SET
        username = #{username},
        age = #{age},
        email = #{email}
    WHERE id = #{id}
</update>

4.3 delete(删除)#

<delete id="deleteUser" parameterType="Long">
    DELETE FROM user WHERE id = #{id}
</delete>

4.4 select(查询)#

<!-- 单个查询 -->
<select id="selectById" parameterType="Long" resultType="User">
    SELECT id, username, age, email FROM user WHERE id = #{id}
</select>

<!-- 列表查询 -->
<select id="selectAll" resultType="User">
    SELECT * FROM user
</select>

<!-- 带条件的查询 -->
<select id="selectByName" resultType="User">
    SELECT * FROM user WHERE username = #{username}
</select>

4.5 常用查询场景#

<!-- 模糊查询(推荐使用 CONCAT 防止 SQL 注入) -->
<select id="searchByName" resultType="User">
    SELECT * FROM user WHERE username LIKE CONCAT('%', #{keyword}, '%')
</select>

<!-- 多参数查询(@Param 注解) -->
<select id="selectByAgeAndName" resultType="User">
    SELECT * FROM user WHERE age = #{age} AND username = #{name}
</select>
import org.apache.ibatis.annotations.Param;

public interface UserMapper {
    List<User> searchByName(String keyword);
    List<User> selectByAgeAndName(@Param("age") int age, @Param("name") String name);
}

五、参数处理(#{} 与 ${})#

5.1 #{} 与 ${} 的区别(重点)#

对比项#{}${}
处理方式预编译,生成 ? 占位符字符串拼接,直接替换
SQL 注入安全有风险
适用传值(推荐)拼接表名、列名、ORDER BY
<!-- #{} —— 推荐,安全 -->
SELECT * FROM user WHERE id = #{id}
<!-- 编译为:SELECT * FROM user WHERE id = ? -->

<!-- ${} —— 慎用,仅用于动态表名/列名 -->
SELECT * FROM ${tableName} WHERE id = #{id}
<!-- 编译为:SELECT * FROM user WHERE id = ?(tableName 被直接拼接) -->

5.2 参数处理规则#

  • 单个基本类型参数: #{任意名称} 都能取到值
  • 多个参数: 需要 @Param 注解,或使用 arg0/param1 等方式
  • POJO 参数: 直接使用属性名,如 #{username}
// 多参数示例
List<User> selectByAgeAndName(@Param("age") int age, @Param("name") String name);
<select id="selectByAgeAndName" resultType="User">
    SELECT * FROM user WHERE age = #{age} AND username = #{name}
</select>

六、结果映射(resultMap)#

6.1 解决列名与属性名不一致#

当数据库列名(如 user_name)与实体属性名(如 userName)不一致时,使用 resultMap:

<resultMap id="UserResultMap" type="com.example.entity.User">
    <id column="id" property="id"/>
    <result column="user_name" property="userName"/>
    <result column="age" property="age"/>
    <result column="email" property="email"/>
</resultMap>

<select id="selectAll" resultMap="UserResultMap">
    SELECT id, user_name, age, email FROM user
</select>

6.2 开启驼峰命名自动映射#

配置 mapUnderscoreToCamelCase=true 后,user_name 会自动映射到 userName,无需 resultMap:

<settings>
    <setting name="mapUnderscoreToCamelCase" value="true"/>
</settings>

6.3 关联映射(一对一)#

<resultMap id="UserWithOrderMap" type="User">
    <id column="id" property="id"/>
    <result column="username" property="username"/>
    <!-- 关联订单 -->
    <association property="order" javaType="Order">
        <id column="order_id" property="id"/>
        <result column="order_no" property="orderNo"/>
        <result column="amount" property="amount"/>
    </association>
</resultMap>

<select id="selectUserWithOrder" resultMap="UserWithOrderMap">
    SELECT u.id, u.username, o.id AS order_id, o.order_no, o.amount
    FROM user u LEFT JOIN orders o ON u.id = o.user_id
    WHERE u.id = #{id}
</select>

6.4 关联映射(一对多)#

<resultMap id="UserWithOrdersMap" type="User">
    <id column="id" property="id"/>
    <result column="username" property="username"/>
    <!-- 集合关联 -->
    <collection property="orders" ofType="Order">
        <id column="order_id" property="id"/>
        <result column="order_no" property="orderNo"/>
        <result column="amount" property="amount"/>
    </collection>
</resultMap>

七、动态 SQL(核心重点)#

MyBatis 的强大之处在于动态 SQL,可以根据条件动态拼接 SQL。

7.1 <if> 条件判断#

<select id="searchUser" resultType="User">
    SELECT * FROM user
    <where>
        <if test="username != null and username != ''">
            AND username LIKE CONCAT('%', #{username}, '%')
        </if>
        <if test="age != null">
            AND age = #{age}
        </if>
    </where>
</select>

7.2 <where> 标签#

  • 自动添加 WHERE 关键字
  • 自动去除开头多余的 AND / OR

7.3 <set> 标签(更新)#

<update id="updateUserSelective">
    UPDATE user
    <set>
        <if test="username != null">username = #{username},</if>
        <if test="age != null">age = #{age},</if>
        <if test="email != null">email = #{email},</if>
    </set>
    WHERE id = #{id}
</update>
  • 自动添加 SET 关键字
  • 自动去除末尾多余的逗号

7.4 <choose> / <when> / <otherwise>#

类似 Java 的 switch:

<select id="findUser" resultType="User">
    SELECT * FROM user
    <where>
        <choose>
            <when test="id != null">
                id = #{id}
            </when>
            <when test="username != null">
                username = #{username}
            </when>
            <otherwise>
                1 = 1
            </otherwise>
        </choose>
    </where>
</select>

7.5 <foreach> 循环(重点)#

批量查询(IN):

<select id="selectByIds" resultType="User">
    SELECT * FROM user
    WHERE id IN
    <foreach collection="ids" item="id" open="(" separator="," close=")">
        #{id}
    </foreach>
</select>

批量插入:

<insert id="batchInsert">
    INSERT INTO user (username, age, email) VALUES
    <foreach collection="list" item="user" separator=",">
        (#{user.username}, #{user.age}, #{user.email})
    </foreach>
</insert>

参数说明:

属性说明
collection集合名(List 默认 list,数组默认 array)
item每次迭代的元素名
open循环开始前拼接的内容
separator元素之间的分隔符
close循环结束后拼接的内容
index索引(List 为下标,Map 为 key)

7.6 <sql> 与 <include>(SQL 片段复用)#

<!-- 定义公共片段 -->
<sql id="userColumns">
    id, username, age, email
</sql>

<!-- 引用片段 -->
<select id="selectAll" resultType="User">
    SELECT <include refid="userColumns"/> FROM user
</select>

<select id="selectById" resultType="User">
    SELECT <include refid="userColumns"/> FROM user WHERE id = #{id}
</select>

八、注解开发#

MyBatis 支持注解方式,适合简单 SQL。

import org.apache.ibatis.annotations.*;

import java.util.List;

@Mapper
public interface UserMapper {

    @Select("SELECT * FROM user")
    List<User> selectAll();

    @Select("SELECT * FROM user WHERE id = #{id}")
    User selectById(Long id);

    @Insert("INSERT INTO user (username, age, email) VALUES (#{username}, #{age}, #{email})")
    @Options(useGeneratedKeys = true, keyProperty = "id")
    int insert(User user);

    @Update("UPDATE user SET username = #{username}, age = #{age} WHERE id = #{id}")
    int update(User user);

    @Delete("DELETE FROM user WHERE id = #{id}")
    int delete(Long id);
}

8.1 注解 vs XML 对比#

对比项注解XML
简单 SQL简洁方便稍显繁琐
复杂 SQL拼接困难、可读性差清晰易维护
动态 SQL需配合 <script>,不直观原生支持
适用场景简单 CRUD复杂查询、动态 SQL

建议: 简单查询用注解,复杂 SQL(动态 SQL、关联查询)用 XML。


九、结果集处理#

9.1 resultType 与 resultMap 对比#

对比项resultTyperesultMap
适用列名与属性名一致列名与属性名不一致、复杂映射
配置简单需定义映射规则
关联查询不支持支持 <association>/<collection>

9.2 单行 vs 多行#

  • 返回单个对象:resultType="User"
  • 返回集合:resultType="User"(MyBatis 自动包装成 List)
  • 返回 Map:resultType="map"
  • 返回基本类型:resultType="int"、resultType="string"
<!-- 返回 Map -->
<select id="selectAsMap" resultType="map">
    SELECT id, username FROM user WHERE id = #{id}
</select>

十、MyBatis 与 Spring Boot 整合#

10.1 引入依赖#

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.4.0</version>
</dependency>

10.2 配置文件(application.yml)#

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/demo?useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: "123456"

mybatis:
  mapper-locations: classpath:mapper/*.xml   # XML 位置
  type-aliases-package: com.example.entity    # 别名包
  configuration:
    map-underscore-to-camel-case: true        # 驼峰映射
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl   # 打印 SQL

10.3 启动类扫描 Mapper#

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@MapperScan("com.example.mapper")   // 扫描 Mapper 接口
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

10.4 Mapper 接口#

import org.apache.ibatis.annotations.Mapper;

import java.util.List;

@Mapper
public interface UserMapper {
    List<User> selectAll();
    User selectById(Long id);
    int insert(User user);
}

10.5 Service 使用#

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

@Service
public class UserService {

    private final UserMapper userMapper;

    public UserService(UserMapper userMapper) {
        this.userMapper = userMapper;
    }

    public List<User> list() {
        return userMapper.selectAll();
    }

    public User getById(Long id) {
        return userMapper.selectById(id);
    }

    @Transactional(rollbackFor = Exception.class)
    public void add(User user) {
        userMapper.insert(user);
    }
}

十一、MyBatis 高级特性#

11.1 日志配置#

开启 SQL 日志,方便调试:

mybatis:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

或使用日志框架(如 Logback):

<settings>
    <setting name="logImpl" value="SLF4J"/>
</settings>

11.2 一级缓存与二级缓存#

缓存作用范围默认说明
一级缓存SqlSession 级别开启同一个会话内查询结果缓存
二级缓存Mapper 命名空间级别关闭跨会话共享缓存

开启二级缓存:

<!-- 全局开启 -->
<settings>
    <setting name="cacheEnabled" value="true"/>
</settings>

<!-- Mapper 中开启 -->
<cache/>
<mapper namespace="com.example.mapper.UserMapper">
    <cache eviction="LRU" flushInterval="60000" size="512" readOnly="true"/>
</mapper>

缓存失效: 同一命名空间下执行 insert/update/delete 会清空缓存。

注意: 二级缓存需实体类实现 Serializable。

11.3 延迟加载#

<settings>
    <setting name="lazyLoadingEnabled" value="true"/>
    <setting name="aggressiveLazyLoading" value="false"/>
</settings>

11.4 分页插件(PageHelper)#

<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
    <version>1.4.7</version>
</dependency>
import com.github.pagehelper.PageHelper;
import com.github.pagehelper.PageInfo;

public PageInfo<User> page(int pageNum, int pageSize) {
    PageHelper.startPage(pageNum, pageSize);
    List<User> list = userMapper.selectAll();
    return new PageInfo<>(list);
}

11.5 插件机制(Interceptor)#

MyBatis 插件通过拦截 Executor、StatementHandler、ParameterHandler、ResultSetHandler 实现:

import org.apache.ibatis.executor.Executor;
import org.apache.ibatis.plugin.Interceptor;
import org.apache.ibatis.plugin.Invocation;
import org.apache.ibatis.plugin.Intercepts;
import org.apache.ibatis.plugin.Signature;

import java.util.Properties;

@Intercepts({
    @Signature(type = Executor.class, method = "update", args = {Object.class})
})
public class MyPlugin implements Interceptor {

    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        System.out.println("执行 SQL 前...");
        Object result = invocation.proceed();
        System.out.println("执行 SQL 后...");
        return result;
    }

    @Override
    public void setProperties(Properties properties) {
    }
}

十二、常见面试题 & 易错点#

12.1 #{} 和 ${} 的区别?(高频)#

  • #{}:预编译,生成 ? 占位符,防止 SQL 注入
  • ${}:字符串拼接,有 SQL 注入风险,仅用于表名/列名/ORDER BY 等无法预编译的场景

12.2 MyBatis 的一级缓存和二级缓存?#

  • 一级缓存: SqlSession 级别,默认开启,会话关闭或执行增删改后失效
  • 二级缓存: Mapper 命名空间级别,默认关闭,需在 XML 中配置 <cache/>,实体需实现 Serializable

12.3 MyBatis 的工作原理(执行流程)?#

  1. 读取 mybatis-config.xml,构建 Configuration
  2. 创建 SqlSessionFactory
  3. SqlSessionFactory 创建 SqlSession
  4. SqlSession 获取 Mapper 代理对象
  5. 通过 MappedStatement 获取 SQL 和参数映射
  6. Executor 执行 SQL,StatementHandler 处理 JDBC
  7. ResultSetHandler 将结果映射为 Java 对象

12.4 resultType 和 resultMap 的区别?#

  • resultType:适用于列名与属性名一致(或开启驼峰映射)的场景,简单
  • resultMap:适用于列名不一致、复杂关联映射(一对一、一对多)

12.5 MyBatis 如何实现分页?#

  • 逻辑分页: 查全部再加 RowBounds,内存分页(不推荐)
  • 物理分页: 使用 PageHelper 插件,自动拼接 LIMIT(推荐)

12.6 动态 SQL 常用标签?#

<if>、<where>、<set>、<choose>/<when>/<otherwise>、<foreach>、<sql>/<include>、<trim>。

12.7 为什么 Mapper 接口不需要实现类?#

MyBatis 通过 JDK 动态代理,根据接口全限定名(namespace)和 方法名(id)找到对应的 MappedStatement,用代理对象执行 SQL。

12.8 useGeneratedKeys 和 keyProperty 的作用?#

  • useGeneratedKeys="true":使用数据库自增主键
  • keyProperty:将生成的主键值回填到实体的哪个属性
<insert id="insert" useGeneratedKeys="true" keyProperty="id">

12.9 MyBatis 中的 @Param 注解作用?#

  • 多参数时给参数命名,便于在 XML 中用 #{name} 引用
  • 单参数可省略(但基本类型建议加上)

12.10 事务回滚失败的原因?#

  • 异常被捕获未抛出(try-catch 吞掉了)
  • 抛出受检异常,未配置 rollbackFor
  • 方法非 public
  • 同类内部方法调用(绕过代理)

十三、知识总结#

  1. MyBatis 是半自动 ORM 框架,SQL 由开发者手写,灵活高效。
  2. 核心组件: SqlSessionFactory → SqlSession → Mapper 代理。
  3. 配置文件: mybatis-config.xml 中标签有严格顺序,常用 properties、settings、typeAliases、mappers。
  4. #{} 预编译防注入,${} 字符串拼接有风险,优先用 #{}。
  5. 结果映射: 简单场景用 resultType,列名不一致或关联查询用 resultMap + association/collection。
  6. 动态 SQL: if/where/set/choose/foreach/sql/include 是重点。
  7. 缓存: 一级缓存默认开启(Session 级),二级缓存需配置(Mapper 级)。
  8. Spring Boot 整合: mybatis-spring-boot-starter + @MapperScan + application.yml 配置。
  9. 分页: 推荐 PageHelper 物理分页。
  10. Mapper 无需实现类: 通过 JDK 动态代理自动生成实现。

学习建议:结合 Spring Boot 项目实际使用 MyBatis,多写复杂动态 SQL 和关联查询,阅读 MyBatis 源码理解 SqlSession 执行流程与插件机制。

页内目录13 章