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

浏览器兼容师

2025-06-25 20:25

阅读 501

开篇：什么是MyBatis？为什么学习它？

在Java开发中，数据库是不可或缺的一部分。无论是网站、管理系统还是移动应用的后台服务，大多数项目都需要与数据库进行交互——比如查询用户信息、更新订单状态等操作。然而，直接使用JDBC（Java Database Connectivity）编写这些操作通常会带来代码冗长、难以维护等问题。

这时，MyBatis应运而生。它是一个轻量级的持久层框架（Persistence Framework），专注于简化对数据库的操作，同时又保持灵活性和高效性。简单来说，MyBatis可以帮助你更容易地将Java对象与数据库表关联起来，并减少手动编写SQL的复杂度。

为什么选择MyBatis呢？

轻量灵活：不像一些复杂的ORM（对象关系映射）工具，MyBatis不会隐藏SQL的细节，而是让你能更精细地控制SQL语句。
易于学习：如果你已经熟悉SQL语言，那么学习MyBatis将会非常轻松。
高效稳定：广泛应用于企业级项目，性能可靠，社区活跃。

接下来，我们将一步步带你走进MyBatis的世界，从环境搭建开始，再到核心概念的理解与实践，最终完成一个简单的项目。

环境准备：搭建开发环境

要开始使用MyBatis，你需要准备以下几个基本开发环境：

1. Java运行环境

确保你的电脑上安装了Java JDK 8或更高版本。你可以通过命令行输入以下命令来检查是否已安装并配置好Java环境：

java -version

如果未安装，请前往Oracle官网下载对应的JDK。

2. MySQL数据库

MyBatis主要用来操作数据库，本教程将使用MySQL作为示例数据库。请前往MySQL官网下载并安装适合你系统的MySQL Server，安装完成后可以使用如下命令启动MySQL服务（以Windows系统为例）：

net start mysql

然后，使用如下命令登录MySQL：

mysql -u root -p

在MySQL客户端执行以下SQL语句，创建测试数据库和数据表：

-- 创建测试数据库
CREATE DATABASE mybatis_demo;

-- 使用该数据库
USE mybatis_demo;

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

-- 插入一条测试数据
INSERT INTO user (name, email) VALUES ('张三', 'zhangsan@example.com');

3. IDE开发工具

推荐使用IntelliJ IDEA或Eclipse作为开发工具。两者都支持良好的Java开发体验，本文将以IntelliJ IDEA为例进行说明。

4. 构建工具Maven

为了让依赖管理更方便，我们使用Maven构建项目。请确保你已经安装Maven，并在IDEA中正确配置。如果你还不熟悉Maven，可以通过如下方式快速安装：

下载Maven：Apache Maven Download
解压后配置环境变量 MAVEN_HOME 和 PATH，然后在命令行执行：

mvn -v

确认输出类似如下信息表示Maven安装成功：

Apache Maven 3.8.x ...

5. 导入MyBatis依赖

在使用MyBatis之前，需要将其添加到Maven项目的依赖中。打开项目的 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.30</version>
    </dependency>
</dependencies>

确保上述依赖添加后，Maven会自动下载相关jar包。

到这里，我们的开发环境就搭建完成了！下一步我们将介绍MyBatis的核心概念，帮助你理解它的基本工作机制。

核心概念：MyBatis中的几个重要组件

现在你已经搭建好了MyBatis的基础环境，接下来我们将逐步介绍MyBatis中最关键的几个概念，帮助你建立起对这个框架的基本认识。为了便于理解，我们会用通俗的语言解释每一个概念，并配上具体的代码示例，帮助你更好地掌握它们的作用和使用方法。

1. Mapper接口

Mapper接口是MyBatis中用于定义数据库操作的接口。你可以把它理解成“任务清单”——接口中的每一个方法，代表一次数据库操作，例如查询数据、插入数据等。

例如，我们可以定义一个 UserMapper 接口：

package com.example.mapper;

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

public interface UserMapper {
    List<User> getAllUsers(); // 查询所有用户
    User getUserById(int id);  // 根据ID获取用户
    void insertUser(User user); // 插入新用户
}

接口中的每个方法都没有具体的实现逻辑，而是通过MyBatis动态生成相应的SQL操作。这些方法会与XML配置文件或者注解进行绑定，从而告诉MyBatis该如何执行这些操作。

2. XML映射文件

XML映射文件是MyBatis中用来描述SQL语句以及如何将结果集映射到Java对象的地方。它就像是“说明书”，告诉程序该做什么，怎么做。

例如，我们可以创建一个名为 UserMapper.xml 的文件，其中包含SQL语句的具体实现：

<?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.model.User">
        SELECT * FROM user
    </select>

    <!-- 根据ID查询用户 -->
    <select id="getUserById" parameterType="int" resultType="com.example.model.User">
        SELECT * FROM user WHERE id = #{id}
    </select>

    <!-- 插入用户 -->
    <insert id="insertUser" parameterType="com.example.model.User">
        INSERT INTO user (name, email)
        VALUES (#{name}, #{email})
    </insert>

</mapper>

可以看到，UserMapper.xml 文件的 <mapper> 元素中的 namespace 属性与前面提到的 UserMapper 接口完全对应，这确保了MyBatis能够找到接口对应的实际SQL操作。

需要注意的是：

resultType 定义了查询返回的数据类型（这里是 User 类）。
parameterType 表示传入的参数类型（例如整数或Java对象）。
#{} 是占位符语法，避免SQL注入攻击，并传递动态参数。

3. 配置类

MyBatis的配置类通常是 mybatis-config.xml 文件，这是MyBatis全局配置的核心文件，负责设置数据库连接池、事务管理器等基本信息。

以下是一个最基础的配置示例：

<?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?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>

这里的关键配置项包括：

environment：数据库环境的配置，指定了使用哪个数据库（开发环境或生产环境）、采用何种事务管理机制以及连接数据库所需的信息（如驱动、URL、用户名和密码）。
dataSource：数据源的配置。在这个例子中，我们使用了内置的 POOLED 连接池，也可以替换成外部连接池（例如Druid或HikariCP）。
mappers：指定映射文件的位置，告诉MyBatis去哪里寻找SQL操作的具体定义。

4. 工具类SqlSessionFactory

SqlSessionFactory 是MyBatis用来创建数据库会话（Session）的工厂类。它相当于一个“生产线”，根据配置创建出可以访问数据库的对象。

我们可以通过读取 mybatis-config.xml 文件初始化它：

package com.example.util;

import org.apache.ibatis.io.Resources;
import org.apache.ibatis.session.SqlSessionFactory;
import org.apache.ibatis.session.SqlSessionFactoryBuilder;

import java.io.IOException;
import java.io.InputStream;

public class MyBatisUtil {
    private static SqlSessionFactory sqlSessionFactory;

    static {
        try {
            String resource = "mybatis-config.xml";
            InputStream inputStream = Resources.getResourceAsStream(resource);
            sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    public static SqlSessionFactory getSqlSessionFactory() {
        return sqlSessionFactory;
    }
}

这段代码会在静态块中加载配置文件，生成 SqlSessionFactory 实例，供后续使用。

5. 执行数据库操作的SqlSession

SqlSession 是真正的数据库会话对象，它提供了一套API用于调用Mapper接口的方法，从而执行SQL操作。

例如，下面是调用 UserMapper 接口中方法的完整过程：

package com.example.test;

import com.example.mapper.UserMapper;
import com.example.model.User;
import com.example.util.MyBatisUtil;
import org.apache.ibatis.session.SqlSession;

import java.util.List;

public class MainApp {
    public static void main(String[] args) {
        // 获取SqlSession
        try (SqlSession session = MyBatisUtil.getSqlSessionFactory().openSession()) {

            // 获取Mapper接口的实现类
            UserMapper userMapper = session.getMapper(UserMapper.class);

            // 调用接口方法执行SQL操作

            // 插入用户
            User newUser = new User();
            newUser.setName("李四");
            newUser.setEmail("lisi@example.com");
            userMapper.insertUser(newUser);
            session.commit(); // 提交事务

            // 查询所有用户
            List<User> users = userMapper.getAllUsers();
            for (User user : users) {
                System.out.println(user.getName());
            }
        }
    }
}

这段代码中展示了如何利用 SqlSession 调用 UserMapper 接口，并通过调用其方法执行数据库插入和查询操作。

通过上述内容，你应该对MyBatis的核心概念有了初步了解。接下来，我们将进一步通过实战项目深入学习MyBatis的应用。

实战项目：使用MyBatis做一个简单的增删改查功能

现在你已经掌握了MyBatis的基本概念，接下来我们通过一个完整的例子来实践如何使用MyBatis完成常见的数据库操作。我们的目标是实现一个管理用户的简单系统，包括添加用户、查询用户、修改用户和删除用户四个功能。

步骤一：创建实体类（Java模型类）

首先，我们需要一个Java类来表示数据库中的用户数据。这个类通常被称为“实体类”（Entity Class）或“模型类”（Model Class）。

package com.example.model;

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;
    }
}

步骤二：定义Mapper接口

接下来，我们需要一个接口来声明数据库操作，即Mapper接口。我们已经在前面介绍了它的作用，现在我们继续完善它，增加更新和删除的方法。

package com.example.mapper;

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

public interface UserMapper {
    List<User> getAllUsers();          // 查询所有用户
    User getUserById(int id);          // 根据ID查询用户
    void insertUser(User user);        // 添加用户
    void updateUser(User user);        // 修改用户
    void deleteUser(int id);           // 删除用户
}

步骤三：编写XML映射文件

在 resources/mapper/UserMapper.xml 中定义相应的SQL语句：

<?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.model.User">
        SELECT * FROM user
    </select>

    <!-- 根据ID查询用户 -->
    <select id="getUserById" parameterType="int" resultType="com.example.model.User">
        SELECT * FROM user WHERE id = #{id}
    </select>

    <!-- 添加用户 -->
    <insert id="insertUser" parameterType="com.example.model.User">
        INSERT INTO user (name, email)
        VALUES (#{name}, #{email})
    </insert>

    <!-- 修改用户 -->
    <update id="updateUser" parameterType="com.example.model.User">
        UPDATE user
        SET name = #{name}, email = #{email}
        WHERE id = #{id}
    </update>

    <!-- 删除用户 -->
    <delete id="deleteUser" parameterType="int">
        DELETE FROM user WHERE id = #{id}
    </delete>

</mapper>

步骤四：编写主程序执行CRUD操作

最后，我们在 MainApp.java 中编写代码，测试增删改查功能：

package com.example.test;

import com.example.mapper.UserMapper;
import com.example.model.User;
import com.example.util.MyBatisUtil;
import org.apache.ibatis.session.SqlSession;

import java.util.List;

public class MainApp {
    public static void main(String[] args) {
        try (SqlSession session = MyBatisUtil.getSqlSessionFactory().openSession()) {
            UserMapper userMapper = session.getMapper(UserMapper.class);

            // 插入用户
            User user = new User();
            user.setName("王五");
            user.setEmail("wangwu@example.com");
            userMapper.insertUser(user);
            session.commit(); // 提交事务

            // 查询所有用户
            System.out.println("当前所有用户：");
            List<User> users = userMapper.getAllUsers();
            for (User u : users) {
                System.out.println(u.getId() + ": " + u.getName());
            }

            // 修改用户（假设ID为1）
            user.setId(1);
            user.setName("赵六");
            user.setEmail("zhaoliu@example.com");
            userMapper.updateUser(user);
            session.commit();

            // 删除用户（假设ID为2）
            userMapper.deleteUser(2);
            session.commit();

            // 查询更新后的用户列表
            System.out.println("更新后的用户列表：");
            users = userMapper.getAllUsers();
            for (User u : users) {
                System.out.println(u.getId() + ": " + u.getName());
            }
        }
    }
}

以上代码演示了完整的增删改查流程。运行程序后，你会看到控制台输出新增、修改、删除后的用户信息，表明数据库操作已经成功执行。

通过这个实战项目，你应该已经能够独立使用MyBatis来开发一个简单的数据库应用程序。接下来，我们将解答一些新手在学习过程中常遇到的问题，帮助你更顺利地迈过可能遇到的障碍。

常见问题：初学者容易遇到的错误及解决办法

在使用MyBatis的过程中，新手经常会遇到各种各样的问题，有些是因为配置不当，有些则源于对原理理解不透彻。下面列出了一些最常见的问题及其解决方案，帮助你在实践中少走弯路。

问题1：NoClassDefFoundError 或 ClassNotFoundException

原因分析：此类异常通常发生在依赖未正确引入或版本冲突时。例如，MyBatis核心包或MySQL驱动没有被正确引入项目中。

解决方案：

检查 pom.xml 中是否包含正确的MyBatis和MySQL依赖，例如：

<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.30</version>
</dependency>

确保Maven下载依赖成功，必要时可以删除本地仓库缓存重新下载。

问题2：找不到Mapper接口或XML文件

原因分析：当MyBatis无法找到对应的Mapper接口或XML文件时，会导致程序运行时报错，例如 BindingException 或 Invalid bound statement。