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

---

开篇：什么是MyBatis？它用来做什么？

在我们开发一个完整的Java应用程序时，经常需要把数据保存到数据库里。比如用户注册信息、商品信息等。传统的做法是使用JDBC（Java Database Connectivity）来操作数据库，但这往往代码量大且重复性高。

MyBatis 就是一个帮助我们更方便地进行数据库操作的框架。它不是完全隐藏SQL语句的“全自动”ORM工具（如Hibernate），而是介于手动写SQL和全自动之间的一个 半自动ORM框架。你可以把它看作是一个“SQL管家”，帮助你执行SQL语句，并处理与Java对象之间的转换。

简单来说：MyBatis = SQL + Java对象 的桥梁

---

环境准备：搭建你的第一个MyBatis开发环境

要使用MyBatis，你需要以下几个基础组件：

1. 安装JDK

请安装JDK 1.8及以上版本，并配置好环境变量 JAVA_HOME 和 PATH。

2. 安装IDE

推荐使用 IntelliJ IDEA 或 Eclipse。

3. 创建Maven项目

使用Maven可以帮助我们轻松管理依赖。以下是创建步骤：

• 打开IDE，新建Maven项目
• 输入Group Id（例如 com.example）
• 输入Artifact Id（例如 mybatis-demo）

完成后，你会看到项目结构中有一个 pom.xml 文件。

4. 添加MyBatis依赖

打开 pom.xml 文件，在 <dependencies> 中添加如下内容：

<!-- 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.28</version>
</dependency>

5. 准备数据库（MySQL为例）

假设我们使用本地MySQL数据库，请创建一个简单的数据库和表：

CREATE DATABASE mydb;

USE mydb;

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

插入一条测试数据：

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

---

核心概念：理解MyBatis的基础组成

学习MyBatis，只需要掌握以下几个核心概念：

1. SqlSessionFactoryBuilder

用于从配置文件中读取数据库连接信息，构建出 SqlSessionFactory。

2. SqlSessionFactory

工厂类，负责创建 SqlSession 对象。

3. SqlSession

核心接口，我们可以用它执行SQL语句、获取Mapper接口或类。

4. Mapper接口/映射器

这是一个接口，里面声明的方法会和XML中的SQL语句绑定。例如：

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

5. XML映射文件

这是MyBatis的灵魂所在。它将SQL语句与Java对象绑定。例如：

<mapper namespace="com.example.mapper.UserMapper">
    <select id="selectUser" resultType="com.example.model.User">
        SELECT * FROM user WHERE id = #{id}
    </select>
</mapper>

---

实战项目：一步步完成一个MyBatis小项目

接下来我们通过一个小项目——查询用户信息——来实践一下MyBatis的基本使用。

第一步：定义User实体类

创建 com.example.model.User.java

package com.example.model;

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; }

    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接口

创建 com.example.mapper.UserMapper.java

package com.example.mapper;

import com.example.model.User;

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

第三步：编写XML映射文件

在 resources 目录下创建 mappers/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">
    <select id="selectUser" resultType="com.example.model.User">
        SELECT * FROM user WHERE id = #{id}
    </select>
</mapper>

第四步：配置MyBatis全局配置文件

在 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/mydb?useSSL=false&amp;serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="yourpassword"/>
            </dataSource>
        </environment>
    </environments>

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

第五步：编写主程序运行查询

创建 com.example.Main.java

package com.example;

import com.example.mapper.UserMapper;
import com.example.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.InputStream;

public class Main {
    public static void main(String[] args) throws Exception {
        // 加载MyBatis配置文件
        String resource = "mybatis-config.xml";
        InputStream inputStream = Resources.getResourceAsStream(resource);
        SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);

        // 获取SqlSession
        try (SqlSession session = sqlSessionFactory.openSession()) {
            UserMapper mapper = session.getMapper(UserMapper.class);
            User user = mapper.selectUser(1); // 假设查ID为1的用户
            System.out.println(user);
        }
    }
}

运行结果示例：

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

恭喜！你已经成功完成了第一个MyBatis项目！

---

常见问题：新手容易遇到的问题与解决方法

Q1：报错：Cannot find the mapper XML file?

可能原因：

• XML文件路径不正确
• 没有在 mybatis-config.xml 中正确引用mapper文件

✅ 解决办法： 检查resource属性值是否准确，确保XML文件在 resources/mappers/ 路径下。

---

Q2：报错：Invalid bound statement (not found)?

可能原因：

• Mapper接口和XML文件的命名空间不一致
• XML中没有对应id的方法

✅ 解决办法： 核对 namespace 是否等于接口全类名，id 是否等于接口方法名。

---

Q3：连接不上数据库？

可能原因：

• 数据库服务未启动
• 配置中的用户名密码错误
• URL地址拼写错误

✅ 解决办法： 先尝试用Navicat或命令行连接数据库确认基本信息无误。

---

学习建议：下一步该学什么？

恭喜你完成了入门学习！下面是一些进阶方向：

✅ 推荐学习路径：

1. 掌握动态SQL

   • 使用 <if>、<foreach> 编写灵活SQL语句

2. 了解缓存机制

   • 系统级缓存和自定义缓存介绍

3. 学习注解方式

   • 不用XML也能实现映射（适合简单SQL）

4. 集成Spring框架

   • Spring Boot整合MyBatis才是企业开发的主流姿势

5. 多表联合查询 & 结果映射优化

   • 复杂业务场景下的实战技能

---

总结

本文带你从零开始，了解了MyBatis的核心功能，搭建了开发环境，并亲手完成了一个小型项目。整个过程注重实践与易懂性，旨在让你快速上手这个强大的Java持久层框架。

如果你是刚刚接触后端开发的新手，别担心，MyBatis并不难，只要你跟着练一遍，再自己动手改一改，就一定能掌握它的基本使用！

继续加油吧，未来的程序员！💪