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

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

在开发一个 Java Web 项目时，我们常常需要和数据库打交道。比如用户注册、商品信息管理、订单处理等。传统的 JDBC 编程虽然可以完成这些功能，但代码重复多、维护麻烦。

MyBatis 是什么？

MyBatis 是一个优秀的 持久层框架（数据库访问层框架），它简化了 Java 应用与数据库之间的交互过程。相比直接使用 JDBC，它减少了大量样板代码，又不像一些 ORM 框架那样“全自动”，所以更灵活。

你可以把它理解成一个“半自动”的工具：你告诉它要执行哪条 SQL，它负责帮你执行，并把结果转换成 Java 对象返回给你。

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

1. 准备工具

你需要以下工具：

• Java JDK 8 或以上版本
• Maven（用于依赖管理）
• IDE 推荐：IntelliJ IDEA / Eclipse
• 数据库：MySQL 5.7 或以上版本

2. 创建 Maven 项目

在 IntelliJ IDEA 中选择 “File → New → Project” 并选择 Maven 项目类型。

项目结构如下：

mybatis-demo/
├── src/
│   ├── main/
│   │   ├── java/            --> 存放 Java 类
│   │   └── resources/         --> 存放配置文件
├── pom.xml                   --> Maven 配置文件

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

点击 "Reload" 刷新项目。

4. 创建数据库表

使用 MySQL 客户端（如 Navicat、DBeaver、或命令行），创建一个测试用的数据库和表：

CREATE DATABASE my_test_db;
USE my_test_db;

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

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

到此为止，环境就准备好了！

---

核心概念讲解：几个必须掌握的概念

MyBatis 的学习重点并不在于复杂的语法，而是它的几个核心组件和流程。下面我们来通俗地解释这几个核心概念：

1. Mapper 接口 —— 就是一个接口，定义你要执行的数据库操作

你可以把它看作是你的“方法说明书”。例如：

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

2. XML 映射文件 —— 写 SQL 的地方

这个文件中写你要执行的 SQL 语句，同时也要告诉 MyBatis 如何把结果转成 Java 对象。

例如 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.mapper.UserMapper">
    <select id="selectUserById" resultType="com.example.model.User">
        SELECT * FROM users WHERE id = #{id}
    </select>
</mapper>

上面这段 XML 告诉 MyBatis 两件事：

• 当调用 selectUserById 方法时，执行对应的 SELECT 查询
• 将查询结果中的字段映射成 User 对象返回

3. Configuration 配置文件 —— 总配置中心

这个文件通常叫 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/my_test_db"/>
                <property name="username" value="root"/>
                <property name="password" value="your_password"/>
            </dataSource>
        </environment>
    </environments>
    
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

4. SqlSession —— 执行 SQL 的会话对象

这是实际运行 SQL 的入口类。我们可以这样使用它：

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

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

你可以把它想象成“数据库连接 + SQL 调度器”的合体版。

---

实战项目：从零开始完成一次数据库查询

现在我们就通过一个简单的实战项目，带你完成一次完整的数据库访问。

步骤1：创建实体类

在 src/main/java/com/example/model/ 下创建 User.java：

package com.example.model;

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

    // Getter and 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; }
}

步骤2：编写 Mapper 接口

在 src/main/java/com/example/mapper/ 目录下创建 UserMapper.java：

package com.example.mapper;

import com.example.model.User;

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

步骤3：编写 XML 映射文件

在 src/main/resources/mapper/ 目录下创建 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.mapper.UserMapper">
    <select id="selectUserById" resultType="com.example.model.User">
        SELECT * FROM users WHERE id = #{id}
    </select>
</mapper>

注意：这里的 namespace 必须和接口 UserMapper 的全限定名一致。

步骤4：配置 MyBatis 入口

确保你已经在 resources 目录下准备好 mybatis-config.xml 文件，内容之前已经展示过。

步骤5：编写主程序运行查询

在 src/main/java/com/example/ 下创建 MainApp.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.IOException;

public class MainApp {
    public static void main(String[] args) throws IOException {
        SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder()
                .build(Resources.getResourceAsStream("mybatis-config.xml"));

        try (SqlSession session = sqlSessionFactory.openSession()) {
            UserMapper mapper = session.getMapper(UserMapper.class);
            User user = mapper.selectUserById(1); // 查询 ID 为 1 的用户
            if (user != null) {
                System.out.println("姓名：" + user.getName());
                System.out.println("邮箱：" + user.getEmail());
            } else {
                System.out.println("没有找到该用户");
            }
        }
    }
}

运行这个 Java 程序，你将看到输出类似：

姓名：张三
邮箱：zhangsan@example.com

恭喜你，你已经完成了第一个 MyBatis 查询！

---

常见问题解答：新手容易遇到的坑

下面是一些初学者常见的问题及解决办法：

问题1：找不到 Mapper 文件，提示绑定异常 BindingException

原因：

• XML 文件路径不对
• XML 中 namespace 与接口不一致
• 未在 mybatis-config.xml 中正确注册 Mapper

解决方案：

• 确保 XML 文件位于 resources 下
• 检查 <mapper> 标签中 resource 路径是否正确
• 检查接口和 XML 中的 namespace 是否一致

---

问题2：SQL 语句报错，比如字段名写错

原因：

• SQL 语句本身有错误
• 数据库字段和 Java 对象属性不匹配

解决方案：

• 使用 resultMap 自定义映射关系
• 在字段名不一致的情况下使用别名 AS

例如：

SELECT id AS userId, name AS userName ...

---

问题3：数据库连接不上

可能原因：

• 驱动类没写对
• 数据库地址、用户名密码错误
• MySQL 没启动或者远程连接被拒绝

解决方案：

• 检查 mybatis-config.xml 中的数据源配置
• 确认能否通过客户端连接该数据库

---

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

你已经掌握了 MyBatis 的基本使用方式，接下来可以逐步学习以下内容：

✅ 基础提升方向：

• 插入、更新、删除操作（insert、update、delete）
• 动态 SQL（if、choose、foreach）
• resultMap 的使用（应对复杂映射）
• 多表关联查询（JOIN 查询处理）

✅ 整合 Spring Boot：

• MyBatis + Spring Boot 整合
• 使用 MyBatis-Plus 提升开发效率
• 分页插件 PageHelper 的使用

✅ 性能优化：

• 连接池的配置（推荐 HikariCP）
• 二级缓存的使用
• SQL 日志分析与慢查询优化

---

结语

本文以最简单的方式带你入门了 MyBatis 框架的核心知识。虽然 MyBatis 不像 Hibernate 那样全自动，但它提供了极高的灵活性和可控性，是目前互联网行业广泛使用的主流持久层框架之一。

希望你通过本教程，能够真正迈出学习 MyBatis 的第一步。坚持动手实践，你会发现它其实比你想象中更容易上手！

如果你在实践中遇到了任何问题，欢迎留言讨论。祝你编程之路越走越远！🎉