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

奇妙先知

2025-06-27 22:38

阅读 319

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

在我们开始写代码之前，先来聊聊什么是 MyBatis。

简单来说，MyBatis 是一个用于简化 Java 操作数据库的框架。你可以把它想象成“数据库与 Java 之间的翻译官”。如果你用原始的 JDBC 来操作数据库，会非常繁琐（比如要反复写 Connection、Statement、ResultSet 等），而 MyBatis 就能让你用更简洁的方式去完成这些工作。

MyBatis 的特点：

轻量级：没有 Spring 那么复杂，适合中小型项目
灵活性强：你仍然可以写原生 SQL，控制每一步操作
性能高：因为不自动封装复杂的逻辑，运行效率更高
支持映射配置：可以把数据库的结果直接映射到 Java 对象中

一句话总结：MyBatis 让你像操作 Java 对象一样操作数据库数据。

环境准备：从零搭建开发环境

我们要做的第一步是准备好开发环境，让 MyBatis 能顺利跑起来。下面是一步步的操作指南，适用于完全的新手朋友。

✅ 建议使用 IntelliJ IDEA（简称 IDEA）作为开发工具，它是目前最流行、功能最强的 Java IDE之一。

步骤一：安装 JDK

MyBatis 运行需要 Java 环境。确保你的电脑上已经安装了 JDK 1.8 或以上版本。你可以通过命令行检查：

java -version

如果看到类似以下输出，则说明已安装成功：

java version "17.0.3" 2022-04-19 LTS
Java(TM) SE Runtime Environment ...

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

步骤二：安装 IDE（推荐 IntelliJ IDEA）

前往 https://www.jetbrains.com/idea/ 下载社区版（Community Edition）即可免费使用。

安装完成后打开 IDE，创建一个新项目：

File -> New -> Project
选择 Maven 项目
勾选 “Create from archetype”
选择 maven-archetype-quickstart
输入 GroupId（如 com.example）、ArtifactId（如 mybatis-demo）
点击下一步完成创建

步骤三：添加 MyBatis 和 MySQL 依赖

打开项目的 pom.xml 文件，在 <dependencies> 标签中添加如下内容：

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

然后点击右上角提示“Import Changes”，等待依赖加载完毕。

步骤四：准备数据库和表

假设我们要做一个“用户信息管理系统”，需要一张用户表。这里我们以 MySQL 数据库为例。

创建数据库和表

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 ('张三', 25);

这样我们就有了一个简单的用户表，接下来就可以在 Java 中读取它了！

核心概念：MyBatis 的关键术语和它们的作用

学习任何新技术都绕不开它的核心概念，但别担心，我们用最直白的语言来解释：

1. SqlSessionFactoryBuilder

相当于一个工厂“建造者”，负责创建工厂(SqlSessionFactory)。通常只在程序启动时使用一次。

2. SqlSessionFactory

这是一个“工厂对象”，用来生产 SqlSession（数据库连接会话）。一般在整个应用生命周期中也只会初始化一次。

3. SqlSession

这就是我们跟数据库“对话”的对象，可以执行 SQL 查询、增删改等操作。

4. Mapper 接口 + XML 映射文件

这是我们最常用的方式：

Mapper 接口：定义方法名，例如 User getUserById(int id)
XML 映射文件：编写对应的 SQL，并告诉 MyBatis 如何把结果转换成 Java 对象

实战项目：完成第一个 MyBatis 小程序

现在我们来实践一下，做一个最简单的例子：根据用户 ID 查找用户信息。

第一步：创建 User 类

这个类就是用来保存数据库中的用户记录的实体类。

// src/main/java/com/example/model/User.java
package com.example.model;

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

    // Getter 和 Setter 方法必须有！否则 MyBatis 不知道怎么赋值
    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 接口

接口中定义我们将要用的方法：

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

import com.example.model.User;

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

第三步：创建 MyBatis 配置文件

在 resources 目录下新建 mybatis-config.xml：

<!-- resources/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/mybatis_demo?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="your_password"/>
            </dataSource>
        </environment>
    </environments>

    <!-- 注册我们的 mapper 接口 -->
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

请将上面的用户名和密码替换为你自己数据库的设置。

第四步：创建 XML 映射文件

在 resources 目录下新建文件夹 mapper，并在里面创建 UserMapper.xml：

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

    <!-- 从数据库查出用户的 SQL -->
    <select id="getUserById" resultType="com.example.model.User">
        SELECT * FROM user WHERE id = #{id}
    </select>
</mapper>

解释一下：

namespace：对应 Mapper 接口的全限定类名
id：对应接口中的方法名
resultType：查询结果应该转成哪种 Java 类型（这里是 User 类）
#{id}：这是 MyBatis 的参数占位符，安全防止 SQL 注入

第五步：编写主程序调用 MyBatis

// 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;
import java.io.InputStream;

public class MainApp {
    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()) {
                // 获取 Mapper 对象
                UserMapper mapper = session.getMapper(UserMapper.class);

                // 调用方法
                User user = mapper.getUserById(1);
                System.out.println("查询结果：" + user);
            }

        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

第六步：运行程序并查看结果

点击 Run 或使用命令运行，你应该看到类似以下输出：

查询结果：User{id=1, name='张三', age=25}

✅ 成功啦！你已经用 MyBatis 从数据库中查出了第一条数据！

常见问题解答（FAQ）

很多初学者在刚开始使用 MyBatis 时会遇到一些常见问题，下面我们列出几个典型问题及其解决办法：

1. 报错：`Cannot find class User`

可能原因：

包路径不正确
没有编译或刷新项目

✅ 解决方案：

确认类文件的位置是否正确（包结构对不对）
IDEA 中尝试 Build -> Rebuild Project

2. 报错：`Invalid bound statement (not found): com.example.mapper.UserMapper.getUserById`

可能原因：

XML 文件没有被正确注册进 MyBatis
namespace 或 id 名称不一致

✅ 解决方案：

检查 XML 文件的 namespace 是否和接口全限定名一致
检查 <select> 标签的 id 是否和接口方法名一致
检查 mybatis-config.xml 中是否包含了该 XML 文件

3. 连接不上数据库

可能原因：

数据库服务没启动
用户名密码错误
URL 地址拼写错误（如端口号不是3306）

✅ 解决方案：

使用 Navicat 或 MySQL 客户端测试数据库连接
重新检查配置文件中的账号密码、URL 和驱动是否匹配当前数据库版本

4. 查询返回 null，明明数据存在

可能原因：

表字段名和类属性名不一致（如数据库列叫 username，Java 属性叫 name）
没有 getter/setter 方法

✅ 解决方案：

确保表字段名和类的属性名一致，或者在 XML 中使用别名映射
确保类中有正确的 Getter 和 Setter 方法

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

恭喜你完成了 MyBatis 的入门教程！接下来你可以尝试扩展以下方向，继续深入学习 MyBatis：

✅ 进阶学习路线建议：

方向	内容	建议
增删改功能实现	实现 insert、update、delete 操作	在实战中掌握基本 CRUD 操作
动态 SQL	if、choose、foreach 等高级查询技巧	应对复杂的条件查询场景
注解方式使用 MyBatis	使用 @Select、@Insert 等注解代替 XML	提升代码简洁性
多表联查	查询多个关联表的数据并封装为对象	更贴近实际业务需求
事务管理	控制多条 SQL 的一致性	保证数据准确性
整合 Spring Boot	将 MyBatis 与 Spring Boot 结合使用	构建完整的企业级项目

📚 推荐阅读资料：

官方文档：https://mybatis.org/mybatis-3/zh/index.html
书籍：《MyBatis从入门到精通》

总结

本篇教程从 MyBatis 的基本介绍、环境搭建、核心概念、实战项目和常见问题 全面覆盖了一个新手的学习路径。希望通过这篇“手把手教学式”的教程，你能快速入门 MyBatis 并感受到它带来的便捷与强大。

记住一句话：“学会写 SQL 是基础，掌握 MyBatis 是进阶。”

现在你已经迈出了第一步，接下来只需要不断练习项目，就能越来越熟练地驾驭这个强大的框架！

如果你觉得这篇文章对你有帮助，欢迎点赞、收藏，也可以留言交流学习心得 😊

标签:运营代码人生书籍

最热最新

暂无评论

为你推荐

暂无相关推荐

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

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

MyBatis 的特点：

环境准备：从零搭建开发环境

步骤一：安装 JDK

步骤二：安装 IDE（推荐 IntelliJ IDEA）

步骤三：添加 MyBatis 和 MySQL 依赖

步骤四：准备数据库和表

创建数据库和表

核心概念：MyBatis 的关键术语和它们的作用

1. SqlSessionFactoryBuilder

2. SqlSessionFactory

3. SqlSession

4. Mapper 接口 + XML 映射文件

实战项目：完成第一个 MyBatis 小程序

第一步：创建 User 类

第二步：创建 Mapper 接口

第三步：创建 MyBatis 配置文件

第四步：创建 XML 映射文件

第五步：编写主程序调用 MyBatis

第六步：运行程序并查看结果

常见问题解答（FAQ）

1. 报错：`Cannot find class User`

2. 报错：`Invalid bound statement (not found): com.example.mapper.UserMapper.getUserById`

3. 连接不上数据库

4. 查询返回 null，明明数据存在

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

✅ 进阶学习路线建议：

总结

评论 0

为你推荐

精选内容

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

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

MyBatis 的特点：

环境准备：从零搭建开发环境

步骤一：安装 JDK

步骤二：安装 IDE（推荐 IntelliJ IDEA）

步骤三：添加 MyBatis 和 MySQL 依赖

步骤四：准备数据库和表

创建数据库和表

核心概念：MyBatis 的关键术语和它们的作用

1. SqlSessionFactoryBuilder

2. SqlSessionFactory

3. SqlSession

4. Mapper 接口 + XML 映射文件

实战项目：完成第一个 MyBatis 小程序

第一步：创建 User 类

第二步：创建 Mapper 接口

第三步：创建 MyBatis 配置文件

第四步：创建 XML 映射文件

第五步：编写主程序调用 MyBatis

第六步：运行程序并查看结果

常见问题解答（FAQ）

1. 报错：Cannot find class User

2. 报错：Invalid bound statement (not found): com.example.mapper.UserMapper.getUserById

3. 连接不上数据库

4. 查询返回 null，明明数据存在

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

✅ 进阶学习路线建议：

总结

评论 0

为你推荐

相关推荐

精选内容

1. 报错：`Cannot find class User`

2. 报错：`Invalid bound statement (not found): com.example.mapper.UserMapper.getUserById`