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

大家好！我是一名从文科转码成功的后端开发者。当初学 Java 的时候，面对数据库操作那堆 Connection、Statement、ResultSet 真是头大——代码又长又容易出错。后来接触了 MyBatis，才发现原来和数据库打交道可以这么简单！

今天我就用最直白的语言，带你从零开始上手 MyBatis。无论你是完全没碰过数据库的新手，还是正在学 Java 的学生，这篇教程都能让你动手写出自己的第一个持久层程序。

小提示：虽然本文讲的是 Java 框架 MyBatis，但我会在适当处提及其他技术（比如 Go 或爬虫）作为对比，帮你建立更完整的后端知识图谱。

---

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

想象一下：你要把用户注册信息存到数据库里。不用框架时，你得手动写：

• 连接数据库
• 拼 SQL 字符串（容易拼错）
• 处理参数（防 SQL 注入）
• 把查询结果一行行转成 Java 对象

太繁琐了！MyBatis 就是一个“翻译官”：你只需要写 SQL 和 Java 对象，它自动帮你完成中间所有脏活累活。

💡 通俗比喻：
如果把数据库比作图书馆，SQL 是借书单，Java 对象是你想要的书，
那 MyBatis 就是那个帮你跑腿取书的管理员。

---

二、环境准备（5 分钟搞定）

我们需要以下工具：

工具	版本建议	用途
JDK	8 或 11	运行 Java 程序
Maven	3.6+	项目依赖管理
MySQL	5.7+ 或 8.0	数据库（可用其他如 PostgreSQL）
IDE	IntelliJ IDEA / VS Code	写代码

步骤 1：创建 Maven 项目

打开终端，执行：

mvn archetype:generate -DgroupId=com.example -DartifactId=mybatis-demo -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

步骤 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>

步骤 3：创建数据库

CREATE DATABASE mybatis_demo;
USE mybatis_demo;

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

---

三、核心概念三句话讲清楚

1. Mapper 接口：你定义一个 Java 接口，比如 UserMapper，里面写方法如 insertUser(User user)。
2. XML 映射文件：告诉 MyBatis 每个方法对应哪条 SQL。比如 <insert id="insertUser">INSERT INTO user ...</insert>。
3. SqlSession：MyBatis 的“会话对象”，通过它调用 Mapper 方法。

✅ 我当初学的时候，总以为要自己 new Mapper 对象——其实 MyBatis 会自动代理生成实现类，你只管调用就行！

---

四、实战：5 步实现用户增删改查

第 1 步：创建 User 实体类

// src/main/java/com/example/User.java
public class User {
    private int id;
    private String name;
    private String email;
    
    // 必须有 getter/setter（省略）
    public int getId() { return id; }
    public void setId(int id) { this.id = id; }
    // ... 其他 getter/setter
}

第 2 步：编写 Mapper 接口

// src/main/java/com/example/UserMapper.java
public interface UserMapper {
    void insertUser(User user);
    User selectUserById(int id);
    List<User> selectAllUsers();
    void deleteUser(int id);
}

第 3 步：编写 XML 映射文件

创建目录：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">
    <insert id="insertUser" parameterType="com.example.User">
        INSERT INTO user(name, email) VALUES(#{name}, #{email})
    </insert>

    <select id="selectUserById" resultType="com.example.User">
        SELECT * FROM user WHERE id = #{id}
    </select>

    <select id="selectAllUsers" resultType="com.example.User">
        SELECT * FROM user
    </select>

    <delete id="deleteUser">
        DELETE FROM user WHERE id = #{id}
    </delete>
</mapper>

第 4 步：配置 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/mybatis_demo?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="你的密码"/>
            </dataSource>
        </environment>
    </environments>

    <mappers>
        <mapper resource="com/example/UserMapper.xml"/>
    </mappers>
</configuration>

第 5 步：写主程序测试

// src/main/java/com/example/App.java
public class App {
    public static void main(String[] args) throws IOException {
        // 1. 读取配置
        InputStream inputStream = Resources.getResourceAsStream("mybatis-config.xml");
        SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);

        // 2. 创建会话
        try (SqlSession session = sqlSessionFactory.openSession()) {
            UserMapper mapper = session.getMapper(UserMapper.class);

            // 3. 插入用户
            User user = new User();
            user.setName("张三");
            user.setEmail("zhangsan@example.com");
            mapper.insertUser(user);
            session.commit(); // 别忘了提交！

            // 4. 查询用户
            User found = mapper.selectUserById(1);
            System.out.println("查到用户: " + found.getName());

            // 5. 查询所有
            List<User> users = mapper.selectAllUsers();
            users.forEach(u -> System.out.println(u.getEmail()));
        }
    }
}

运行 App.java，如果看到输出，恭喜你！MyBatis 已经跑起来了！

---

五、新手常见问题 & 解决方案

问题	原因	解决办法
BindingException: Invalid bound statement	Mapper 接口与 XML 的 namespace 不匹配	检查 XML 的 namespace 是否等于接口全路径名
数据没插入成功	忘记 session.commit()	所有写操作后必须调用 commit()
中文乱码	MySQL 编码问题	在 JDBC URL 后加 &characterEncoding=utf8
找不到 Mapper 文件	资源未打包	确保 XML 放在 resources 目录下，且路径与包名一致

⚠️ 避坑指南：我当初花了 2 小时排查“无效绑定”错误，就是因为 XML 文件放错了目录——Maven 默认不打包 java 目录下的非 .java 文件！

---

六、学习建议 & 下一步

你现在掌握了 MyBatis 最核心的用法。接下来可以：

1. 深入学习：

   • 动态 SQL（<if>, <foreach>）
   • 关联查询（一对一、一对多）
   • 使用注解代替 XML（适合简单 SQL）

2. 对比其他技术：

   • Go 语言：如果你对 Go 感兴趣，它的数据库操作通常用 database/sql 包 + ORM 如 GORM，风格更轻量。
   • 爬虫场景：爬虫抓取的数据常需入库，MyBatis 正好用于后端存储——前端爬数据，后端用 MyBatis 存数据，分工明确。

3. 工程化：

   • 将 MyBatis 与 Spring Boot 整合（业界标准）
   • 使用连接池（如 HikariCP）提升性能

🌟 最后鼓励：我从背单词的文科生到写后端框架，靠的就是“动手做”。别怕报错，每个红字都是你进步的台阶。现在，去改改上面的代码，试试更新用户、模糊查询吧！

祝你编码愉快！