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

作者注：作为一位维护过多个开源项目的后端开发者，我经常收到初学者的私信：“老师，MyBatis到底怎么用？” 回想起我当初学的时候，也是一头雾水——配置文件看不懂、SQL写在哪都不知道。今天，我就用最简单的方式，带你从零开始掌握 MyBatis。无论你是刚学完 Java 基础，还是正在做课程设计，这篇教程都能帮你快速上手。

---

一、MyBatis 是什么？它能做什么？

MyBatis 是一个 Java 持久层框架。别被“持久层”吓到——它其实就是帮你的 Java 程序 和数据库打交道 的工具。

想象一下：

• 你写了一个电商 产品 管理系统（比如后台管理商品）
• 用户在 前端 页面点击“添加商品”
• 你的 Java 后端需要把这条商品信息存进 MySQL 数据库

没有 MyBatis 时，你要写大量样板代码（比如 Connection、PreparedStatement），非常繁琐。
有了 MyBatis，你只需关注 SQL 语句本身 和 Java 对象，它会自动帮你完成数据库操作！

💡 小贴士：虽然现在很多人用 Spring Boot + MyBatis，但今天我们先学 纯 MyBatis，打好基础更重要。

---

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

我们需要以下工具：

工具	版本建议	说明
JDK	8 或 11	Java 运行环境
Maven	3.6+	项目依赖管理（也可用 Gradle）
IDE	IntelliJ IDEA / Eclipse	推荐 IDEA，对 MyBatis 支持更好
数据库	MySQL 5.7+	也可以用 H2（内存数据库）做测试

步骤 1：创建 Maven 项目

打开你的 IDE，新建一个 Maven 项目（不选 archetype），项目结构如下：

mybatis-demo/
├── src/
│   └── main/
│       ├── java/
│       └── resources/
└── pom.xml

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

⚠️ 注意：如果你用的是 Go 语言开发者常用的 Goland，那不能运行 Java 项目！请务必使用 Java IDE。

---

三、核心概念：3 个关键角色

MyBatis 的工作原理很简单，就靠 3 个东西：

角色	作用	类比
Mapper 接口	定义操作数据库的方法	像“菜单”，告诉你能点什么菜
XML 映射文件	写具体的 SQL 语句	像“厨房”，真正做菜的地方
SqlSession	执行 SQL 的“执行器”	像“服务员”，帮你下单并上菜

🗣️ 我当初学的时候总搞混 Mapper 和 XML 的关系。记住：接口定义方法，XML 写 SQL，MyBatis 自动把它们连起来！

---

四、实战项目：做一个“产品”管理系统

我们来做一个超简单的功能：查询所有商品信息。

步骤 1：建表（MySQL）

CREATE DATABASE mybatis_demo;
USE mybatis_demo;

CREATE TABLE product (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100),
    price DECIMAL(10, 2)
);

INSERT INTO product (name, price) VALUES
('iPhone 15', 5999.00),
('MacBook Pro', 12999.00);

步骤 2：创建 Product 实体类

// src/main/java/com/example/model/Product.java
package com.example.model;

public class Product {
    private Integer id;
    private String name;
    private Double price;

    // 必须有无参构造函数（MyBatis 需要）
    public Product() {}

    // getter 和 setter（IDE 可自动生成）
    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 Double getPrice() { return price; }
    public void setPrice(Double price) { this.price = price; }

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

步骤 3：创建 Mapper 接口

// src/main/java/com/example/mapper/ProductMapper.java
package com.example.mapper;

import com.example.model.Product;
import java.util.List;

public interface ProductMapper {
    List<Product> findAll(); // 查询所有产品
}

步骤 4：编写 XML 映射文件

在 src/main/resources 下创建目录：com/example/mapper/（必须和接口包名一致！）

<!-- src/main/resources/com/example/mapper/ProductMapper.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.ProductMapper">
    <!-- id 对应接口方法名，resultType 是返回类型 -->
    <select id="findAll" resultType="com.example.model.Product">
        SELECT id, name, price FROM product
    </select>
</mapper>

🔍 注意：namespace 必须是 完整接口类名，id 必须和 方法名一致！

步骤 5：配置 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="your_password"/>
            </dataSource>
        </environment>
    </environments>

    <!-- 注册 Mapper XML 文件 -->
    <mappers>
        <mapper resource="com/example/mapper/ProductMapper.xml"/>
    </mappers>
</configuration>

步骤 6：写主程序测试

// src/main/java/com/example/App.java
package com.example;

import com.example.mapper.ProductMapper;
import com.example.model.Product;
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;
import java.util.List;

public class App {
    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 接口
            ProductMapper mapper = session.getMapper(ProductMapper.class);
            
            // 5. 调用方法
            List<Product> products = mapper.findAll();
            
            // 6. 输出结果
            for (Product p : products) {
                System.out.println(p);
            }
        }
    }
}

运行结果：

Product{id=1, name='iPhone 15', price=5999.0}
Product{id=2, name='MacBook Pro', price=12999.0}

🎉 恭喜！你已经成功用 MyBatis 查询了数据库！

---

五、新手常见问题解答

❓ Q1：为什么报错 “Mapper method not found”？

原因：XML 中的 id 和接口方法名不一致，或者 namespace 写错了。
解决：检查拼写，确保完全匹配（包括大小写）。

❓ Q2：实体类属性和数据库字段名不一样怎么办？

比如数据库是 product_name，Java 是 productName。
方案：在 XML 中用 resultMap 显式映射：

<resultMap id="ProductMap" type="Product">
    <id property="id" column="id"/>
    <result property="name" column="product_name"/>
    <result property="price" column="price"/>
</resultMap>

<select id="findAll" resultMap="ProductMap">
    SELECT id, product_name, price FROM product
</select>

❓ Q3：能不能不用 XML，直接在接口里写 SQL？

可以！用 @Select 注解：

public interface ProductMapper {
    @Select("SELECT id, name, price FROM product")
    List<Product> findAll();
}

但复杂 SQL（比如多表关联）还是推荐用 XML，更清晰。

---

六、学习建议与下一步

✅ 学习路径推荐

1. 先掌握基础 CRUD：增删改查（Insert/Update/Delete/Select）
2. 学习动态 SQL：<if>、<foreach> 等标签（处理条件查询）
3. 集成 Spring Boot：实际项目中几乎都用 mybatis-spring-boot-starter
4. 了解一级/二级缓存：提升性能的关键

🚫 避坑指南

• 不要硬编码 SQL：始终用参数化查询，防止 SQL 注入
• 记得关闭 SqlSession：用 try-with-resources 自动关闭
• Mapper 接口不要加 @Repository：纯 MyBatis 不需要 Spring 注解

🔗 延伸阅读

• MyBatis 官方文档（中文）
• 《MyBatis 从入门到精通》（书籍）
• GitHub 上搜索 mybatis-example 看开源项目

---

结语

这篇 技术分享 虽然只讲了查询，但 MyBatis 的核心思想已经传达给你了：解耦 SQL 与 Java 代码，让数据库操作更简单。

无论你是想做毕业设计，还是准备面试，掌握 MyBatis 都是 Java 后端开发的必备技能。下一步，你可以尝试添加“新增产品”功能，练习 <insert> 标签。

最后提醒：前端负责展示，后端（比如你）负责数据逻辑，而 MyBatis 就是你和数据库之间的“翻译官”。至于 Go 语言？那是另一个世界的故事啦 😄

动手试试吧！遇到问题，欢迎在评论区留言交流。