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

一、什么是MyBatis？能用来做什么？

在我们开发一个Java Web项目时，常常需要和数据库打交道。比如注册用户时要把信息保存到数据库中，登录时又要从数据库里查出账号密码是否匹配。

如果我们直接使用JDBC来操作数据库的话，写起来非常繁琐，而且容易出错。这时候我们就需要用到持久层框架，而 MyBatis 就是一个非常好用的 Java 持久层框架。

简单来说：

• MyBatis 是一个连接 Java 和数据库之间的桥梁。
• 它把我们写的 SQL 语句封装成“方法”，方便调用。
• MyBatis 不会自动帮你写 SQL，但它可以让你专注于写 SQL，并更高效地执行它。

通俗一点讲，你可以把它想象成一个“翻译官” —— 把你在 Java 里说的东西（参数），翻译成数据库听得懂的 SQL 语言。

---

二、环境准备

要开始使用 MyBatis，我们需要以下几个工具：

1. 开发环境要求

• Java JDK 1.8 或以上版本
• Maven（用于管理依赖）
• MySQL 数据库
• IDEA（推荐IntelliJ IDEA，也可以是 Eclipse）

如果你没有安装这些，请先安装好，这一步不是本教程的重点，但一定要完成。

2. 创建 Maven 项目

用 IDEA 创建一个空的 Maven 项目，目录结构如下：

mybatis-demo/
├── src/
│   └── main/
│       ├── java/         → Java源代码
│       └── resources/    → 配置文件
└── pom.xml               → Maven配置文件

3. 添加 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.28</version>
</dependency>

保存之后 Maven 会自动下载相关 jar 包。

---

三、MyBatis 的核心概念

在正式写代码之前，先了解几个关键概念：

1. MyBatis 配置文件 (mybatis-config.xml)

这个文件是用来告诉 MyBatis 怎么连接数据库的，比如数据库地址、用户名、密码等。

示例内容：

新建 src/main/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/demo_db?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="123456"/>
            </dataSource>
        </environment>
    </environments>
</configuration>

注意：请根据自己的数据库修改 url、username 和 password。

2. 实体类（Entity）

实体类对应数据库中的一张表。例如，如果有一个 user 表，我们可以创建一个 User.java 类：

package com.example.entity;

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

    // Getter and 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; }
}

3. Mapper 接口 + XML 映射文件

这两个部分一起完成“SQL 到 Java 对象”的映射功能。

(1) Mapper 接口

接口中的每一个方法都代表一条 SQL 查询或者操作。

package com.example.mapper;

import com.example.entity.User;
import java.util.List;

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

(2) Mapper XML 文件

在 resources 目录下新建 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="findAllUsers" resultType="com.example.entity.User">
        SELECT * FROM user
    </select>
</mapper>

这里的 namespace 要和你的 Mapper 接口全限定名一致。

4. 注册 Mapper

回到 mybatis-config.xml 文件中，在 <configuration> 标签下加上：

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

这样 MyBatis 才能找到你写的 SQL。

---

四、实战项目：查询所有用户列表

我们现在来完整跑一次最简单的案例：从数据库中读取所有用户数据并显示出来。

步骤 1：创建数据库与数据表

使用 MySQL 客户端执行以下 SQL 创建测试数据：

CREATE DATABASE demo_db;

USE demo_db;

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');

步骤 2：编写测试类

在 src/main/java 下新建测试类 TestMyBatis.java：

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

        // 2. 获取 session
        try (SqlSession session = sqlSessionFactory.openSession()) {
            // 3. 获取 Mapper
            UserMapper mapper = session.getMapper(UserMapper.class);

            // 4. 调用方法
            List<User> users = mapper.findAllUsers();

            // 5. 输出结果
            for (User user : users) {
                System.out.println("ID：" + user.getId() + "，姓名：" + user.getName() + "，邮箱：" + user.getEmail());
            }
        }
    }
}

运行效果：

运行该类，你应该会看到输出类似下面的内容：

ID：1，姓名：张三，邮箱：zhangsan@example.com
ID：2，姓名：李四，邮箱：lisi@example.com

恭喜你，完成了第一个 MyBatis 项目！

---

五、常见问题答疑

Q1：报错：“无效的驱动器或找不到数据库”

A：请检查你的 JDBC URL 是否正确，特别是数据库名、端口号、以及 timezone 参数。

Q2：提示找不到 UserMapper？

A：有可能是没注册 XML 文件或者接口名称对不上，检查 XML 中的 namespace 是否和接口的包路径+类名一致。

Q3：SQL执行了，但是返回为空？

A：可能数据库数据未插入，也可能是字段名不匹配。建议打印 SQL 语句看看是否执行正确。

Q4：IDEA 提示 “无法解析符号 'UserMapper'”？

A：说明编译时没有加载 XML 文件，请确认 resources 目录下的 XML 文件被正确识别为资源文件。

---

六、学习建议

到这里，你已经掌握了 MyBatis 的基本使用方法。为了更好地深入学习，你可以继续探索以下内容：

学习路线建议：

学习阶段	内容
基础篇	SQL 映射文件编写、动态 SQL
提升篇	参数传递方式（@Param注解）、事务管理
高级篇	结合 Spring Boot 使用 MyBatis、MyBatis 插件、性能优化

推荐练习项目：

• 编写一个用户的增删改查小系统（CRUD）
• 查询带条件分页的结果
• 动态 SQL 构建复杂的查询逻辑

---

总结

通过这篇教程，我们了解了：

• 什么是 MyBatis 以及它的用途
• 如何搭建开发环境和引入依赖
• 熟悉了核心配置文件、Mapper接口、XML映射文件的作用
• 完成了一个完整的 MyBatis 查询数据库的实战项目
• 解决了一些初学阶段常遇到的问题

现在你可以尝试自己动手去写一个 MyBatis 项目了！如果有任何问题欢迎随时查阅文档或回来看这篇文章 😊