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

---

开篇：MyBatis 是什么，能做什么？

你有没有遇到过这样的问题：写 Java 程序操作数据库的时候，每次都得自己写 JDBC 代码？连接数据库、执行 SQL、处理结果集，这些重复的工作是不是很烦人？

这时候，我们就需要一个“工具”来简化这个过程，这就是我们今天要学的——MyBatis。

MyBatis 是谁？

MyBatis 是一个 Java 的持久层（数据库访问层）框架。它不像 Hibernate 那种完全自动映射 ORM 框架，而是允许你用 SQL 来直接与数据库打交道，但又帮你管理了大量底层细节，比如：

• 连接池
• SQL 执行
• 结果封装成 Java 对象
• 参数传递方式

你可以把它理解成 “手动挡的 SQL 工具箱”：自由灵活，同时又不重复造轮子。

---

环境准备：搭建你的第一个 MyBatis 开发环境

本节目标：安装并配置好一个可以跑 MyBatis 的 Java 开发环境。

步骤1：准备好开发工具

你需要以下工具和软件：

工具	推荐版本	下载地址
JDK	8 或以上	https://adoptium.net/zh-CN/temurin/releases/
Maven	最新版	https://maven.apache.org/download.cgi
IDE	IDEA / Eclipse	https://www.jetbrains.com/idea/download/
数据库	MySQL 5.7+	https://dev.mysql.com/downloads/installer/

💡 Tips：如果你是初学者，建议使用 IntelliJ IDEA 社区版 + Maven 管理项目，IDEA 对 Maven 支持很好，适合新手上手。

---

步骤2：创建一个新的 Maven 项目

1. 打开 IDEA -> File -> New -> Project -> Maven（勾选 Create from archetype）
2. 选择 maven-archetype-quickstart
3. 填写 GroupId: com.example，ArtifactId: mybatis-demo

完成后会生成如下结构：

mybatis-demo
├── pom.xml
└── src
    ├── main
    │   ├── java/com/example/App.java
    │   └── resources/
    └── test/java/com/example/AppTest.java

---

步骤3：引入 MyBatis 和 MySQL 依赖

打开 pom.xml 文件，添加以下依赖项到 <dependencies> 标签中：

<!-- MyBatis 核心库 -->
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.9</version>
</dependency>

<!-- MySQL 驱动 -->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>

---

步骤4：建立数据库和表（示例）

新建一个测试用数据库，并插入一张简单的用户表：

-- 创建数据库
CREATE DATABASE mybatis_demo;

-- 使用数据库
USE mybatis_demo;

-- 创建用户表
CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(255),
    email VARCHAR(255)
);

-- 插入数据
INSERT INTO users (name, email) VALUES ('张三', 'zhangsan@example.com');

---

核心概念：MyBatis 的关键知识点通俗讲解

现在我们了解了什么是 MyBatis，也搭好了环境。接下来我们来看看它的几个核心概念。

---

✅ 核心一：SqlSessionFactory 和 SqlSession

在 MyBatis 中，我们需要先创建一个全局唯一的 SqlSessionFactory，它就像工厂一样负责生产 SqlSession。

• SqlSessionFactory：整个应用程序只创建一次，用于生成会话。
• SqlSession：代表一个数据库会话，用来执行 SQL、获取 mapper、提交事务等。

示例代码：

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

---

✅ 核心二：Mapper 映射文件

Mapper 就是你写的接口类，用来定义你希望执行哪些数据库操作，例如查询所有用户、根据 ID 查用户、新增用户等。

而对应的 XML 文件，则是具体 SQL 的实现地。MyBatis 会将接口中的方法名与 XML 中的 SQL ID 自动绑定起来。

示例接口：UserMapper.java

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

对应 XML 文件：UserMapper.xml

<mapper namespace="com.example.mapper.UserMapper">
    <select id="selectAllUsers" resultType="com.example.model.User">
        SELECT * FROM users;
    </select>
</mapper>

---

✅ 核心三：XML 配置文件 mybatis-config.xml

这是 MyBatis 的全局配置文件，告诉 MyBatis：

• 数据库连接信息（URL、用户名、密码）
• 是否开启缓存、事务控制等特性

示例内容：

<?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/mybatis_demo"/>
                <property name="username" value="root"/>
                <property name="password" value="yourpassword"/>
            </dataSource>
        </environment>
    </environments>
    
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

---

✅ 核心四：Java Bean 对象（Model 类）

也就是所谓的实体类，用来映射数据库表字段。每个字段对应对象属性。

示例：User.java

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

    // Getter and Setter 方法
}

---

实战项目：做一个“用户管理系统”的查询功能

现在我们来动手做一个最简单的小项目——查询所有用户数据。

---

步骤1：建立 Model 类 —— User.java

package com.example.model;

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

    public Integer getId() { return id; }
    public void setId(Integer 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 + '\'' +
                '}';
    }
}

---

步骤2：编写 Mapper 接口 —— UserMapper.java

package com.example.mapper;

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

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

---

步骤3：编写 XML 映射文件 —— resources/mapper/UserMapper.xml

在 resources 文件夹下新建 mapper 目录，然后放入该 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 users;
    </select>
</mapper>

---

步骤4：编写主程序测试 —— App.java

package com.example;

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

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

            // 调用方法查询所有用户
            List<User> users = userMapper.selectAllUsers();

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

---

运行结果：

如果一切正常，你将在控制台看到类似以下输出：

User{id=1, name='张三', email='zhangsan@example.com'}

恭喜！你已经完成了你的第一个 MyBatis 查询项目！

---

常见问题解答 FAQ

刚接触 MyBatis 的时候，很多人会有下面这些问题：

---

❓ 为什么报错：无效的 bound statement not found？

这通常是由于：

• Mapper XML 的 namespace 和 Java Mapper 接口路径不一致
• XML 中的 id 拼写错误或方法不存在
• 没有正确注册 Mapper 文件

👉 解决方法： 确认你的 XML namespace 必须和接口类的全限定名相同，例如：

package com.example.mapper;

public interface UserMapper {}

那么 XML 中必须写：

<mapper namespace="com.example.mapper.UserMapper">

---

❓ 报错：找不到驱动类 com.mysql.cj.jdbc.Driver

这是因为没加 MySQL 驱动依赖或版本不对。

👉 解决方法： 检查 pom.xml 中是否包含：

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

并且确认数据库 URL 写法是否正确：

jdbc:mysql://localhost:3306/mydb?serverTimezone=UTC

对于 MySQL 8.x，必须加上时区设置。

---

❓ 返回结果为空，但是数据库明明有数据？

可能是以下原因：

• 表字段名和 Java 属性名不一样
• 没有给字段起别名匹配 Java 属性名
• XML 中 resultType 指定错误

👉 解决方法： 确保字段名和类的属性名一致，如果不一致可以用 SQL 别名进行映射：

SELECT id AS id, name AS name, email AS userEmail ...

然后 Java 属性叫做 userEmail。

---

学习建议：下一步怎么走？

学会了基本的查询只是万里长征第一步，接下来你可以继续学习这些进阶知识：

学习主题	内容概要
MyBatis 增删改操作	包括 insert、update、delete 的使用方法
参数绑定	单参数、多参数、Map 传参、@Param 注解
动态 SQL	if、choose、foreach 等强大条件判断
关联查询	一对一、一对多的嵌套查询及结果封装
注解版 MyBatis	不写 XML，直接在接口中注解 SQL
Spring 整合 MyBatis	在 Spring Boot 项目中整合使用

推荐书籍：

• 《MyBatis 从入门到精通》——刘增辉
• 《深入浅出 MyBatis 技术原理与实战》——杨开振

视频课程可以在 B站、慕课网、网易云课堂搜索“MyBatis零基础入门”找到大量免费资源。

---

总结回顾

今天我们完成了一个完整的入门流程：

✅ 认识了 MyBatis 是什么
✅ 搭建了开发环境
✅ 学习了四大核心概念
✅ 完成了一个查询项目的实战
✅ 解答了常见的错误问题
✅ 给出了后续的学习方向建议

只要坚持跟着练一遍，相信你已经对 MyBatis 有了一个清晰的认识。接下来，让我们一起继续向更高级的后端世界迈进吧！

---

🎉 练习小任务： 试着扩展刚刚做的查询功能，为用户新增一个 “通过 ID 查询” 的方法吧！

期待你在评论区分享你的练习成果哦 😄