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

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

在开发 Java 应用程序时，我们经常需要把数据存储到数据库中。而与数据库打交道的方式有很多种，比如直接使用 JDBC（Java Database Connectivity），但这种方式编写起来较为繁琐，维护起来也不够灵活。

MyBatis 是一个轻量级的 持久层框架，它的目标是简化数据库操作、提升代码可维护性，并且保留 SQL 的灵活性。简单来说，就是让你更方便地写 SQL，同时通过映射机制自动将结果转换成 Java 对象。

MyBatis 的核心思想是：

• SQL 由开发者自己写，不强制 ORM（对象关系映射）
• 结果集可以自动映射为 Java 对象
• 支持动态 SQL
• 轻量、易集成、性能好

---

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

所需工具列表：

1. Java 开发环境（JDK 8 或以上）
2. Maven（用于项目管理和依赖引入）
3. MySQL（或其他数据库，如 H2、PostgreSQL 等）
4. IDE（推荐 IntelliJ IDEA 或 Eclipse）

第一步：安装 JDK 和配置环境变量

确保你已经安装好 Java 开发环境，并配置好了 JAVA_HOME 和 PATH 环境变量。可以通过命令行输入以下命令验证：

java -version
javac -version

如果看到版本号说明已经安装成功。

---

第二步：安装并配置 Maven

Maven 是 Java 中常用的构建和依赖管理工具。下载地址：https://maven.apache.org

解压后配置 MAVEN_HOME 并加入 PATH。验证是否安装成功：

mvn -v

---

第三步：创建 Maven 项目

你可以使用 IDE 创建一个简单的 Maven 项目，结构如下：

mybatis-demo/
├── pom.xml
└── src/
    └── main/
        ├── java/
        └── resources/

在 pom.xml 中添加 MyBatis 核心依赖和 MySQL 驱动：

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

---

第四步：准备数据库环境

这里我们以 MySQL 为例，创建一个测试数据库和表：

创建数据库：

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');

---

核心概念：什么是“持久层”？MyBatis有哪些关键概念？

为了更好地理解 MyBatis，我们先来了解几个重要概念：

---

1. 持久层（Persistence Layer）

应用程序通常分为多个层次，其中 持久层 的作用是负责与数据库交互。也就是说，所有的数据库操作（增删改查）都应该在这里完成。

在传统的做法中，我们会用 JDBC 直接连接数据库、执行 SQL、处理结果集等，非常麻烦。而 MyBatis 就是为了让这个过程变得更简单、更容易维护。

---

2. Mapper 接口

Mapper 接口相当于你的“DAO接口”，它定义了你要执行的方法名，比如 selectUserById(int id)。

示例：

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

这些方法会被 MyBatis 自动实现。

---

3. XML 映射文件

XML 文件中包含对应的 SQL 语句，并且定义如何将结果集映射成 Java 对象。例如：

<mapper namespace="com.example.mapper.UserMapper">
    <select id="selectUserById" resultType="com.example.model.User">
        SELECT * FROM user WHERE id = #{id}
    </select>
</mapper>

• namespace 对应接口的全类名
• id 对应接口中的方法名
• #{id} 是参数占位符

---

4. SqlSession

这是 MyBatis 的核心 API，用于执行 SQL、获取映射器、事务控制等。

示例：

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

---

5. Configuration 配置文件

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="123456"/>
            </dataSource>
        </environment>
    </environments>

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

---

实战项目：跟着我一步步做一个小项目！

我们来一起开发一个简单的项目：查询用户信息！

---

第一步：创建实体类 User

// 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 和 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 接口

// src/main/java/com/example/mapper/UserMapper.java
package com.example.mapper;

import com.example.model.User;

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

---

第三步：创建 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 user WHERE id = #{id}
    </select>
</mapper>

---

第四步：创建配置文件

编辑 mybatis-config.xml：

<!-- src/main/resources/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>

请替换 your_password 为你自己的数据库密码。

---

第五步：写测试类运行查询

// src/main/java/com/example/App.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;


![缓存策略对比-2](https://code-guide.oss.shanghai.autogptai.club/common/file/download?name=date2025062300/d86b36f7-627b-4700-8838-f5d5bafef702.jpg)


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

public class App {
    public static void main(String[] args) throws IOException {
        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);
            User user = mapper.selectUserById(1);
            if (user != null) {
                System.out.println("找到用户：" + user.getName());
            } else {
                System.out.println("未找到用户");
            }
        }
    }
}

运行该程序，如果数据库中有 id=1 的用户，就会输出其名字。

---

常见问题解答：新手常遇到的问题和解决办法

❓1. 为什么我运行程序时报错说找不到 mapper？

可能原因：

• XML 文件路径不对
• mybatis-config.xml 中没有正确加载该 mapper
• XML 文件中的 namespace 拼写错误
• 方法名和 XML 中的 id 不一致

解决方案：

• 检查 resources 下的 XML 是否被正确打包
• 查看 mybatis-config.xml 中 <mapper> 标签是否指向正确的资源文件
• 检查接口和 XML 的命名空间是否一致
• 查看方法名和 XML 的 id 是否匹配

---

❓2. 报错：Class not found 或者 No mapping found for SQL statement

这通常是由于：

• 类型别名未配置或未注册
• 数据库字段与 Java 属性名称不一致

解决建议：

• 在 XML 中使用 resultMap 显式映射字段
• 或者保证数据库字段名和 Java 属性名一致（例如数据库字段 user_name → Java属性 userName）

---

❓3. 数据库连接不上怎么办？

检查点：

• 数据库服务是否启动？
• IP 地址、端口号是否正确？
• 用户名和密码是否填写正确？
• URL 中是否有拼写错误？

---

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

MySQL 默认编码如果不是 UTF-8 会导致乱码，在连接字符串中加上编码参数即可：

jdbc:mysql://localhost:3306/mybatis_demo?useSSL=false&serverTimezone=UTC&characterEncoding=UTF-8

---

学习建议：下一步学习什么？怎么进阶？

恭喜你完成了第一个 MyBatis 程序！接下来你可以继续深入学习下面的内容：

✅1. 更多 CRUD 示例

• 插入数据（insert）
• 更新数据（update）
• 删除数据（delete）
• 多表关联查询
• 动态 SQL（if、choose、where、set、foreach 等标签）

✅2. 使用注解代替 XML（简洁风格）

MyBatis 也支持使用注解定义 SQL：

@Select("SELECT * FROM user WHERE id = #{id}")
User selectUserById(int id);

适用于简单的 SQL。

✅3. 结合 Spring Boot 使用

Spring Boot 提供了对 MyBatis 的自动装配支持，大大减少了配置成本。你可以使用：

• MyBatis-Spring-Boot-Starter
• PageHelper 分页插件
• MyBatis Generator 自动生成代码

✅4. 性能优化和调试技巧

• SQL 日志打印（log4j / logback）
• 数据库连接池（HikariCP）
• 缓存策略（二级缓存、Redis 缓存）

---

如果你觉得这篇文章对你有帮助，请收藏 + 点赞，我们下期继续讲《MyBatis 进阶实战》！ 🚀