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

开篇：什么是MyBatis？

在开发 Java Web 项目时，我们经常需要和数据库打交道。比如注册一个用户、查询用户信息、更新数据等等。通常我们会使用 JDBC 来操作数据库，但直接写 SQL 和处理结果集非常麻烦，而且容易出错。

那有没有一种方式，可以让我们更方便地操作数据库呢？

答案就是今天我们要学的——MyBatis！

简单介绍

MyBatis 是一个优秀的 Java 持久层框架（ORM框架），它的核心作用是帮助开发者更简单、高效地与数据库交互。

• ✅ 不强制你完全屏蔽 SQL，而是提供了一个灵活的方式来编写 SQL。
• ✅ 支持自定义 SQL、存储过程。
• ✅ 自动把结果映射到 Java 对象中，省去手动转换的过程。

我们可以把它理解成“数据库和 Java 对象之间的翻译官”。

---

环境准备：搭建MyBatis开发环境

在正式学习 MyBatis 前，我们需要准备好以下开发工具：

所需工具清单：

工具	说明
JDK 1.8+	Java 运行环境
IDE	推荐 IntelliJ IDEA 或 Eclipse
数据库	MySQL（或你熟悉的任意数据库）
Maven	依赖管理工具

📌 提示：如果你还不太熟悉 Maven，不用担心，接下来会一步步带你用上它。

第一步：创建Maven项目

打开 IDEA → New Project → Maven → Create from archetype → 选择 maven-archetype-quickstart

输入 GroupId（比如 com.example）、ArtifactId（比如 mybatis-demo）

项目创建好后，你会看到如下目录结构：

src
├── main
│   ├── java
│   └── resources
└── test

第二步：添加MyBatis依赖

打开项目的 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.28</version>
</dependency>

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

第三步：配置数据库连接信息

在 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/test?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="123456"/>
            </dataSource>
        </environment>
    </environments>
    
    <!-- 注册 Mapper 文件位置（后面讲） -->
    <mappers>
        <mapper resource="UserMapper.xml"/>
    </mappers>
</configuration>

注意：

• 修改你的数据库地址、用户名和密码。
• 如果你是其他数据库（如 Oracle），Driver 和 URL 要换掉。

---

核心概念：MyBatis的关键组件

要理解 MyBatis 的工作原理，先认识这几个重要角色：

1. SqlSessionFactory（工厂类）

这是整个 MyBatis 的入口点，通过它来获取操作数据库的对象。

初始化方式如下：

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

2. SqlSession（数据库会话）

相当于一次与数据库的连接会话，可以执行 SQL 查询、插入等操作。

SqlSession session = sqlSessionFactory.openSession();
try {
    // 在这里做数据库操作
} finally {
    session.close();
}

3. Mapper接口 + XML映射文件

这是我们编写的接口和对应的 XML 文件，用于描述如何调用 SQL 和映射结果。

❗划重点：MyBatis 允许我们将 SQL 写在 XML 文件中，同时配合 Java 接口来调用这些方法，这样代码结构清晰又易于维护。

---

实战项目：实现一个简单的查询功能

我们现在来做一个小项目：实现对“用户表”的查询功能。

步骤一：准备数据库和表

打开你的 MySQL，创建一个测试数据库 test，再创建一张表：

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

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

步骤二：创建Java实体类

在 src/main/java/com.example 下创建一个 User.java 类：

package com.example;

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接口和XML文件

创建接口文件：UserMapper.java

package com.example.mapper;

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

public interface UserMapper {
    List<User> getAllUsers();   // 查询所有用户
}

创建对应 XML 文件：UserMapper.xml（放在 resources 目录下）

<?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="getAllUsers" resultType="com.example.User">
        SELECT * FROM user
    </select>

</mapper>

💡解释：

• namespace 是接口的全路径名。
• id 是接口的方法名。
• resultType 表示 SQL 返回的结果应该转成哪个 Java 类型。

步骤四：测试查询功能

在 src/test/java/... 中创建一个测试类：

package com.example.test;

import com.example.mapper.UserMapper;
import com.example.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;


![负载均衡配置-1](https://code-guide.oss.shanghai.autogptai.club/common/file/download?name=date2025061517/5668053a-a02c-4b7c-a47e-24db54d6c072.jpg)


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

public class TestMyBatis {
    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()) {
            UserMapper mapper = session.getMapper(UserMapper.class);
            List<User> users = mapper.getAllUsers();
            for (User u : users) {
                System.out.println(u);
            }
        }
    }
}

运行该类，如果控制台成功打印出用户信息，恭喜！你的第一个 MyBatis 项目跑起来了 🎉

---

常见问题：新手容易踩坑的地方

1. 报错：找不到 Mapper 文件

• 🔍 检查：
  • mybatis-config.xml 是否正确引入了 Mapper 文件。
  • XML 文件是否在资源目录下。
  • 文件名是否一致，路径是否正确。

2. 报错：字段名称与类属性不匹配

• 💡 解决方案：
  • SQL 字段名要和 Java Bean 属性名保持一致（或者使用别名）。
  • 可以使用 resultMap 显式映射字段。

3. 数据库连接失败

• 🔧 检查：
  • JDBC URL 是否正确。
  • 用户名和密码是否正确。
  • MySQL 是否允许远程连接（如果是本地访问则不需要考虑）。

4. 使用中文乱码怎么办？

• 加上参数：characterEncoding=utf8 到 JDBC URL 中即可。

---

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

学到这里，恭喜你已经迈出了 MyBatis 的第一步！接下来你可以尝试以下几个方向继续深入学习：

🔹 1. 更多CRUD操作

学习 insert、update、delete 等基本操作，掌握传参方式（如注解、map对象等）

🔹 2. 动态SQL

掌握 <if>、<choose>、<foreach> 等标签，写出适应不同条件的动态查询语句

🔹 3. 注解方式开发

MyBatis 也支持不使用 XML，全部用 Java 注解实现 SQL 映射

🔹 4. 结合Spring Boot使用

真正的企业开发中，MyBatis 多和 Spring Boot 一起使用，构建完整的 Web 应用程序

---

总结

本篇文章带着你从零开始，搭建环境、了解 MyBatis 的核心概念，并完成了一个简单的实战小项目。虽然只是入门，但这为你进一步学习打下了坚实的基础。

🧭 学编程就像学骑车，刚开始可能会摇摆不定，但坚持练习就会越来越稳。加油吧，未来的大神！

如果你想进阶学习 MyBatis 高级技巧、动态 SQL、延迟加载、缓存等内容，欢迎持续关注后续教程 👇

---

📚 参考资料：

• MyBatis 官方文档
• 《MyBatis从入门到精通》书籍
• Maven中央仓库：https://mvnrepository.com/

如有任何问题，也可以留言交流哦 😊