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

开篇：MyBatis是什么？用来做什么？

如果你是一个刚接触后端开发的Java初学者，可能会听说过数据库操作这个词。在实际开发中，我们常常需要将Java程序中的数据保存到数据库中，或者从数据库读取数据用于展示、分析等用途。

传统的做法是使用JDBC（Java Database Connectivity）来写SQL语句并操作数据库，但这种方式非常繁琐，代码冗长且容易出错。于是，Java生态系统中出现了很多封装好的ORM框架（对象关系映射），用来简化数据库操作。

而 MyBatis 就是一种轻量级的持久层（DAO层）框架，它帮助你在Java代码和数据库之间建立桥梁，让你可以更方便地执行SQL查询、更新、插入等操作。

为什么选择 MyBatis？

• 它不是全自动ORM（不像Hibernate那样黑盒），它允许你直接写SQL，掌控力强。
• 学习成本低，适合初学者。
• 性能高，灵活性大。
• 社区活跃，资料丰富。

本教程会带你一步步了解 MyBatis 的基础知识，并通过一个小项目实践使用方法。

---

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

在正式开始前，你需要准备好以下工具：

1. Java 环境

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

java -version

如果没有安装，请前往 Oracle官网 下载安装。

2. 数据库环境

我们使用 MySQL 作为数据库示例，先下载安装 MySQL 并运行服务。

创建测试数据库和表：

登录MySQL后，执行如下语句创建一个 user 表：

CREATE DATABASE mybatis_demo;

USE mybatis_demo;

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

插入一条测试数据：

INSERT INTO user (name, age) VALUES ('Tom', 23);

3. 构建工具：Maven

我们使用 Maven 来管理项目依赖，不需要手动下载 jar 包。

安装 Maven：

mvn -v

没有的话去 Maven官网 安装。

4. IDE 推荐

建议使用 IntelliJ IDEA 或 Eclipse（IDEA体验更好）。

---

核心概念：用最简单的语言解释关键术语

学习任何技术都要了解它的基本概念。MyBatis 虽然简单，但也有一些专有名词需要理解。

1. Mapper 映射器

你可以把它看作“接口”，这个接口里声明了一些数据库操作的方法（比如根据id查用户、新增用户），然后告诉 MyBatis 这些方法应该执行哪条 SQL。

例如：

public interface UserMapper {
    User selectUserById(int id);
}

2. XML 映射文件

每个 Mapper 对应一个 XML 文件，里面写的是具体的 SQL 和结果如何映射成 Java 对象。

例如 UserMapper.xml 中可能有：

<select id="selectUserById" resultType="User">
    SELECT * FROM user WHERE id = #{id}
</select>

3. MyBatis 配置文件 mybatis-config.xml

它是整个项目的配置中心，主要配置数据库连接信息、扫描哪些包、事务管理等。

例如：

<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?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="your_password"/>
            </dataSource>
        </environment>
    </environments>
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

4. Session（SqlSession）

是 MyBatis 提供的 API，用来执行 SQL、获取 Mapper 实例的对象。

SqlSession session = sqlSessionFactory.openSession();
try {
    UserMapper mapper = session.getMapper(UserMapper.class);
    User user = mapper.selectUserById(1);
    System.out.println(user);
} finally {
    session.close();
}

---

实战项目：实现一个简单的用户管理系统

我们将做一个最基础的功能：根据用户ID查询用户信息。

第一步：创建 Maven 项目结构

打开命令行或 IDE 创建一个 Maven 项目结构如下：

src
├── main
│   ├── java
│   │   └── com.example.demo
│   │       ├── entity
│   │       │   └── User.java
│   │       ├── mapper
│   │       │   └── UserMapper.java
│   │       └── App.java
│   ├── resources
│   │   ├── mapper
│   │   │   └── UserMapper.xml
│   │   └── mybatis-config.xml

第二步：添加依赖（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.26</version>
    </dependency>
</dependencies>

第三步：定义实体类（User.java）

package com.example.demo.entity;

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

    // 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 int getAge() { return age; }
    public void setAge(int age) { this.age = age; }

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

第四步：定义 Mapper 接口（UserMapper.java）

package com.example.demo.mapper;

import com.example.demo.entity.User;

public interface UserMapper {
    User selectUserById(int id);
}

第五步：编写 XML 映射文件（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.demo.mapper.UserMapper">
    <select id="selectUserById" resultType="com.example.demo.entity.User">
        SELECT * FROM user WHERE id = #{id}
    </select>
</mapper>

第六步：配置 MyBatis（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>
    <typeAliases>
        <package name="com.example.demo.entity"/>
    </typeAliases>

    <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?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="你的密码"/>
            </dataSource>
        </environment>
    </environments>

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

第七步：编写主程序（App.java）

package com.example.demo;

import com.example.demo.entity.User;
import com.example.demo.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.IOException;
import java.io.InputStream;

public class App {
    public static void main(String[] args) {
        try {
            // 加载配置文件
            String resource = "mybatis-config.xml";
            InputStream inputStream = Resources.getResourceAsStream(resource);
            SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);

            // 获取 sqlSession
            try (SqlSession session = sqlSessionFactory.openSession()) {
                UserMapper mapper = session.getMapper(UserMapper.class);
                User user = mapper.selectUserById(1); // 查询 id 为 1 的用户
                System.out.println(user);
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

运行结果：

如果你的数据库中有 id 为 1 的用户，程序应该输出类似下面的内容：

User{id=1, name='Tom', age=23}

恭喜！你完成了第一个基于 MyBatis 的数据库操作！

---

常见问题解答

❓Q1：出现报错 “Cannot find class” 如何解决？

原因：可能是 MyBatis 找不到你的实体类路径，检查 <typeAliases> 配置是否正确。 解决方法：确认 xml 中的 <typeAliases> 指向了正确的实体包名。

❓Q2：提示 “Invalid bound statement (not found)” 是什么意思？

原因：说明你的 Mapper 接口中声明的方法没有在 XML 中找到对应的 select、insert 等标签。 解决方法：检查 XML 的 namespace 是否与接口全类名一致，以及 SQL 标签的 id 是否匹配。

❓Q3：程序运行时抛出空指针异常？

可能原因：

• 数据库查询返回 null，而你的代码没有处理 null。
• mybatis-config.xml 配置错误导致无法连接数据库。 解决方法：检查 SQL 是否正确；打印调试日志；查看数据库是否正常运行。

❓Q4：MyBatis 支持自动提交吗？

默认情况下不会自动提交事务。在进行插入、更新、删除操作时，需要调用 session.commit() 才会生效。

---

学习建议：下一步学什么？

掌握了 MyBatis 的基本用法之后，你可以继续深入学习以下几个方向：

✅1. 多种增删改操作

尝试使用 MyBatis 实现：

• 插入新用户（insert）
• 修改用户信息（update）
• 删除用户（delete）

✅2. 动态 SQL

学会使用 <if>、<choose>、<foreach> 等标签，动态生成 SQL，应对复杂查询条件。

✅3. 关联查询

掌握一对一、一对多等关联关系的数据查询，例如：

• 查询用户的同时获取他的订单列表

✅4. 与 Spring 整合

进一步学习 Spring + MyBatis 的整合方式，构建企业级应用。

---

结语

MyBatis 是一个非常适合 Java 初学者上手的 ORM 工具，它的最大特点就是“透明化”——你仍然可以自己控制 SQL，而不像某些框架那样“隐藏”细节。希望这篇教程能够帮助你顺利开启 MyBatis 的旅程！

如果你遇到任何问题，欢迎留言交流，祝你学习愉快！