MyBatis基础教程：Java持久层框架入门
作者：985毕业的全栈工程师，掘金专栏作者
写作初衷：很多初学者一听到“持久层”“ORM”就望而却步，其实没那么难！我当初学的时候也踩过坑，今天就用最直白的方式带你上手 MyBatis。
为什么你需要 MyBatis？
在 Java 开发中，后端程序经常需要和数据库打交道——比如用户注册、商品查询、订单保存等。这个“和数据库交互”的过程，在专业术语中叫做 数据持久化。
你可能会问：“那我直接用 JDBC 不行吗？”
当然可以！但 JDBC 写起来很繁琐：要手动管理连接、写 SQL、处理 ResultSet、还要防止内存泄漏……对于初学者来说，这简直是“劝退三连”。
于是，MyBatis 应运而生。它是一个轻量级的 Java 持久层框架，帮你自动完成大部分重复工作，让你专注于写 SQL 和业务逻辑。
技术选型对比：MyBatis vs Hibernate vs JDBC
| 方案 | 学习成本 | 灵活性 | SQL 控制力 | 适合场景 |
|---|---|---|---|---|
| JDBC | 高 | 低 | 完全控制 | 小项目或学习原理 |
| Hibernate | 中高 | 低 | 几乎无（自动生成） | 快速开发、领域模型复杂 |
| MyBatis | 低 | 高 | 完全控制 | 大多数企业项目（尤其国内） |
💡 我的实战经验：在国内互联网公司，MyBatis 是主流选择。因为它既简化了 JDBC 的样板代码，又保留了对 SQL 的完全掌控——这对性能调优和复杂查询至关重要。
一、环境准备：5 分钟搭建开发环境
我们将使用最简单的 Java SE + MyBatis + H2（内存数据库）来演示，无需安装 MySQL。
所需工具
- JDK 8 或以上
- Maven（推荐）或 Gradle
- 任意 IDE（IntelliJ IDEA / Eclipse）
步骤 1：创建 Maven 项目
<!-- pom.xml -->
<dependencies>
<!-- MyBatis 核心 -->
<dependency>
<groupId>org.mybatis</groupId>
<artifactId>mybatis</artifactId>
<version>3.5.13</version>
</dependency>
<!-- H2 内存数据库（免安装） -->
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>2.2.224</version>
</dependency>
<!-- 日志（方便看 SQL） -->
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<version>1.4.11</version>
</dependency>
</dependencies>
步骤 2：配置 MyBatis
创建 src/main/resources/mybatis-config.xml：
<?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">
<transactionManager type="JDBC"/>
<dataSource type="POOLED">
<property name="driver" value="org.h2.Driver"/>
<property name="url" value="jdbc:h2:mem:testdb"/>
<property name="username" value="sa"/>
<property name="password" value=""/>
</dataSource>
</environment>
</environments>
<!-- 映射文件位置 -->
<mappers>
<mapper resource="UserMapper.xml"/>
</mappers>
</configuration>
✅ 小贴士：H2 数据库是纯内存的，程序一跑就自动建表，关掉就清空，非常适合学习！
二、核心概念：3 个关键角色
MyBatis 的核心非常简单，记住这 3 个东西就够了：
1. SqlSessionFactory
工厂对象，用来创建 SqlSession。整个应用只需要一个。
2. SqlSession
代表一次数据库会话，你可以用它执行 SQL、提交事务等。
3. Mapper（映射器）
这是你写 SQL 的地方！通常是一个 XML 文件（也可以用注解），把 Java 方法和 SQL 绑定在一起。
🤔 我当初学的时候总搞不清 Mapper 是啥——其实就是“方法 ↔ SQL”的映射表！
三、实战项目：实现一个用户管理系统
我们来做一个最简单的功能：新增用户 + 查询所有用户。
步骤 1：创建 User 实体类
// src/main/java/com/example/User.java
public class User {
private Long id;
private String name;
private String email;
// 构造函数、getter/setter 省略（可用 Lombok 简化）
}
步骤 2：编写 Mapper XML
<!-- src/main/resources/UserMapper.xml -->
<?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">
<mapper namespace="UserMapper">
<!-- 插入用户 -->
<insert id="insertUser" parameterType="com.example.User">
INSERT INTO users (name, email) VALUES (#{name}, #{email})
</insert>
<!-- 查询所有用户 -->
<select id="findAllUsers" resultType="com.example.User">
SELECT id, name, email FROM users
</select>
</mapper>
🔍 注意：
namespace必须唯一，通常用类名#{name}是 MyBatis 的占位符，会自动防 SQL 注入！
步骤 3：初始化数据库表（H2 自动执行）
在 mybatis-config.xml 同级目录下创建 schema.sql（非必须，但推荐）：
CREATE TABLE IF NOT EXISTS users (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100),
email VARCHAR(100)
);
然后在代码中加载：
// 初始化 H2 表结构（仅演示用）
try (Connection conn = DriverManager.getConnection("jdbc:h2:mem:testdb", "sa", "")) {
Statement stmt = conn.createStatement();
stmt.execute("CREATE TABLE IF NOT EXISTS users (id BIGINT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100), email VARCHAR(100))");
}
步骤 4：编写主程序
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 Main {
public static void main(String[] args) throws Exception {
// 1. 加载配置文件
InputStream inputStream = Resources.getResourceAsStream("mybatis-config.xml");
// 2. 创建 SqlSessionFactory
SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);
// 3. 获取 SqlSession
try (SqlSession session = sqlSessionFactory.openSession()) {
// 4. 插入用户
User user = new User();
user.setName("张三");
user.setEmail("zhangsan@example.com");
session.insert("UserMapper.insertUser", user);
// 5. 提交事务（重要！）
session.commit();
// 6. 查询所有用户
List<User> users = session.selectList("UserMapper.findAllUsers");
for (User u : users) {
System.out.println("ID: " + u.getId() + ", Name: " + u.getName());
}
}
}
}
⚠️ 新手常见错误：忘记 session.commit()！默认 MyBatis 不自动提交，插入/更新后必须手动 commit。
四、常见问题 & 避坑指南
Q1：为什么查不到数据？SQL 明明是对的！
原因：很可能忘了 session.commit()，或者 Mapper 的 namespace 写错了。
检查清单：
- 是否调用了
session.commit()？ - Mapper XML 的
namespace和代码中的字符串是否一致？ -
resultType是否写全了包名？（如com.example.User）
Q2：能不用 XML 吗？我想用注解！
当然可以！MyBatis 支持注解方式：
public interface UserMapper {
@Insert("INSERT INTO users (name, email) VALUES (#{name}, #{email})")
void insertUser(User user);
@Select("SELECT * FROM users")
List<User> findAllUsers();
}
但在实际项目中，复杂 SQL 还是推荐用 XML，更清晰、支持动态 SQL。
Q3：前端怎么和 MyBatis 对接？
注意：MyBatis 是后端技术，不直接和前端交互！
典型流程：
前端（Vue/React） → HTTP 请求 → Spring Boot Controller → Service → MyBatis → 数据库
所以你在学 MyBatis 时，暂时不用管前端，专注 Java 和数据库即可。
五、下一步学习建议
你已经掌握了 MyBatis 最核心的部分！接下来可以：
整合 Spring Boot
使用mybatis-spring-boot-starter，告别手动创建 SqlSessionFactory。学习动态 SQL
比如<if>、<foreach>，实现条件查询、批量插入等。理解 #{} 和 ${} 的区别
#{}是预编译（安全），${}是字符串拼接（有注入风险）！尝试 PageHelper 分页插件
企业级分页必备。
📌 我的建议：不要一上来就学 Spring Boot + MyBatis，先搞懂原生 MyBatis 的工作原理，后面整合才不会“魔法感”太强。
结语
MyBatis 并不难，它只是帮你把 JDBC 的脏活累活自动化了。你依然是 SQL 的主人，这也是它在国内经久不衰的原因。
我当初学的时候，也是从一行 INSERT 开始的。只要你动手敲一遍上面的代码，你就已经超过了 50% 只看不练的人。
记住：编程没有捷径，但有正确的路径。
👋 如果你觉得这篇教程对你有帮助，欢迎关注我的掘金主页，我会持续更新《零基础学 Java》系列文章。下一期：《Spring Boot + MyBatis 整合实战》！
评论 0