MyBatis基础教程：Java持久层框架入门
一、开篇：什么是MyBatis？它有什么用？
在开发 Java 应用程序时，我们经常需要将数据保存到数据库中。如果你之前学过 JDBC（Java Database Connectivity），你可能会觉得操作数据库有点麻烦：连接、执行 SQL、处理结果集……代码又长又容易出错。
MyBatis 是一个轻量级的 Java 持久层框架，它的作用就是简化我们与数据库打交道的过程。简单来说：
MyBatis = 简化版JDBC + 自定义SQL控制
它可以自动帮我们做很多底层的操作，比如连接数据库、执行SQL语句、把结果映射成 Java 对象等。但同时它不会替你写 SQL，你可以完全掌控 SQL 的编写，这对性能优化非常重要。
二、环境准备：搭建你的第一个MyBatis项目
2.1 工具清单（新手友好）
- IDE：推荐使用 IntelliJ IDEA
- JDK：建议使用 JDK 8 或以上版本
- 数据库：MySQL 5.7+
- 构建工具：Maven（用于管理依赖和打包）
- 其他插件/库：
- MyBatis 核心库
- MySQL JDBC 驱动
2.2 步骤详解
第一步：创建Maven项目
打开 IntelliJ IDEA，选择 Create New Project -> Maven -> 勾选 Create from archetype -> 选择 maven-archetype-quickstart
填写 GroupId（如 com.example）、ArtifactId（如 mybatis-demo），然后点击完成。
第二步：添加依赖（pom.xml）
打开项目根目录下的 pom.xml 文件，加入以下两个核心依赖：
<!-- MyBatis核心 -->
<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>
第三步：配置数据库信息
在 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>
<mappers>
<mapper resource="UserMapper.xml"/>
</mappers>
</configuration>
💡 注意事项：
- 把
testdb替换成你实际创建的数据库名- 把
root和your_password改为你自己的数据库账号密码- 如果是旧版本 MySQL，可能不需要
&serverTimezone=UTC
三、核心概念讲解：轻松理解MyBatis的几个关键角色
为了帮你更好地理解 MyBatis，我们可以把它想象成一个“餐厅”。
3.1 核心组件类比图
| MyBatis组件 | 类比 | 说明 |
|---|---|---|
| SqlSessionFactory | 餐厅总开关 | 负责生成与数据库交互的“服务员” |
| SqlSession | 上菜的服务员 | 用来执行SQL、获取结果 |
| Mapper接口 | 客户点餐菜单 | 定义你要调用的方法 |
| XML映射文件 | 后厨做法手册 | 写具体的SQL语句，告诉后厨怎么做这道菜 |
3.2 通俗易懂的核心流程
- 准备好数据库连接信息（mybatis-config.xml）
- 创建 SqlSessionFactory，相当于打开餐厅大门
- 获取 SqlSession，相当于叫来一位服务员
- 调用 Mapper 方法，例如
userMapper.selectAllUsers() - 执行 XML 中的 SQL 语句，并返回结果
整个过程就相当于你在餐厅点了一份菜，服务生去后厨下单，厨师做完再端给你！
四、实战演练：跟着我一起做一个小项目吧！
4.1 我们要做什么
我们将完成一个简单的用户管理系统：
- 查询所有用户信息
- 插入一条新用户记录
4.2 数据库准备
先在你的 MySQL 中创建一个数据库（如 testdb），然后执行以下 SQL 创建表：
CREATE TABLE user (
id INT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(100),
email VARCHAR(100)
);
插入一条测试数据：
INSERT INTO user(name, email) VALUES ('Tom', 'tom@example.com');
4.3 编写Java实体类 User.java
在 src/main/java 下创建包 com.example.demo.model，并新建类 User.java
package com.example.demo.model;
public class User {
private int id;
private String name;
private String email;
// Getter and Setter（可以右键 Generate 自动生成）
}
4.4 编写Mapper接口 UserMapper.java
在同一包下新建接口 UserMapper.java
package com.example.demo.mapper;
import java.util.List;
import com.example.demo.model.User;
public interface UserMapper {
List<User> selectAllUsers();
void insertUser(User user);
}
4.5 编写XML映射文件 UserMapper.xml
在 resources 目录下创建 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.demo.mapper.UserMapper">
<select id="selectAllUsers" resultType="com.example.demo.model.User">
SELECT * FROM user
</select>
<insert id="insertUser" parameterType="com.example.demo.model.User">
INSERT INTO user (name, email) VALUES (#{name}, #{email})
</insert>
</mapper>
4.6 最后测试主函数 App.java
修改默认生成的 App.java 内容如下：
package com.example.demo;
import com.example.demo.mapper.UserMapper;
import com.example.demo.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.IOException;
import java.io.InputStream;
import java.util.List;
public class App {
public static void main(String[] args) throws IOException {
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);
// 查询所有用户
List<User> users = mapper.selectAllUsers();
for (User u : users) {
System.out.println("ID: " + u.getId() + ", Name: " + u.getName() + ", Email: " + u.getEmail());
}
// 插入新用户
User newUser = new User();
newUser.setName("Jerry");
newUser.setEmail("jerry@example.com");
mapper.insertUser(newUser);
session.commit(); // 提交事务
}
}
}
✅ 运行效果
运行程序后，你会看到终端输出已有的用户信息，并且数据库中会新增一条 “Jerry”的记录。
五、常见问题答疑：别踩这些坑！
问题1：找不到 mapper 接口或报 NullPointerException
✅ 原因：可能是没有正确注册 mapper 文件
💡 解决办法：确认 mybatis-config.xml 中是否包含 <mapper> 标签指向正确的 XML 文件
问题2：无法连接数据库，提示连接超时或认证失败
✅ 原因：账号密码错误 / URL 地址错误 / 网络问题
💡 解决办法：检查你的数据库是否启动、URL是否正确、账号密码是否正确
问题3：执行 insert 成功却没数据变化
✅ 原因：没有提交事务！
💡 解决办法：记得调用 session.commit() 来提交更改
问题4：中文乱码
✅ 原因：URL 没有设置字符编码
💡 解决办法：把连接字符串改为：
jdbc:mysql://localhost:3306/testdb?useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC
六、学习建议：下一步你可以怎么走？
恭喜你已经完成了 MyBatis 的入门阶段！接下来你可以进一步学习以下内容：
- 📌 动态SQL：根据条件拼接 SQL，比如
<if><foreach> - 📌 注解方式：不用 XML，直接在接口上写 SQL（@Select、@Insert）
- 📌 分页查询：结合 PageHelper 实现分页功能
- 📌 事务管理：多个操作同时成功或失败
- 📌 Spring 整合：把 MyBatis 与 Spring Boot 结合使用，打造企业级项目
🔍 学习资源推荐：
- 官方文档：https://mybatis.org/mybatis-3/
- B站视频教程搜索关键词："MyBatis 新手入门"
- GitHub 示例项目：搜索“mybatis demo”
总结
本篇文章带你一步步从零开始搭建了一个使用 MyBatis 的小项目，并解释了它的核心机制和常见问题。希望你能通过实践掌握这个强大的数据库访问框架。
记住一句话：
MyBatis 不是用来逃避 SQL 的，而是用来优雅地写 SQL 并安全高效地使用的工具。
继续加油，你离一名合格的 Java 开发者又近了一步！🌟
评论 0