MyBatis基础教程：Java持久层框架入门
——一位文科转码者的零基础实战指南
大家好，我是一名从中文系“叛逃”到程序员队伍的自学转码者。当初学 Java 后端时，面对一堆 ORM、DAO、SQL 映射之类的术语，真是一头雾水。尤其是第一次接触 MyBatis 时，光是配置文件就让我折腾了整整两天。所以今天我想用最直白的语言，带完全零基础的朋友一起走进 MyBatis 的世界。
这篇文章不讲高深理论，只聚焦一件事：让你亲手跑通一个能查数据库的 Java 程序。我会结合自己的实战经验，一步步带你搭建环境、理解核心概念，并完成一个简单的“用户查询”功能。无论你是前端想了解后端，还是纯新手想入门 Java 持久层开发，都能跟着做出来。
一、MyBatis 是什么？它用来做什么？
简单说：MyBatis 是一个帮 Java 程序和数据库“对话”的工具。
- 前端负责界面（比如网页按钮、输入框）
- 后端负责逻辑和数据处理（比如“用户点登录，我去数据库查账号密码”）
- 而 MyBatis 就是后端访问数据库的“翻译官”：你写 SQL，它帮你把结果变成 Java 对象，省去手动解析数据库返回值的麻烦。
💡 我当初学的时候以为 ORM（对象关系映射）很玄乎，其实本质就是：把数据库的一行数据，自动变成一个 Java 对象。比如
users表里一条记录{id: 1, name: "张三"}，MyBatis 能直接变成User user = new User(1, "张三")。
二、环境准备：5 分钟搭好开发环境
我们需要以下工具（全部免费）：
| 工具 | 作用 | 安装建议 |
|---|---|---|
| JDK 8 或 11 | 运行 Java 程序 | 推荐 Oracle JDK 或 OpenJDK |
| Maven | 项目依赖管理 | 下载后配置环境变量 |
| - IntelliJ IDEA（社区版） | 写代码的 IDE | 免费，比 Eclipse 更友好 |
| MySQL | 数据库 | 安装后建一个测试库 |
步骤 1：创建 Maven 项目
打开 IDEA → New Project → 选择 Maven → 不勾选模板 → 输入 GroupId（如 com.example）、ArtifactId（如 mybatis-demo）
步骤 2：添加依赖
在 pom.xml 中加入以下依赖：
<dependencies>
<!-- MyBatis 核心 -->
<dependency>
<groupId>org.mybatis</groupId>
<artifactId>mybatis</artifactId>
<version>3.5.13</version>
</dependency>
<!-- MySQL 驱动 -->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>8.0.33</version>
</dependency>
<!-- 单元测试（可选但推荐） -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.13.2</version>
<scope>test</scope>
</dependency>
</dependencies>
⚠️ 注意：如果你用的是 MySQL 8.0+，驱动类名是
com.mysql.cj.jdbc.Driver，不是旧的com.mysql.jdbc.Driver。
三、核心概念：用大白话讲清楚 MyBatis 的三大件
MyBatis 只需要三个关键文件就能工作：
1. 实体类（Entity） —— Java 中的数据结构
对应数据库的一张表。
// src/main/java/com/example/User.java
public class User {
private int id;
private String name;
// 必须有无参构造函数（MyBatis 需要）
public User() {}
// getter/setter 省略（IDEA 可自动生成）
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; }
}
2. Mapper 接口 + XML 映射文件 —— 定义 SQL 和 Java 方法的对应关系
- Mapper 接口：你调用的方法声明
- XML 文件：具体的 SQL 语句
// src/main/java/com/example/UserMapper.java
public interface UserMapper {
User selectUserById(int id);
}
<!-- src/main/resources/com/example/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.UserMapper">
<select id="selectUserById" resultType="com.example.User">
SELECT id, name FROM users WHERE id = #{id}
</select>
</mapper>
🔍 关键点：
namespace必须是 Mapper 接口的全限定名id必须和接口方法名一致#{id}是安全的参数占位符（防 SQL 注入）
3. MyBatis 配置文件（mybatis-config.xml） —— 全局设置
<!-- src/main/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/testdb?useSSL=false&serverTimezone=UTC"/>
<property name="username" value="root"/>
<property name="password" value="your_password"/>
</dataSource>
</environment>
</environments>
<!-- 注册 Mapper XML 文件 -->
<mappers>
<mapper resource="com/example/UserMapper.xml"/>
</mappers>
</configuration>
四、实战项目：5 分钟实现“根据 ID 查询用户”
步骤 1：准备数据库
CREATE DATABASE testdb;
USE testdb;
CREATE TABLE users (
id INT PRIMARY KEY,
name VARCHAR(50)
);
INSERT INTO users VALUES (1, '李四'), (2, '王五');
步骤 2：编写测试代码
// src/test/java/com/example/MyBatisTest.java
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;
public class MyBatisTest {
@Test
public void testSelectUser() throws Exception {
// 1. 读取配置文件
String resource = "mybatis-config.xml";
InputStream inputStream = Resources.getResourceAsStream(resource);
// 2. 创建 SqlSessionFactory
SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);
// 3. 获取 SqlSession（相当于数据库连接）
try (SqlSession session = sqlSessionFactory.openSession()) {
// 4. 获取 Mapper 接口代理对象
UserMapper mapper = session.getMapper(UserMapper.class);
// 5. 调用方法
User user = mapper.selectUserById(1);
System.out.println("查到的用户: " + user.getName()); // 输出：李四
}
}
}
运行这个测试方法，如果看到 “查到的用户: 李四”，恭喜你！MyBatis 已经跑通了！
🛠️ 实战经验提醒：
- 所有资源路径（如 XML 文件）必须放在
src/main/resources下，否则会找不到- Mapper XML 的
namespace写错是最常见的错误之一
五、新手常见问题 & 解决方案
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
ClassNotFoundException: com.mysql.cj.jdbc.Driver |
MySQL 驱动未正确引入 | 检查 pom.xml 是否有 mysql-connector-java 依赖 |
Invalid bound statement |
Mapper XML 未注册或 namespace 错误 | 检查 mybatis-config.xml 中 <mappers> 配置 |
| 返回 null | SQL 写错或数据库无数据 | 先在 MySQL 客户端执行相同 SQL 确认结果 |
| 中文乱码 | 数据库连接未指定编码 | 在 JDBC URL 加 ?useUnicode=true&characterEncoding=utf8 |
| 方法找不到 | Mapper 接口和 XML 的 id 不匹配 | 确保方法名、参数类型完全一致 |
💡 我当初学的时候，因为
namespace写成了UserMapper（漏了包名），调试了 3 小时……记住：namespace = 包名 + 类名
六、学习建议：下一步怎么走？
你已经掌握了 MyBatis 最核心的流程。接下来可以：
尝试增删改操作
在 Mapper 中添加<insert>,<update>,<delete>标签，注意：修改操作需要手动提交事务（session.commit()）学习动态 SQL
比如根据条件查询：<if test="name != null"> AND name = #{name}</if>整合 Spring Boot
实际项目中 MyBatis 通常和 Spring Boot 搭配使用，用@MapperScan自动注入，无需手动创建 SqlSession对比其他框架
了解 Hibernate（全自动 ORM）和 MyBatis（半自动）的区别：特性 MyBatis Hibernate SQL 控制 完全手动写 SQL 自动生成 SQL 学习曲线 较低（适合新手） 较高 性能优化 灵活（可精细调优） 黑盒，难调优 适用场景 复杂查询多、需 SQL 优化 快速开发、CRUD 为主
结语
作为曾经连“持久层”是什么都不知道的文科生，我想告诉你：技术没有那么可怕，关键是从“跑起来”开始。MyBatis 的设计哲学就是“少即是多”——它不替你做决定，而是给你最大自由去写 SQL。
现在，你已经有了第一个能连数据库的 Java 程序。接下来，试着加个“插入用户”功能，或者把查询改成按名字模糊搜索。每一步小成功，都是你成为后端工程师的坚实脚印。
最后送你一句我转码路上的座右铭：“看不懂的代码，跑一遍就懂了。”
加油，未来的开发者！
评论 0