MyBatis 入门详细实战教程（一）：从环境搭建到查询运行

作为 Java 后端开发必备技能，MyBatis 极大简化了 JDBC 操作，让开发者只需专注 SQL 本身。本文来讲一讲 MyBatis 入门实操全过程，包括环境搭建、配置编写、代码实现，以及实操中遇到的资源找不到、MySQL 驱动不兼容等常见问题解决方案，适合零基础快速上手。

一、MyBatis 框架概述

MyBatis 是一款优秀的基于 Java 的持久层框架，内部封装了 JDBC 繁琐的加载驱动、获取连接、创建 Statement、释放资源等操作，让开发者只需要关注 SQL 语句。

它通过 XML 或注解方式配置 SQL，利用 ORM 思想将 Java 对象与 SQL 参数自动映射，执行后将结果集封装为 Java 对象返回，大幅提升开发效率。

二、环境准备

JDK 1.8
IDEA 2025.2.1
MySQL 8.0
Maven 3.x

三、实操步骤

1. 创建数据库和测试数据

sql 复制代码

CREATE DATABASE mybatis_db;
USE mybatis_db;

CREATE TABLE `user` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `username` varchar(32) NOT NULL COMMENT '用户名称',
  `birthday` datetime DEFAULT NULL COMMENT '生日',
  `sex` char(1) DEFAULT NULL COMMENT '性别',
  `address` varchar(256) DEFAULT NULL COMMENT '地址',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

INSERT INTO `user` VALUES 
(1,'老王','2018-02-27 17:47:08','男','北京'),
(2,'熊大','2018-03-02 15:09:37','女','上海'),
(3,'熊二','2018-03-04 11:34:34','女','深圳'),
(4,'光头强','2018-03-04 12:04:06','男','广州');

2. 引入 Maven 依赖

XML 复制代码

<dependencies>
    <!-- MyBatis  -->
    <dependency>
        <groupId>org.mybatis</groupId>
        <artifactId>mybatis</artifactId>
        <version>3.4.5</version>
    </dependency>
    <!-- MySQL 8.x 驱动 -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.30</version>
    </dependency>
    <!-- JUnit 测试 -->
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.10</version>
        <scope>test</scope>
    </dependency>
    <!-- 日志 -->
    <dependency>
        <groupId>log4j</groupId>
        <artifactId>log4j</artifactId>
        <version>1.2.17</version>
    </dependency>
</dependencies>

3. 编写实体类 User

java 复制代码

package cn.tx.domain;
import java.io.Serializable;
import java.util.Date;

public class User implements Serializable {
    private Integer id;
    private String username;
    private Date birthday;
    private String sex;
    private String address;
    // getter/setter/toString
}

4. 编写 Mapper 接口

java 复制代码

package cn.tx.mapper;
import cn.tx.domain.User;
import java.util.List;

public interface UserMapper {
    List<User> findAll();
}

5. 编写 Mapper.xml 映射文件

路径：resources/mapper/UserMapper.xml

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="cn.tx.mapper.UserMapper">
    <select id="findAll" resultType="cn.tx.domain.User">
        select * from user;
    </select>
</mapper>

6. 编写 MyBatis 配置文件

路径：resources/SqlMapConfig.xml

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="mysql">
        <environment id="mysql">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="com.mysql.cj.jdbc.Driver"/>
                <property name="url" value="jdbc:mysql:///mybatis_db?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="root"/>
            </dataSource>
        </environment>
    </environments>

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

7. 编写测试类

java 复制代码

package cn.tx.test;
import cn.tx.domain.User;
import cn.tx.mapper.UserMapper;
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 org.junit.Test;
import java.io.InputStream;
import java.util.List;

public class UserTest {
    @Test
    public void testFindAll() throws Exception {
        // 1. 读取配置文件（输入流）
        InputStream in = Resources.getResourceAsStream("SqlMapConfig.xml");
        // 2. 创建 SqlSessionFactory
        SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(in);
        // 3. 获取 SqlSession
        SqlSession session = factory.openSession();
        // 4. 获取 Mapper 代理对象
        UserMapper mapper = session.getMapper(UserMapper.class);
        // 5. 执行查询
        List<User> list = mapper.findAll();
        
        for (User user : list) {
            System.out.println(user);
        }
        // 6. 释放资源
        session.close();
        in.close();
    }
}

四、知识点讲解

1. 什么是 "流（InputStream）"？

InputStream 是 Java 的输入流 ，可以理解为程序与文件之间的数据管道。MyBatis 必须通过流读取 XML 配置文件，才能解析数据库信息、加载 SQL 映射。

2. MyBatis 执行流程

读取配置 → 构建 SqlSessionFactory → 获取 SqlSession → 获取 Mapper 代理 → 执行 SQL → 封装结果 → 关闭资源

3. 增删改必须提交事务

MyBatis 默认手动提交事务，执行 insert/update/delete 后必须调用：

java 复制代码

session.commit();

否则数据只会在事务缓存中，不会真正写入数据库。

五、易错点

1：Could not find resource mapper/UserMapper.xml

原因：XML 文件路径与配置不一致 / 文件夹命名错误（mapper /mappers）
解决：保证配置文件路径与实际路径完全一致，或使用 <package name="cn.tx.mapper"/> 扫描包。

2：Client does not support authentication protocol

原因：MySQL 驱动版本过低（5.1.6）不兼容 MySQL 8.0
解决：升级驱动到 8.0+，驱动类改为 com.mysql.cj.jdbc.Driver，URL 加时区参数。

3：增删改执行成功但数据库无数据

原因：未提交事务
解决：添加 session.commit() 或使用 openSession(true) 自动提交。

六、总结

MyBatis 简化 JDBC，专注 SQL，自动完成对象映射。
流程：建库 → 导包 → 实体类 → Mapper 接口 → XML → 配置文件 → 测试。
流是读取配置的关键通道，必须正确关闭避免资源泄漏。
增删改必须提交事务，查询不需要。
常见报错多为路径、驱动版本、事务未提交导致，按对应方案即可快速解决。

本文完整覆盖 MyBatis 入门实操与排错，跟着步骤即可成功运行，为后续动态 SQL、关联查询打下基础。