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

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

在我们开始编写后端程序时，常常需要和数据库打交道。比如我们要做一个网站的用户注册系统，那我们就需要将用户输入的账号、密码等信息保存到数据库中。当用户登录的时候，又要从数据库中读取这些信息进行验证。

传统方式中，我们需要自己写很多SQL语句，并且手动处理数据库连接、结果集解析等工作。这不仅繁琐，而且容易出错。

MyBatis 就是一个帮助你简化与数据库交互的 Java 框架。它不像Hibernate那样完全隐藏SQL，而是提供了一种非常灵活的方式，让我们可以专注于 SQL 编写，同时又能享受框架带来的便利。

换句话说，你可以把 MyBatis 看作一个“智能的 JDBC 工具包”，它帮你管理数据库连接、事务、查询执行等工作，而你可以把精力集中在实际的 SQL 逻辑上。

---

环境准备：搭建开发环境

为了使用 MyBatis，我们需要准备好以下开发工具：

所需软件/组件清单

• JDK 1.8 或以上版本
• IntelliJ IDEA（或其他 IDE，如 Eclipse）
• Maven（用于依赖管理）
• MySQL 数据库（或 SQLite、PostgreSQL 等其他数据库）

⚠️ 提示：本文以 MySQL 为例讲解，请提前安装好 MySQL 并创建测试数据库。

第一步：创建 Maven 项目

打开 IntelliJ IDEA，选择 File -> New -> Project -> Maven

填写 GroupId（比如 com.example）和 ArtifactId（比如 mybatis-demo），然后点击完成。

Maven 会自动生成一个基础目录结构和 pom.xml 文件。

第二步：添加 MyBatis 和 MySQL 驱动依赖

打开 pom.xml 文件，在 <dependencies> 标签里添加如下内容：

<dependencies>
    <!-- MyBatis 核心依赖 -->
    <dependency>
        <groupId>org.mybatis</groupId>
        <artifactId>mybatis</artifactId>
        <version>3.5.7</version>
    </dependency>

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

    <!-- 日志支持（可选但建议） -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-simple</artifactId>
        <version>2.0.0</version>
    </dependency>
</dependencies>

保存之后，Maven 会自动下载并导入相关依赖。

---

核心概念：通俗解释关键知识点

使用 MyBatis 最核心的几个概念包括：

• SqlSessionFactory
• SqlSession
• Mapper 接口 / XML 映射文件
• POJO 类（实体类）

我们可以用生活中的例子来理解这些概念：

概念	生活类比	作用说明
SqlSessionFactory	工厂管理员	负责生产 SqlSession
SqlSession	工人（负责干活的人）	实际与数据库沟通的对象
Mapper 接口 / XML 映射文件	工艺图纸	告诉数据库要执行什么 SQL
POJO 类	产品图纸	对应数据库表的一行数据

接下来，我们将一步步了解这些组件的作用和使用方法。

---

实战项目：用 MyBatis 实现一个“用户列表”功能

目标：实现一个简单的控制台程序，能从数据库中读取所有用户的信息并打印出来。

第一步：准备数据库和表

首先，我们在本地 MySQL 创建一个测试数据库和表：

CREATE DATABASE mytest;

USE mytest;

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 实体类

在 src/main/java/com/example 包下新建一个类：

package com.example;

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

    // 必须有无参构造函数
    public User() {}

    public User(int id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }

    // Getter 和 Setter 方法（略）
}

第三步：配置 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/mytest?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="your_password"/>
            </dataSource>
        </environment>
    </environments>

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

⚠️ 注意替换 your_password 为你自己的数据库密码。

第四步：编写映射文件 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="userMapper">

    <select id="selectAllUsers" resultType="com.example.User">
        SELECT * FROM user
    </select>

</mapper>

第五步：编写主程序类

创建一个主类 App.java：

package com.example;

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 {
        String resource = "mybatis-config.xml";
        InputStream inputStream = Resources.getResourceAsStream(resource);
        SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);

        try (SqlSession session = sqlSessionFactory.openSession()) {
            List<User> users = session.selectList("selectAllUsers");
            for (User user : users) {
                System.out.println(user.getName() + " - " + user.getEmail());
            }
        }
    }
}

运行这个类，控制台应该输出：

张三 - zhangsan@example.com
李四 - lisi@example.com

恭喜！你已经成功完成了第一个 MyBatis 项目！

---

常见问题解答

以下是初学者在使用 MyBatis 时常遇到的问题及其解决办法：

Q1：报错 “Could not find resource”

可能是路径错误，检查你的资源文件（如 mybatis-config.xml 或 UserMapper.xml）是否真的放在 resources 目录下，并被正确打包进 jar。

Q2：找不到驱动类 com.mysql.cj.jdbc.Driver

确认你是否添加了 MySQL 的 Maven 依赖。如果你使用的是低版本 MySQL，可能需要将驱动类名改为 com.mysql.jdbc.Driver。

Q3：执行 selectList 返回空列表

请确保数据库中确实有数据，并且 SQL 是正确的；也可以尝试打印 SQL 查看是否有拼写错误。

Q4：如何开启日志以便查看执行的 SQL？

可以在 mybatis-config.xml 中添加日志配置：

<settings>
    <setting name="log4j" value="STDOUT_LOGGING"/>
</settings>

或者使用 SLF4J 等日志框架。

---

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

掌握了基本的 CRUD 操作之后，你可以继续深入以下几个方向：

✅ 进阶学习内容推荐：

1. 使用接口+注解代替 XML 文件
   • 更现代的编程风格
   • 更加简洁明了
2. 动态 SQL
   • 使用 <if>、<choose>、<foreach> 构建条件查询
3. 一对一、一对多查询（关联查询）
   • 如何获取多个表关联的数据
4. 分页插件 PageHelper
   • 快速实现分页功能
5. Spring Boot 整合 MyBatis
   • 构建企业级应用的基础

📌 推荐学习资源：

• MyBatis 官方文档：https://mybatis.org/mybatis-3/
• 《MyBatis从入门到精通》书籍
• B站/YouTube 上的实战教学视频（搜索“MyBatis 入门教程”）

---

总结回顾

通过本篇文章，你应该已经了解到：

• MyBatis 是什么，能用来干什么
• 如何搭建开发环境
• 什么是 SqlSession、Mapper、POJO
• 如何用 MyBatis 查询数据库中的数据
• 遇到常见问题时怎么排查
• 接下来该往哪些方向努力

掌握 MyBatis 是成为一名合格 Java 后端开发者的必经之路，希望你带着这份教程继续探索下去，构建属于你自己的 Web 应用！

---

文章字数：约3017字