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

Cloud后端

2025-06-25 06:39

阅读 679

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

你有没有想过，我们在开发一个网站或者软件的时候，如何把用户的信息保存到数据库里呢？又怎么从数据库中取出这些信息显示在网页或App上呢？

这个时候就需要一个“桥梁”，帮助我们连接Java程序和数据库之间的沟通。这个桥梁就是所谓的持久层框架，而今天我们要学的就是其中非常流行的一个——MyBatis。

简单来说：

MyBatis 是一个 Java 数据库操作框架，它帮助我们轻松地将 Java 对象与数据库表进行映射，并执行 SQL 操作。

你可以把它理解为一种让 Java 和数据库“说同一种语言”的工具。

它的优点包括：

✅ 可以直接写 SQL，灵活控制数据库
✅ 支持自动映射结果集到 Java 对象
✅ 轻量级，简单易学，适合初学者
✅ 广泛用于企业级应用开发中

二、环境准备：搭建你的 MyBatis 开发环境

在开始写代码之前，你需要准备好开发环境。下面我们会一步步搭建一个可以运行 MyBatis 的项目。

所需工具清单：

工具	版本建议	下载地址
Java JDK	1.8 或更高	Oracle JDK
Maven	最新版	Maven官网
IntelliJ IDEA（IDE）	社区版即可	JetBrains官网
MySQL（数据库）	5.7+	MySQL下载

步骤一：创建 Maven 项目

打开 IntelliJ IDEA → File → New → Project
选择 “Maven” → Next
填入 GroupId（如：com.example）→ ArtifactId（如：mybatis-demo）→ Finish

这样就创建了一个空的 Maven 项目。

步骤二：添加 MyBatis 依赖

打开 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.33</version>
    </dependency>
</dependencies>

保存后，IDEA 会自动下载所需库文件。

步骤三：安装并配置 MySQL

安装 MySQL，设置 root 用户密码。
使用 Navicat 或 MySQL Workbench 创建一个测试用的数据库，比如叫 test_db。
创建一张表，例如 user：

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

插入一条测试数据：

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

三、核心概念：让你明白 MyBatis 怎么工作

学习 MyBatis 有几个关键的概念必须掌握，下面我们一个个来讲解，尽量用最通俗的语言解释清楚。

1. SqlSession：数据库连接的“门把手”

你可以把它想象成“连接数据库的一扇门”。每次你要操作数据库，都需要通过这个门进去。

示例代码：

SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(Resources.getResourceAsStream("mybatis-config.xml"));
SqlSession session = factory.openSession();

2. Mapper 接口 + XML 映射文件：SQL 操作的“说明书”

这两个东西是 MyBatis 的灵魂所在。

Mapper 接口是一个接口（interface），用来定义一些数据库操作方法，比如查询用户。
XML 映射文件里才是真正的 SQL，它会告诉 MyBatis 这个接口对应的具体 SQL 怎么写，返回的数据该怎么处理。

举个例子：

接口 `UserMapper.java`：

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

XML 文件 `UserMapper.xml`：

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

这段代码的意思是：“当你调用 UserMapper 接口中的 selectUser 方法时，MyBatis 就去执行对应的 SQL 查询，然后把结果转换成 User 类型的对象返回。”

3. 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/test_db?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>

四、实战项目：一步一步完成一个用户查询小项目

现在我们来做个小项目：使用 MyBatis 从数据库中查询一个用户信息并打印出来。

第一步：创建实体类 `User.java`

package com.example.model;

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

    // Getter 和 Setter（省略）
    
    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", name='" + name + '\'' +
                ", email='" + email + '\'' +
                '}';
    }
}

第二步：创建 Mapper 接口 `UserMapper.java`

package com.example.mapper;

import com.example.model.User;

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

第三步：编写对应的 XML 文件 `UserMapper.xml`

放在 resources/mapper 目录下（需手动创建该目录）

<?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="selectUser" resultType="com.example.model.User">
        SELECT * FROM user WHERE id = #{id}
    </select>
</mapper>

第四步：配置文件修改（确保包含 Mapper）

确保你的 mybatis-config.xml 中有如下配置：

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

第五步：编写主程序进行测试 `TestMyBatis.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;
import java.io.InputStream;

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

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

运行程序，你应该看到类似输出：

User{id=1, name='张三', email='zhangsan@example.com'}

恭喜！你已经成功用 MyBatis 实现了第一个数据库操作！

五、常见问题：新手容易遇到的问题及解决方法

问题1：提示找不到 mapper 或 xml 文件？

✅ 解决方案：

检查你的 xml 是否放在 resources 目录下，路径是否正确。
确保 mybatis-config.xml 中 <mapper> 的 path 是否与资源位置一致。

问题2：提示 SQL 报错，比如找不到字段名？

✅ 解决方案：

检查 XML 文件中的 SQL 是否和数据库结构匹配。
如果数据库字段名和 Java 属性名不同，需要加 resultMap 或使用别名。

问题3：数据库连接失败？

✅ 解决方案：

检查 mybatis-config.xml 中的 url、用户名、密码是否正确。
检查 MySQL 服务是否启动。
注意 URL 是否加上了 ?serverTimezone=UTC 之类的参数。

问题4：使用 Maven 时报 `找不到依赖` 错误？

✅ 解决方案：

检查网络连接是否正常。
清理本地 maven 缓存：删除 ~/.m2/repository/org/mybatis/ 目录，重新 build。
查看是否拼错了 groupId 或 artifactId。

六、学习建议：接下来应该学什么？

掌握了 MyBatis 的基本使用后，下一步你可以沿着这些方向继续深入学习：

✅ 增删改操作（CRUD）

尝试写出 insertUser、updateUser、deleteUser 方法，并练习事务的使用。

✅ 注解方式的使用（替代 XML）

MyBatis 也支持用注解的方式写 SQL，比如：

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

这对于小型项目更简洁。

✅ 多表查询与 resultMap

当涉及到多个表联合查询时，需要用到 <resultMap> 来定制映射规则。

✅ 与 Spring 整合使用

大多数实际项目中，MyBatis 都是和 Spring 一起使用的。学习如何整合两者是迈向企业级开发的第一步。

✅ 动态 SQL

MyBatis 提供了非常强大的动态 SQL 功能，比如根据条件拼接查询语句，适用于复杂的业务场景。

结语：坚持练习是掌握的关键

虽然一开始会觉得 MyBatis 的配置有点麻烦，但只要你跟着教程多动手练习几次，就能逐渐熟悉它的运作机制。记住一句话：

“MyBatis 不是魔法，也不是黑盒，它是帮你写 SQL 更方便的工具。”

从今天开始，每天写一点点代码，你会发现自己进步得飞快！

如果你觉得这篇文章对你有帮助，欢迎点赞、收藏，或者分享给正在学习编程的小伙伴。

祝你学习愉快，早日成为 Java 开发高手！🚀

📌 文章字数：约 2966 字
📌 作者：一位热爱教学的后端讲师

标签:综合JavaGitHub

最热最新

暂无评论

为你推荐

暂无相关推荐

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

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

简单来说：

它的优点包括：

二、环境准备：搭建你的 MyBatis 开发环境

所需工具清单：

步骤一：创建 Maven 项目

步骤二：添加 MyBatis 依赖

步骤三：安装并配置 MySQL

三、核心概念：让你明白 MyBatis 怎么工作

1. SqlSession：数据库连接的“门把手”

2. Mapper 接口 + XML 映射文件：SQL 操作的“说明书”

接口 `UserMapper.java`：

XML 文件 `UserMapper.xml`：

3. mybatis-config.xml：配置文件，相当于“系统设置手册”

四、实战项目：一步一步完成一个用户查询小项目

第一步：创建实体类 `User.java`

第二步：创建 Mapper 接口 `UserMapper.java`

第三步：编写对应的 XML 文件 `UserMapper.xml`

第四步：配置文件修改（确保包含 Mapper）

第五步：编写主程序进行测试 `TestMyBatis.java`

五、常见问题：新手容易遇到的问题及解决方法

问题1：提示找不到 mapper 或 xml 文件？

问题2：提示 SQL 报错，比如找不到字段名？

问题3：数据库连接失败？

问题4：使用 Maven 时报 `找不到依赖` 错误？

六、学习建议：接下来应该学什么？

✅ 增删改操作（CRUD）

✅ 注解方式的使用（替代 XML）

✅ 多表查询与 resultMap

✅ 与 Spring 整合使用

✅ 动态 SQL

结语：坚持练习是掌握的关键

评论 0

为你推荐

精选内容

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

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

简单来说：

它的优点包括：

二、环境准备：搭建你的 MyBatis 开发环境

所需工具清单：

步骤一：创建 Maven 项目

步骤二：添加 MyBatis 依赖

步骤三：安装并配置 MySQL

三、核心概念：让你明白 MyBatis 怎么工作

1. SqlSession：数据库连接的“门把手”

2. Mapper 接口 + XML 映射文件：SQL 操作的“说明书”

接口 UserMapper.java：

XML 文件 UserMapper.xml：

3. mybatis-config.xml：配置文件，相当于“系统设置手册”

四、实战项目：一步一步完成一个用户查询小项目

第一步：创建实体类 User.java

第二步：创建 Mapper 接口 UserMapper.java

第三步：编写对应的 XML 文件 UserMapper.xml

第四步：配置文件修改（确保包含 Mapper）

第五步：编写主程序进行测试 TestMyBatis.java

五、常见问题：新手容易遇到的问题及解决方法

问题1：提示找不到 mapper 或 xml 文件？

问题2：提示 SQL 报错，比如找不到字段名？

问题3：数据库连接失败？

问题4：使用 Maven 时报 找不到依赖 错误？

六、学习建议：接下来应该学什么？

✅ 增删改操作（CRUD）

✅ 注解方式的使用（替代 XML）

✅ 多表查询与 resultMap

✅ 与 Spring 整合使用

✅ 动态 SQL

结语：坚持练习是掌握的关键

评论 0

为你推荐

相关推荐

精选内容

接口 `UserMapper.java`：

XML 文件 `UserMapper.xml`：

第一步：创建实体类 `User.java`

第二步：创建 Mapper 接口 `UserMapper.java`

第三步：编写对应的 XML 文件 `UserMapper.xml`

第五步：编写主程序进行测试 `TestMyBatis.java`

问题4：使用 Maven 时报 `找不到依赖` 错误？