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

创新App

2025-06-29 01:39

阅读 300

开篇：MyBatis是什么？它能帮我们做什么？

在开发 Java 后端应用时，我们经常需要将数据存储到数据库中，或者从数据库中读取数据。这个过程被称为数据库操作。传统的做法是直接使用 JDBC（Java Database Connectivity）来完成这些操作，但这种方式代码量大、重复性高，且容易出错。

这时候，我们就需要一个工具或框架来简化数据库操作——MyBatis就是这样的一种工具。

MyBatis 是什么？

MyBatis 是一个 轻量级的 Java 持久层框架，它的核心作用就是帮助我们更方便地与数据库进行交互。

它通过简单的配置和映射方式，将 Java 对象和数据库中的记录相互转换。
你可以用 SQL 来写查询语句，而不是完全由框架生成，这样灵活又可控。
它不像某些 ORM（对象关系映射）框架那样“自动化”到你不需要写 SQL，而是介于手动写 SQL 和全自动 ORM 之间的折中方案。

适合谁学？

如果你具备以下条件，这篇教程非常适合你：

熟悉 Java 基础语法
了解基本的数据库概念（如表、字段等）
想要快速上手一个实用的 Java 数据库操作工具

第一步：环境准备

在开始学习 MyBatis 之前，我们需要先准备好开发环境。下面是一步步搭建的过程：

1. 安装 JDK（Java Development Kit）

确保你已经在电脑上安装了 JDK，建议版本为 JDK 8 或以上。

验证是否安装成功：

java -version

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

2. 安装 IDE（推荐 IntelliJ IDEA）

虽然你可以用任何编辑器写 Java 代码，但为了方便调试和管理项目，我们推荐使用 IntelliJ IDEA（简称 IDEA）社区版即可。

下载地址：https://www.jetbrains.com/idea/download/

安装完成后启动 IDEA，后续我们将用它创建 MyBatis 项目。

3. 安装 Maven

Maven 是一个项目管理工具，可以帮你自动下载依赖包（比如 MyBatis 的 jar 文件），非常方便。

检查是否已安装：

mvn -v

如果提示命令不存在，请参考官方指南安装 Maven：https://maven.apache.org/install.html

4. 创建 Maven 项目

打开 IDEA → File → New → Project
选择 "Maven" → Next
输入 GroupId（通常是你的组织域名倒写，比如 com.example）和 ArtifactId（项目名，比如 mybatis-demo）
点击 Finish，会自动生成一个基础的 Maven 项目结构。

5. 引入 MyBatis 依赖

找到项目根目录下的 pom.xml 文件，在 <dependencies> 标签内添加以下内容：

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

保存后，IDEA 会自动下载相关依赖文件。

6. 安装数据库（MySQL 推荐）

我们以 MySQL 为例，你需要先安装 MySQL，并创建一个测试数据库和用户。

步骤简述：

安装 MySQL：可以从 MySQL官网下载安装
启动服务后，使用命令行或客户端连接数据库
创建数据库：

CREATE DATABASE mydb;

创建用户并授权：

CREATE USER 'test'@'localhost' IDENTIFIED BY '123456';
GRANT ALL PRIVILEGES ON mydb.* TO 'test'@'localhost';
FLUSH PRIVILEGES;

现在我们的开发环境已经准备好了！

第二步：MyBatis 的核心概念解析（通俗易懂）

接下来，我们要介绍几个 MyBatis 中非常重要的概念。虽然听起来有些专业，但我们尽量用最简单的话解释清楚它们的作用。

1. Mapper（映射器）

Mapper 就是一个接口（interface）
这个接口里的每一个方法都对应一条 SQL 查询
MyBatis 会根据接口的方法名去调用对应的 SQL

举个例子：

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

2. XML 映射文件

XML 映射文件里写的是具体的 SQL 语句。每个方法都要在这里写一个 <select> 或 <insert> 等标签。

例如：UserMapper.xml

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

注意：

namespace 要和 Mapper 接口的全类名一致
id 是接口方法的名字
resultType 表示返回的数据类型

3. MyBatis 配置文件（mybatis-config.xml）

这个文件用来告诉 MyBatis 怎么连接数据库，以及加载哪些 Mapper 文件。

基本配置如下：

<?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/mydb?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="test"/>
                <property name="password" value="123456"/>
            </dataSource>
        </environment>
    </environments>
    
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

4. SessionFactory 和 SqlSession（会话工厂和数据库连接）

这是 MyBatis 实现数据库连接的核心机制。

SqlSessionFactory 是一个工厂类，用于创建 SqlSession
SqlSession 表示一次数据库连接会话，通过它来执行 SQL、获取结果

简单使用示例：

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);
    System.out.println(user.getName());
}

第三步：动手实战：做一个简单的用户查询程序

我们现在来实现一个完整的功能：根据用户 ID 查询用户信息。

步骤一：创建实体类 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 and Setter methods
    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; }
}

步骤二：创建数据库表

进入 MySQL，创建一张用户表：

USE mydb;

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

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

步骤三：创建 Mapper 接口和 XML 文件

创建接口文件 src/main/java/com/example/mapper/UserMapper.java

package com.example.mapper;

import com.example.model.User;

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

然后创建映射文件：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 中引入这个 Mapper 文件：

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

步骤四：编写主程序测试一下

创建一个类 MyBatisTest.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.InputStream;

public class MyBatisTest {
    public static void main(String[] args) throws Exception {
        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);
            System.out.println("ID: " + user.getId());
            System.out.println("Name: " + user.getName());
            System.out.println("Email: " + user.getEmail());
        }
    }
}

运行一下这个程序，应该能看到类似这样的输出：

ID: 1
Name: 张三
Email: zhangsan@example.com

恭喜！你已经成功完成了第一个 MyBatis 示例！

第四步：新手常见问题解答（FAQ）

这里列出一些初学者最容易遇到的问题和解决办法。

Q1：找不到资源文件，报错 “Cannot find resource ...”

可能原因：

resources 目录下没有正确放置 mybatis-config.xml 或 UserMapper.xml
文件路径配置错误

解决方案：

检查 pom.xml 中是否配置了资源过滤？
确保资源文件放在 src/main/resources 目录下
使用 IDEA 查看编译后的 classes 文件夹是否包含配置文件

Q2：SQL 报错或查询不到数据

可能原因：

SQL 写错了（比如字段名拼写错误）
数据库连接参数不正确
数据库中没有相应数据

解决方案：

打印完整 SQL 看是否正确
在 MySQL 中直接执行该 SQL 测试
检查用户名、密码、数据库名是否一致

Q3：出现 NullPointerException，getMapper 返回 null

可能原因：

Mapper 接口与 XML 文件的 namespace 不一致
XML 文件没有被正确注册进 MyBatis 配置中

解决方案：

检查 XML 中的 namespace 是否与接口全类名一致
在 mybatis-config.xml 中确认 <mapper> 标签是否正确引用了该 XML 文件

Q4：MyBatis 没有日志输出，不知道哪里错了怎么办？

MyBatis 默认不会打印 SQL 语句，我们可以使用 log4j 或 slf4j 来开启日志输出。

推荐添加 log4j 依赖并在 resources 下加入 log4j.properties 配置文件。

第五步：下一步学习建议

恭喜你完成了本教程！你现在已经有能力使用 MyBatis 进行简单的数据库查询了。以下是建议继续学习的方向：

1. 学习 MyBatis 的增删改操作（Insert / Update / Delete）

除了查询，我们还需要掌握如何插入、修改、删除数据。

示例：插入一个新用户

<insert id="insertUser">
    INSERT INTO user(name, email)
    VALUES(#{name}, #{email})
</insert>

对应的接口方法：

void insertUser(User user);

记得提交事务（可以在 SqlSession 提交）。

2. 动态 SQL（if、choose、foreach 等）

MyBatis 支持强大的动态 SQL 功能，可以根据条件生成不同的查询语句。

示例：根据条件筛选用户

<select id="selectUsersByName" resultType="User">
    SELECT * FROM user
    <where>
        <if test="name != null">
            AND name LIKE CONCAT('%', #{name}, '%')
        </if>
    </where>
</select>

3. 关联查询（一对一、一对多）

当表之间有关联关系时，MyBatis 可以帮助我们自动映射复杂结构。

4. 结合 Spring Boot 使用 MyBatis（进阶方向）

学会在 Spring Boot 中整合 MyBatis 后，就可以用来构建完整的企业级应用了。

结语

本教程从零开始，带你一步步搭建起第一个 MyBatis 项目。整个过程中我们不仅学习了基础知识，还做了实际的小案例练习，也解答了新手常遇到的问题。

记住一句话：技术不是听懂的，是练出来的。

如果你跟着步骤一步一步敲完代码，并能独立运行出来，那你就已经掌握了 MyBatis 的入门技巧！

下一阶段的学习目标是深入理解和实践 MyBatis 更高级的功能，比如动态 SQL、批量操作、关联查询等。

加油！成为一名熟练的 Java 开发者，你已经迈出了第一步。

标签:SpringbootGo

最热最新

暂无评论

为你推荐

暂无相关推荐

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

开篇：MyBatis是什么？它能帮我们做什么？

第一步：环境准备

1. 安装 JDK（Java Development Kit）

2. 安装 IDE（推荐 IntelliJ IDEA）

3. 安装 Maven

4. 创建 Maven 项目

5. 引入 MyBatis 依赖

6. 安装数据库（MySQL 推荐）

步骤简述：

第二步：MyBatis 的核心概念解析（通俗易懂）

1. Mapper（映射器）

2. XML 映射文件

3. MyBatis 配置文件（mybatis-config.xml）

4. SessionFactory 和 SqlSession（会话工厂和数据库连接）

第三步：动手实战：做一个简单的用户查询程序

步骤一：创建实体类 User

步骤二：创建数据库表

步骤三：创建 Mapper 接口和 XML 文件

步骤四：编写主程序测试一下

第四步：新手常见问题解答（FAQ）

Q1：找不到资源文件，报错 “Cannot find resource ...”

Q2：SQL 报错或查询不到数据

Q3：出现 NullPointerException，getMapper 返回 null

Q4：MyBatis 没有日志输出，不知道哪里错了怎么办？

第五步：下一步学习建议

1. 学习 MyBatis 的增删改操作（Insert / Update / Delete）

2. 动态 SQL（if、choose、foreach 等）

3. 关联查询（一对一、一对多）

4. 结合 Spring Boot 使用 MyBatis（进阶方向）

推荐学习资料

结语

评论 0

为你推荐

精选内容