MyBatis 从入门到精通（第一篇）—— 框架基础与环境搭建

作为 Java 开发者，数据持久化是核心需求之一，但繁琐的 JDBC 代码常常让我们陷入 "重复劳动" 的困境。MyBatis 作为轻量级持久层框架，既保留了 SQL 的灵活性，又简化了数据映射与连接管理。本系列博客将分三篇，从基础到进阶，带大家系统掌握 MyBatis------ 第一篇聚焦 "框架概念" 与 "环境搭建"，帮你迈出 MyBatis 学习的第一步。

一、先搞懂：什么是框架？为什么要学框架？

[1.1 框架的本质："半成品" 的便利](#1.1 框架的本质：“半成品” 的便利)

[1.2 使用框架的 3 个核心好处](#1.2 使用框架的 3 个核心好处)

[1.3 框架的适用场景：并非所有项目都需要](#1.3 框架的适用场景：并非所有项目都需要)

[二、MyBatis 初认识：从历史到核心定位](#二、MyBatis 初认识：从历史到核心定位)

[2.1 MyBatis 的 "前世今生"](#2.1 MyBatis 的 “前世今生”)

[2.2 核心定位：半自动化 ORM 框架](#2.2 核心定位：半自动化 ORM 框架)

[2.3 对比 JDBC：MyBatis 到底简化了什么？](#2.3 对比 JDBC：MyBatis 到底简化了什么？)

[三、动手实战：MyBatis 环境搭建（两种方式）](#三、动手实战：MyBatis 环境搭建（两种方式）)

[3.1 方式一：普通 Java 项目搭建（入门级）](#3.1 方式一：普通 Java 项目搭建（入门级）)

[步骤 1：创建项目结构](#步骤 1：创建项目结构)

[步骤 2：导入依赖 jar 包](#步骤 2：导入依赖 jar 包)

[步骤 3：创建实体类（以 Dept 为例）](#步骤 3：创建实体类（以 Dept 为例）)

[步骤 4：编写全局配置文件（SqlMapConfig.xml）](#步骤 4：编写全局配置文件（SqlMapConfig.xml）)

[步骤 5：编写 Mapper 映射文件（DeptMapper.xml）](#步骤 5：编写 Mapper 映射文件（DeptMapper.xml）)

[步骤 6：编写测试类（MyTest.java）](#步骤 6：编写测试类（MyTest.java）)

[步骤 7：添加日志配置（可选，推荐）](#步骤 7：添加日志配置（可选，推荐）)

[3.2 方式二：Maven 项目搭建（企业实战级）](#3.2 方式二：Maven 项目搭建（企业实战级）)

[步骤 1：创建 Maven 项目结构](#步骤 1：创建 Maven 项目结构)

[步骤 2：配置 pom.xml（核心依赖）](#步骤 2：配置 pom.xml（核心依赖）)

[步骤 3：重复普通项目的核心文件](#步骤 3：重复普通项目的核心文件)

[步骤 4：编写测试类（JUnit 测试）](#步骤 4：编写测试类（JUnit 测试）)

四、总结与下一步

一、先搞懂：什么是框架？为什么要学框架？

在深入 MyBatis 之前，我们需要先理解 "框架" 的本质 ------ 它不是高深的新技术，而是 "前人经验的封装"，帮我们解决通用问题，专注核心业务。

1.1 框架的本质："半成品" 的便利

举个生活中的例子：用 PowerPoint 制作专业 PPT 时，我们很少从零开始设计排版，而是直接使用模板 ------ 模板已经搭好了 "架子"（布局、字体、配色），我们只需填充内容。

框架的逻辑与此一致：它是一个 "预定义公共结构的半成品"，提前解决了项目中的通用问题（如 JDBC 的驱动加载、连接关闭、事务控制），我们只需在这个 "架子" 里编写业务相关的代码（如查询用户、新增订单）。

1.2 使用框架的 3 个核心好处

提升效率，减少重复劳动：无需手动编写公共代码（如 JDBC 中每次都要写的加载驱动、关闭连接），专注业务逻辑，缩短开发周期；
统一规范，降低维护成本：避免 "一千个开发者写一千种代码" 的混乱，团队协作时新人上手更快，后续维护更轻松；
稳定可靠，集成最佳实践：框架整合了大量前人的经验，生成的代码比手写更稳定、性能更优（如 MyBatis 的连接池、缓存机制）。

1.3 框架的适用场景：并非所有项目都需要

框架虽好，但并非 "万能"。如果是小型工具（如单文件数据查询脚本），框架的维护成本（人力、财力）可能超过收益；中大型项目、需要长期维护的系统，框架的优势才会凸显 ------MyBatis 正是为这类项目的 "数据持久化" 需求设计的。

二、MyBatis 初认识：从历史到核心定位

2.1 MyBatis 的 "前世今生"

MyBatis 并非凭空出现，它的发展历程反映了持久层框架的演进：

2001 年：项目诞生，名为iBatis，是 Apache 的开源项目；
2010 年：从 Apache 迁移到 Google Code，正式改名为MyBatis；
2013 年：迁移到 GitHub，逐渐成为 Java 领域最流行的持久层框架之一。

2.2 核心定位：半自动化 ORM 框架

要理解 MyBatis，首先要明确两个关键概念：

ORM（Object-Relational Mapping）：对象关系映射，是一种数据持久化技术。它将 Java 实体类（Object）与数据库表（Relation）通过 "映射规则" 关联，避免手动将 ResultSet 结果转换为实体类对象；
半自动化：需要手动编写 SQL 语句；而 "全自动化框架"（如 Hibernate）无需写 SQL，直接操作实体类即可完成数据库操作。

为什么 MyBatis 选择 "半自动化"？

全自动化框架在多表关联、分页查询、复杂 SQL场景下，灵活性差且性能难优化；而 MyBatis 允许手写 SQL，既能通过 ORM 简化数据映射，又能灵活控制 SQL 逻辑，完美平衡 "效率" 与 "灵活"。

2.3 对比 JDBC：MyBatis 到底简化了什么？

我们以 "根据用户名查询用户信息" 为例，直观对比 JDBC 与 MyBatis 的差异，感受 MyBatis 的优势：

实现方式	核心步骤	痛点 / 优势
JDBC	1. 加载驱动→2. 创建连接→3. 声明 SQL→4. 预编译 SQL→5. 设置参数→6. 执行查询→7. 处理结果→8. 关闭资源	1. 代码冗余（除 SQL 和结果处理，其余步骤重复）；2.SQL 硬编码在 Java 中，修改需改代码
MyBatis	1. 配置 Mapper.xml（写 SQL）→2.Java 代码调用接口	1. 省去 90% 重复代码；2.SQL 与 Java 解耦，维护方便；3. 自动映射参数与结果

JDBC 代码示例（繁琐的重复步骤）：

复制代码

// 1.加载驱动
Class.forName("com.mysql.jdbc.Driver");
// 2.创建连接
String url = "jdbc:mysql://localhost:3306/test";
Connection connection = DriverManager.getConnection(url, "root", "root");
// 3.声明SQL
String sql = "SELECT * FROM userinfo where username= ? ";
// 4.预编译SQL
PreparedStatement statement = connection.prepareStatement(sql);
// 5.设置参数
statement.setString(1, "王五");
// 6.执行查询
ResultSet rs = statement.executeQuery();
// 7.处理结果
while (rs.next()) {
    System.out.println(rs.getString("id")+rs.getString("username")); 
}
// 8.关闭资源
rs.close();
statement.close();
connection.close();

可以看到，除了 "声明 SQL" 和 "处理结果"，其余 6 个步骤都是重复劳动。

MyBatis 代码示例 （简洁高效）：

只需在 Mapper.xml 中配置 SQL：

复制代码

<mapper namespace="test"> 
    <select id="findUserByName" resultType="com.jr.pojo.User"> 
        SELECT * FROM USERINFO WHERE username LIKE #{value}%
    </select>
</mapper>

Java 代码只需调用接口，无需关心连接、关闭等细节。

结论：MyBatis 彻底解决了 JDBC 的 "代码冗余" 和 "SQL 硬编码" 问题，让开发者专注于 SQL 逻辑与业务实现。

三、动手实战：MyBatis 环境搭建（两种方式）

环境搭建是学习框架的第一步，我们分别讲解 "普通 Java 项目" 和 "Maven 项目" 两种方式 ------ 前者适合入门理解，后者是企业开发的标准方式。

3.1 方式一：普通 Java 项目搭建（入门级）

步骤 1：创建项目结构

新建 Java 项目，目录结构如下（清晰划分代码、配置文件位置）：

复制代码

mybatis-demo/
├─ src/
│  ├─ com/jr/pojo/       # 实体类（如Dept、User）
│  │  └─ Dept.java
│  ├─ com/jr/test/       # 测试类
│  │  └─ MyTest.java
│  ├─ com/jr/mapper/     # Mapper映射文件（写SQL）
│  │  └─ DeptMapper.xml
│  ├─ SqlMapConfig.xml   # MyBatis全局配置文件
│  └─ log4j.properties   # 日志配置（可选，查看SQL执行过程）
└─ lib/                  # 依赖jar包
   ├─ mybatis-3.4.4.jar  # MyBatis核心包
   ├─ mysql-connector-java-8.0.11.jar  # MySQL驱动
   └─ log4j-1.2.17.jar   # 日志包

步骤 2：导入依赖 jar 包

将上述 jar 包复制到lib目录，右键 "Add as Library"，确保 IDE 能识别这些依赖。

步骤 3：创建实体类（以 Dept 为例）

实体类属性需与数据库表字段对应，提供 getter/setter、构造方法和 toString ()：

复制代码

public class Dept {
    private int deptno;    // 部门编号（对应数据库dept表的deptno字段）
    private String dname;  // 部门名称（对应dname字段）
    private String loc;    // 部门地址（对应loc字段）

    // 无参构造
    public Dept() {}

    // 有参构造
    public Dept(int deptno, String dname, String loc) {
        this.deptno = deptno;
        this.dname = dname;
        this.loc = loc;
    }

    // getter/setter（省略，实际开发需手动编写或用Lombok简化）
    @Override
    public String toString() {
        return "Dept{" +
                "deptno=" + deptno +
                ", dname='" + dname + '\'' +
                ", loc='" + loc + '\'' +
                '}';
    }
}

步骤 4：编写全局配置文件（SqlMapConfig.xml）

这是 MyBatis 的 "全局控制中心"，核心配置数据源、环境、映射文件路径：

复制代码

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
        PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
        "https://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
    <!-- 配置数据源环境（开发环境） -->
    <environments default="development">
        <environment id="development">
            <!-- 事务管理器：JDBC（依赖数据源连接控制事务） -->
            <transactionManager type="JDBC"/>
            <!-- 数据源：POOLED（连接池，开发/测试常用，提升性能） -->
            <dataSource type="POOLED">
                <property name="driver" value="com.mysql.cj.jdbc.Driver"/> <!-- MySQL8.0+驱动 -->
                <property name="url" value="jdbc:mysql://localhost:3306/mytestdb?serverTimezone=GMT&amp;useSSL=false"/> <!-- 数据库地址，注意时区配置 -->
                <property name="username" value="root"/> <!-- 数据库用户名 -->
                <property name="password" value="root"/> <!-- 数据库密码 -->
            </dataSource>
        </environment>
    </environments>

    <!-- 加载Mapper映射文件（告诉MyBatis SQL在哪里） -->
    <mappers>
        <mapper resource="com/jr/mapper/DeptMapper.xml"/>
    </mappers>
</configuration>

关键说明：

transactionManager type="JDBC"：使用 JDBC 的事务管理机制，手动控制提交 / 回滚；
dataSource type="POOLED"：使用连接池，避免频繁创建 / 关闭连接，提升性能。

步骤 5：编写 Mapper 映射文件（DeptMapper.xml）

Mapper 文件是 MyBatis 的 "SQL 仓库"，定义 SQL 语句与结果映射规则：

复制代码

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
<!-- namespace：命名空间，唯一标识（后续会用到，暂时可写包路径） -->
<mapper namespace="com.jr.mapper.DeptMapper">
    <!-- 查询所有部门：id=SQL唯一标识，resultType=返回结果的实体类全路径 -->
    <select id="selectDept" resultType="com.jr.pojo.Dept">
        select * from dept  <!-- 手写SQL，灵活可控 -->
    </select>
</mapper>

步骤 6：编写测试类（MyTest.java）

通过测试类验证环境是否搭建成功，核心是获取SqlSession并调用 SQL：

复制代码

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;
import java.util.List;

public class MyTest {
    public static void main(String[] args) throws Exception {
        // 1. 加载全局配置文件（SqlMapConfig.xml）
        InputStream is = Resources.getResourceAsStream("SqlMapConfig.xml");
        
        // 2. 创建SqlSessionFactory（会话工厂，全局唯一）
        SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(is);
        
        // 3. 创建SqlSession（与数据库的一次会话，用完必须关闭）
        SqlSession session = factory.openSession();
        
        // 4. 执行SQL：通过"namespace+id"定位到具体SQL
        List<Dept> depts = session.selectList("com.jr.mapper.DeptMapper.selectDept");
        
        // 5. 打印结果
        for (Dept dept : depts) {
            System.out.println(dept);
        }
        
        // 6. 关闭会话（释放资源，避免内存泄漏）
        session.close();
    }
}

步骤 7：添加日志配置（可选，推荐）

新建log4j.properties文件，查看 SQL 执行过程（方便调试）：

复制代码

log4j.rootLogger=DEBUG, Console
log4j.appender.Console=org.apache.log4j.ConsoleAppender
log4j.appender.Console.layout=org.apache.log4j.PatternLayout
log4j.appender.Console.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
log4j.logger.org.apache.ibatis=DEBUG
log4j.logger.java.sql=DEBUG

运行测试类后，控制台会输出 SQL 执行日志，如 "Preparing: select * from dept"，确认 SQL 正常执行。

3.2 方式二：Maven 项目搭建（企业实战级）

普通项目需手动导入 jar 包，Maven 可自动管理依赖，是企业开发的标准方式。

步骤 1：创建 Maven 项目结构

复制代码

mybatis-maven-demo/
├─ src/
│  ├─ main/
│  │  ├─ java/
│  │  │  └─ com/jr/pojo/Dept.java       # 实体类
│  │  │  └─ com/jr/mapper/DeptMapper.java  # Mapper接口（后续讲代理开发）
│  │  ├─ resources/
│  │  │  ├─ SqlMapConfig.xml            # 全局配置文件
│  │  │  ├─ log4j.properties            # 日志配置
│  │  │  └─ com/jr/mapper/DeptMapper.xml # Mapper映射文件
│  └─ test/
│     └─ java/com/jr/test/MyTest.java    # 测试类
└─ pom.xml                               # Maven依赖配置文件

步骤 2：配置 pom.xml（核心依赖）

在pom.xml中添加 MyBatis、MySQL 驱动、JUnit 等依赖，Maven 会自动下载：

复制代码

<dependencies>
    <!-- MyBatis核心依赖 -->
    <dependency>
        <groupId>org.mybatis</groupId>
        <artifactId>mybatis</artifactId>
        <version>3.5.3</version>
    </dependency>

    <!-- MySQL驱动（适配MySQL8.0+） -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.11</version>
    </dependency>

    <!-- JUnit测试依赖（测试用例） -->
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.12</version>
        <scope>test</scope> <!-- 只在测试阶段生效 -->
    </dependency>

    <!-- 日志依赖（Slf4j+Log4j，查看SQL执行日志） -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-log4j12</artifactId>
        <version>1.7.25</version>
    </dependency>
</dependencies>

<!-- 解决Maven不编译Java目录下XML文件的问题 -->
<build>
    <resources>
        <resource>
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.xml</include> <!-- 编译Java目录下的XML文件 -->
            </includes>
        </resource>
        <resource>
            <directory>src/main/resources</directory>
            <includes>
                <include>**/*.xml</include>
                <include>**/*.properties</include>
            </includes>
        </resource>
    </resources>
</build>

关键说明 ：Maven 默认只编译resources目录下的配置文件，Java 目录下的 XML（如 Mapper 文件）需通过<build>标签配置才能编译，否则会报 "文件找不到" 错误。

步骤 3：重复普通项目的核心文件

实体类（Dept.java）、全局配置文件（SqlMapConfig.xml）、Mapper 映射文件（DeptMapper.xml）的内容与普通项目一致，直接复制即可。

步骤 4：编写测试类（JUnit 测试）

Maven 项目推荐用 JUnit 编写测试用例，更规范：

复制代码

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.Before;
import org.junit.Test;
import java.io.InputStream;
import java.util.List;

public class MyTest {
    private SqlSessionFactory factory;

    // 测试方法执行前初始化SqlSessionFactory（只执行一次）
    @Before
    public void setUp() throws Exception {
        InputStream is = Resources.getResourceAsStream("SqlMapConfig.xml");
        factory = new SqlSessionFactoryBuilder().build(is);
    }

    // 测试查询所有部门
    @Test
    public void testSelectDept() throws Exception {
        SqlSession session = factory.openSession();
        List<Dept> depts = session.selectList("com.jr.mapper.DeptMapper.selectDept");
        for (Dept dept : depts) {
            System.out.println(dept);
        }
        session.close();
    }
}

四、总结与下一步

第一篇博客我们完成了 MyBatis 的 "基础铺垫"：

理解了框架的本质与价值，知道 MyBatis 为何能替代 JDBC；
掌握了两种环境搭建方式（普通项目 + Maven 项目），能动手执行简单的查询操作。

下一步预告：第二篇博客将深入 MyBatis 的 "核心配置与开发规范"，包括：

MyBatis 三层架构与核心类解析（SqlSession、Executor 等）；
全局配置文件（SqlMapConfig.xml）的详细配置（properties、settings、typeAliases 等）；
Mapper 代理开发规范（企业主流开发方式，无需写 Dao 实现类）。

跟着系列博客一步步操作，你会发现 MyBatis 并不复杂 ------ 关键是理解 "配置逻辑" 与 "开发规范"，后续的进阶内容也会水到渠成。