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

大家好，我是小张，一名985高校毕业的全栈工程师，平时喜欢在掘金写一些技术入门教程。今天我想和大家聊聊 MyBatis —— 一个在 Java 后端开发中非常常用的持久层框架。

你可能会问：“为什么我要学 MyBatis？现在不是有 Spring Data、JPA 这些更‘高级’的东西吗？”
其实，MyBatis 虽然“老”，但非常“稳”。它灵活、轻量、性能好，国内大量企业（比如阿里、京东）的后端系统仍在广泛使用。更重要的是，理解 MyBatis 能帮你真正搞懂 Java 是如何和数据库打交道的——这是每个后端工程师的基本功。

我当初学的时候，被各种 XML 配置和 SQL 映射搞得晕头转向，踩过不少坑。所以今天这篇教程，我会用最通俗的语言、最简单的例子，带你从零开始掌握 MyBatis 的核心用法。即使你完全没接触过后端开发，只要会一点 Java 基础，就能跟着做！

📌 关键词提醒：虽然本文主题是 MyBatis，但也会简要提及 爬虫、Go、资源 和 后端 的关系，帮助你建立整体技术视野。

---

一、MyBatis 是什么？能用来做什么？

简单说：MyBatis 是一个帮助 Java 程序操作数据库的工具。

想象一下：你想把用户注册信息存到 MySQL 数据库里。不用框架的话，你需要：

1. 写 JDBC 代码连接数据库
2. 手动拼接 SQL 语句（比如 "INSERT INTO user..."）
3. 处理 ResultSet 结果集，把每一行数据转成 Java 对象
4. 关闭连接、处理异常……

这个过程又啰嗦又容易出错。而 MyBatis 帮你自动完成第 2~3 步：你只需要写 SQL，它负责把 Java 对象和数据库记录互相转换。

💡 小知识：这种“把对象和数据库记录映射”的技术，叫 ORM（Object-Relational Mapping）。MyBatis 是“半自动 ORM”——SQL 你写，映射它做；而 Hibernate/JPA 是“全自动 ORM”——连 SQL 都不用写。

---

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

我们使用最经典的组合：Java + Maven + MySQL + MyBatis

1. 安装必要软件

软件	版本建议	用途
JDK	8 或 11	Java 运行环境
Maven	3.6+	项目依赖管理
MySQL	5.7+ 或 8.0	数据库
IDE	IDEA / VS Code	写代码

✅ 避坑指南：MySQL 8.0 默认认证方式变了，如果连接报错，记得在连接字符串加 ?useSSL=false&serverTimezone=UTC

2. 创建 Maven 项目

打开终端，执行：

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

然后进入项目目录：

cd mybatis-demo

3. 添加 MyBatis 依赖

编辑 pom.xml，在 <dependencies> 中加入：

<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.13</version>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>

⚠️ 注意：不要加 Spring 相关依赖！我们先学纯 MyBatis，后面再整合 Spring。

4. 创建数据库和表

在 MySQL 中执行：

CREATE DATABASE mybatis_demo;
USE mybatis_demo;

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

插入几条测试数据：

INSERT INTO user (name, email) VALUES 
('张三', 'zhangsan@example.com'),
('李四', 'lisi@example.com');

---

三、核心概念：MyBatis 的四大组件

MyBatis 虽然配置看起来复杂，其实就四个核心部分：

1. SqlSessionFactory（工厂）

• 作用：创建 SqlSession 的“工厂”
• 类比：就像汽车制造厂，负责生产“SqlSession”这辆车

2. SqlSession（会话）

• 作用：执行 SQL、获取 Mapper、管理事务
• 类比：你开着“SqlSession”这辆车去数据库办事

3. Mapper 接口

• 作用：定义操作数据库的方法（如 selectUserById）
• 类比：你的“操作手册”

4. Mapper XML 文件

• 作用：写具体的 SQL 语句，并告诉 MyBatis 如何把结果映射成 Java 对象
• 类比：SQL 的“说明书”

🧠 记忆技巧：Factory → Session → Mapper Interface → Mapper XML，这是一个调用链。

---

四、实战：手把手写一个用户查询功能

我们现在来实现一个最简单的功能：根据 ID 查询用户信息

第一步：创建 User 实体类

在 src/main/java/com/example 下新建 User.java：

package com.example;

public class User {
    private int id;
    private String name;
    private String email;

    // 必须有无参构造函数！
    public User() {}

    // getter 和 setter
    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; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }

    @Override
    public String toString() {
        return "User{id=" + id + ", name='" + name + "', email='" + email + "'}";
    }
}

第二步：编写 Mapper 接口

新建 UserMapper.java：

package com.example;

public interface UserMapper {
    User selectUserById(int id);
}

第三步：编写 Mapper 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">
    <select id="selectUserById" resultType="com.example.User">
        SELECT id, name, email FROM user WHERE id = #{id}
    </select>
</mapper>

🔍 关键点解释：

• namespace 必须等于 Mapper 接口的全限定名
• id 必须等于接口中的方法名
• resultType 指定返回的 Java 类型
• #{id} 是参数占位符，MyBatis 会自动防 SQL 注入

第四步：配置 MyBatis 主配置文件

在 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>

第五步：编写测试代码

修改 App.java：

package com.example;

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;

public class App {
    public static void main(String[] args) throws IOException {
        // 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);
        }
    }
}

第六步：运行！

在项目根目录执行：

mvn compile exec:java -Dexec.mainClass="com.example.App"

如果看到输出：

User{id=1, name='张三', email='zhangsan@example.com'}

恭喜你！MyBatis 第一个程序跑通了！

---

五、新手常见问题解答（FAQ）

❓ Q1：为什么我的 XML 文件找不到？

• 检查 mybatis-config.xml 中 <mapper resource="..."> 的路径是否正确
• 确保 XML 文件放在 src/main/resources 下，且包路径与接口一致
• Maven 默认不编译非 .java 文件，可在 pom.xml 中添加资源过滤（但我们的结构已避免此问题）

❓ Q2：报错 “There is no getter for property named ‘xxx’”？

• 检查实体类是否有对应的 getXxx() 方法（注意大小写！）
• 字段名和数据库列名最好一致，否则要用 <resultMap> 显式映射

❓ Q3：如何执行 INSERT/UPDATE/DELETE？

在 Mapper XML 中用 <insert>, <update>, <delete> 标签，并在 Java 方法中加上 @Param 注解传参。例如：

int insertUser(@Param("name") String name, @Param("email") String email);

<insert id="insertUser">
    INSERT INTO user (name, email) VALUES (#{name}, #{email})
</insert>

⚠️ 注意：增删改操作默认不自动提交！需要手动 session.commit()。

❓ Q4：MyBatis 和爬虫、Go 有什么关系？

这是个好问题！虽然 MyBatis 是 Java 后端技术，但我们可以这样理解整个技术生态：

• 爬虫：通常用 Python 或 Go 编写，用于抓取网页数据
• Go：一门高性能后端语言，适合写微服务、API 网关
• 资源：爬虫抓到的数据，最终可能存入数据库（由 MyBatis 管理）
• 后端：MyBatis 是 Java 后端访问数据库的关键组件

举个场景：你用 Go 写一个 API 服务，调用 Python 爬虫获取商品价格，然后通过 HTTP 请求把数据发给 Java 后端，Java 后端用 MyBatis 把数据存入 MySQL。不同技术各司其职，共同构建完整系统。

---

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

MyBatis 只是后端开发的一小步。我建议你按以下路径深入：

1. 掌握 CRUD 全操作：尝试实现用户增删改查完整功能
2. 学习动态 SQL：<if>, <foreach> 等标签处理复杂查询
3. 整合 Spring Boot：用 @MapperScan 简化配置，告别手动创建 SqlSession
4. 了解连接池：HikariCP、Druid 等提升数据库性能
5. 对比其他技术：
   • 学 Go？试试 GORM
   • 做爬虫？用 Scrapy + MySQL 存储
   • 想全栈？前端学 Vue/React，后端继续深化 Spring

💬 最后送大家一句话：框架只是工具，理解原理才是核心。MyBatis 背后是 JDBC，JDBC 背后是 TCP/IP 和数据库协议。每一步都值得深挖。

---

希望这篇教程能帮你迈出 Java 后端开发的第一步！如果你觉得有用，欢迎点赞收藏。有任何问题，也欢迎在评论区留言交流。

我是小张，我们下篇教程见！