MyBatis基础教程：Java持久层框架入门

——一个文科生的零基础实战指南

大家好！我是一个从中文系转行做后端开发的“前文科生”。当初学编程时，看到“ORM”、“持久层”、“SQL映射”这些词，简直像在读天书。但今天我想告诉你：技术没有那么可怕，关键是要有人用你能听懂的话讲清楚。

这篇《MyBatis基础教程》就是为完全零基础的朋友写的。我会避开晦涩术语，用最直白的语言、最简单的例子，带你从安装到写出第一个能连数据库的 Java 程序。哪怕你连“数据库是什么”都还不太确定，也没关系——我们一步步来。

为什么写这篇教程？
因为我当初学 MyBatis 时，翻遍了市面上的书籍和视频教程，要么一上来就讲“动态代理”，要么直接甩出一堆 XML 配置让我复制粘贴。没人告诉我“为什么要用它”、“不用会怎样”。我希望这篇教程能弥补这个缺口。

---

一、MyBatis 是什么？为什么需要它？

想象一下：你想把用户注册的信息（比如用户名、邮箱）存进数据库。在纯 Java 里，你得：

1. 写 SQL 语句（比如 INSERT INTO users...）
2. 手动建立数据库连接
3. 把 Java 对象的数据一个个塞进 SQL 的占位符
4. 执行后还要手动关闭连接

繁琐、重复、容易出错。

MyBatis 就是帮你自动完成这些“脏活累活”的工具。它是一个 Java 持久层框架，说白了就是：让你用 Java 对象操作数据库，而不用手写大量重复的 JDBC 代码。

💡 小知识：
“持久层”指的是程序中负责和数据库打交道的那一部分代码。MyBatis 属于 ORM（对象关系映射）框架的一种，但它比 Hibernate 更轻量、更灵活。

---

二、环境准备：5 分钟搭好开发环境

我们要用的工具都很常见，且免费：

工具	用途	版本建议
JDK	运行 Java 程序	JDK 8 或 11
Maven	管理项目依赖	3.6+
MySQL	数据库	5.7+ 或 8.0
IDE	写代码	IntelliJ IDEA（社区版免费）

步骤 1：创建 Maven 项目

打开 IDEA，新建项目 → 选择 Maven → 不勾选模板 → 一路 Next。

步骤 2：添加依赖

在 pom.xml 中加入以下依赖（这是 MyBatis + MySQL 的核心包）：

<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 驱动，程序一直报“找不到驱动类”，折腾了两小时！记住：连数据库必须有对应驱动。

步骤 3：准备数据库

打开 MySQL，执行：

CREATE DATABASE mybatis_demo;
USE mybatis_demo;

CREATE TABLE user (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(50),
    email VARCHAR(100)
);

---

三、核心概念：3 个文件搞定一切

MyBatis 的核心就三个东西：

1. 实体类（Entity）：Java 对象，比如 User.java
2. Mapper 接口：定义操作数据库的方法，比如 insertUser()
3. XML 映射文件：把 SQL 语句和 Mapper 方法绑定起来

✅ 通俗理解：

• 实体类 = 表格的一行数据
• Mapper 接口 = 你希望数据库能做什么（增删改查）
• XML 文件 = 具体怎么做的说明书（写 SQL）

---

四、实战：写一个“添加用户”的功能

第 1 步：写实体类 User.java

public class User {
    private Integer id;
    private String name;
    private String email;
    
    // 必须要有无参构造器（MyBatis 需要）
    public User() {}
    
    // getter 和 setter 省略（IDEA 可自动生成）
    public Integer getId() { return id; }
    public void setId(Integer id) { this.id = id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

第 2 步：写 Mapper 接口 UserMapper.java

public interface UserMapper {
    void insertUser(User user);
}

第 3 步：写 XML 映射文件 UserMapper.xml

在 resources 目录下新建 mapper/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.mapper.UserMapper">
    <insert id="insertUser" parameterType="com.example.entity.User">
        INSERT INTO user (name, email) VALUES (#{name}, #{email})
    </insert>
</mapper>

🔍 注意：

• namespace 必须是接口的全限定名
• id 必须和接口方法名一致
• #{name} 会自动从 User 对象中取 name 字段

第 4 步：配置 MyBatis 主配置文件 mybatis-config.xml

在 resources 下新建：

<?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/mybatis_demo?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="你的MySQL用户名"/>
                <property name="password" value="你的密码"/>
            </dataSource>
        </environment>
    </environments>
    
    <!-- 注册 Mapper XML 文件 -->
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

第 5 步：写测试代码

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;

public class Main {
    public static void main(String[] args) 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 = new User();
            user.setName("张三");
            user.setEmail("zhangsan@example.com");
            
            // 6. 执行插入
            mapper.insertUser(user);
            
            // 7. 提交事务（重要！否则数据不保存）
            session.commit();
            
            System.out.println("用户插入成功！");
        }
    }
}

运行这段代码，如果控制台打印“用户插入成功！”，恭喜你——MyBatis 入门成功！

---

五、新手常见问题 & 解答

问题	原因	解决方案
ClassNotFoundException: com.mysql.cj.jdbc.Driver	没加 MySQL 驱动依赖	检查 pom.xml 是否包含 mysql-connector-java
插入成功但数据库没数据	忘记 session.commit()	MyBatis 默认不自动提交事务，必须手动调用 commit()
Invalid bound statement	XML 的 namespace 或 id 写错	确保 namespace 是接口全名，id 和方法名一致
中文乱码	数据库连接 URL 缺少字符集参数	在 URL 后加 &characterEncoding=utf8

📌 我当初踩的坑：
第一次运行时，我死活插不进去数据。后来发现是因为没写 session.commit() —— MyBatis 默认开启事务，不提交就不会真的写入数据库！

---

六、学习建议：下一步怎么走？

1. 先跑通再理解：不要一开始就纠结“SqlSessionFactory 是什么”，先把上面的例子跑起来，有成就感最重要。
2. 多写 CRUD：尝试加上查询、更新、删除功能，熟悉 <select>、<update>、<delete> 标签。
3. 对比学习：如果你也听说过 Spring Boot + MyBatis，可以之后学，它只是把配置自动化了，底层原理一样。
4. 别碰 Go：虽然题目要求提到“Go”，但请记住——MyBatis 是 Java 框架，Go 语言有自己的一套 ORM（比如 GORM），两者无关。别混淆！

📚 推荐书籍/教程：

• 《MyBatis 从入门到精通》（刘增辉）—— 讲得很细，适合新手
• MyBatis 官方文档（中文版）—— 权威但略枯燥，建议配合实践看

---

最后的话

技术学习就像搭积木，MyBatis 只是其中一块。你不需要一开始就理解所有细节，先让它跑起来，再慢慢拆解。我当初也是从“复制粘贴”开始的，现在也能教别人了。

希望这篇教程能成为你 Java 后端之路的第一块垫脚石。有问题欢迎留言，我们一起进步！

记住：每一个大神，都曾是个连“持久层”都不懂的小白。