MyBatis 基础教程：Java 持久层框架入门

一、开篇：MyBatis 是什么？能做什么？

你可能已经学过 Java，也写过一些控制台程序或简单的 Web 应用。但你会发现，Java 本身并不能直接和数据库打交道。这时我们就需要一个工具来帮助我们连接数据库、执行 SQL，并把结果转化为 Java 对象。

MyBatis 就是这样一个工具，它是一个优秀的持久层框架，专门用来简化 Java 程序与数据库之间的交互。

为什么使用 MyBatis？

• 避免重复的 JDBC 代码（比如连接数据库、执行 SQL、处理结果集等）
• 可控性强，SQL 由开发者编写，不会像其他 ORM 框架那样自动生成
• 简洁灵活，学习成本低，非常适合初学者

接下来我们就一步步带你认识 MyBatis，并通过一个小项目来实践它的基本用法。

---

二、环境准备：搭建你的 MyBatis 开发环境

要开始使用 MyBatis，你需要准备好以下几个基础环境：

1. 安装 JDK（Java Development Kit）

确保你已经安装了 JDK，推荐使用 JDK 8 或以上版本。

验证是否安装成功：

java -version

2. 安装开发工具 IDEA / Eclipse

推荐使用 IntelliJ IDEA，因为它对 Java 支持非常友好。

下载地址：https://www.jetbrains.com/idea/

3. 创建 Maven 项目

MyBatis 通常配合 Maven 来管理依赖库。如果你还不熟悉 Maven，可以简单理解为它是一个“自动下载所需工具包”的系统。

新建 Maven 项目步骤：

1. 打开 IDEA → Create New Project → Maven
2. 设置 GroupId 和 ArtifactId（例如 com.example.mybatisdemo）
3. 完成创建

4. 添加 MyBatis 依赖

打开 pom.xml 文件，在 <dependencies> 中添加以下内容：

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

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.26</version>
</dependency>

这样就引入了 MyBatis 和 MySQL 的驱动程序。

---

三、核心概念：MyBatis 中的关键术语

在深入编程之前，我们需要先了解几个核心概念。

1. Mapper（映射器）

Mapper 是 MyBatis 最关键的部分，它相当于一个“中介”，负责将 SQL 语句和 Java 类联系起来。你可以把它想象成一张地图，告诉你某个 SQL 查询的结果应该对应哪个 Java 对象。

2. SQL 映射文件（XML 文件）

我们会在 XML 文件中编写 SQL 查询语句，并告诉 MyBatis 这些查询的结果如何映射成 Java 对象。

3. MyBatis 全局配置文件（mybatis-config.xml）

这是 MyBatis 的总开关，主要用来配置数据库连接信息以及加载哪些 mapper 文件。

4. SessionFactory 和 SqlSession

• SessionFactory：MyBatis 启动后生成的一个工厂对象，用于创建访问数据库的会话。
• SqlSession：代表一次数据库会话，你可以通过它执行 SQL、调用 Mapper 等操作。

---

四、实战项目：用 MyBatis 查询数据库中的用户信息

我们来做一个最简单的例子：从数据库中查询所有用户的信息，并显示出来。

第一步：准备数据库和表

假设你已经安装了 MySQL，创建如下数据库和表：

CREATE DATABASE mydb;

USE mydb;

CREATE TABLE user (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(50),
    email VARCHAR(100)
);

INSERT INTO user (name, email) VALUES ('张三', 'zhangsan@example.com');
INSERT INTO user (name, email) VALUES ('李四', 'lisi@example.com');

第二步：创建 User 类

创建一个 Java 类，对应 user 表：

public class User {
    private int id;
    private String name;
    private String email;

    // Getter 和 Setter 方法
    public int getId() { return id; }
    public void setId(int id) { this.id = id; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }

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

第三步：创建 Mapper 接口

创建一个接口，定义我们要执行的方法：

import java.util.List;

public interface UserMapper {
    List<User> selectAllUsers();
}

第四步：创建对应的 XML 映射文件

在 resources 目录下创建一个 XML 文件，例如：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="selectAllUsers" resultType="com.example.model.User">
        SELECT * FROM user
    </select>
</mapper>

第五步：配置 mybatis-config.xml

在 resources 下创建 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?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="123456"/>
            </dataSource>
        </environment>
    </environments>

    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

第六步：编写主类运行查询

创建一个主类：

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 MainApp {
    public static void main(String[] args) throws Exception {
        // 加载配置文件
        String resource = "mybatis-config.xml";
        InputStream inputStream = Resources.getResourceAsStream(resource);
        SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);

        // 打开数据库会话
        try (SqlSession session = sqlSessionFactory.openSession()) {
            // 获取 Mapper 接口的实现类
            UserMapper mapper = session.getMapper(UserMapper.class);

            // 执行查询
            List<User> users = mapper.selectAllUsers();

            // 输出结果
            for (User user : users) {
                System.out.println(user);
            }
        }
    }
}

运行 MainApp 类，你应该能看到输出两个用户的信息！

---

五、常见问题解答

Q1：报错找不到 Driver 或 URL 错误怎么办？

答：

• 检查你的 MySQL 是否正在运行
• 检查数据库连接字符串是否正确（包括用户名、密码、数据库名）
• 查看 pom.xml 中是否正确引入了 mysql-connector-java 包

Q2：Mapper 接口无法被识别？

答： 检查 mybatis-config.xml 中有没有正确配置 <mappers> 标签，XML 文件路径是否正确。

Q3：resultType 写错了会不会报错？

答： 会！如果 resultType 指定的类不存在或字段不匹配，MyBatis 会抛出异常，所以务必保证类存在且字段对应。

---

六、学习建议：下一步怎么学？

恭喜你完成了第一个 MyBatis 示例！接下来你可以继续学习这些进阶知识：

✅ 建议学习路线：

1. 参数传值与动态 SQL

   • 了解如何给 SQL 传递参数（@Param 注解、Map 等）
   • 学习使用 <if>、<foreach> 等标签写动态 SQL

2. 注解方式使用 MyBatis

   • 不用 XML 文件，直接在接口上使用注解写 SQL

3. 结合 Spring Boot 使用 MyBatis

   • 学会在 Spring Boot 项目中整合 MyBatis，开发完整项目

4. 事务管理与分页查询

   • 学习在业务逻辑中控制事务
   • 实现分页功能，提升查询效率

5. 源码浅析

   • 如果你想深入了解 MyBatis 的底层原理，可研究其源码设计思路

---

总结

本教程带你从零开始学习 MyBatis，讲解了基本概念、搭建开发环境、实际项目练习，并解答了一些常见问题。

记住一句话：MyBatis 是一个帮你更方便地写 SQL 和操作数据库的工具，它是通往 Java 后端开发的重要一步。

只要多动手、多练习，你一定可以掌握它！

---

如需获取本教程的完整代码示例，欢迎留言或关注公众号获取资料包！