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

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

在Java开发中，数据库操作是常见的需求。我们常常需要从数据库中读取数据、新增记录、更新信息或删除数据。而手动编写JDBC代码不仅复杂而且容易出错。

于是就有了很多ORM（对象关系映射）框架，它们的作用就是让开发者可以通过简单的Java对象和方法来操作数据库，而不必每次都写大量的SQL语句和处理结果集。

MyBatis是一个轻量级的持久层框架，它的特点是：

• 简洁
• 高性能
• 灵活（你可以自由编写SQL）

与传统的Hibernate等“全自动”ORM不同，MyBatis更偏向“半自动”。也就是说，你还是需要自己写SQL语句，但MyBatis会帮你完成SQL与Java对象之间的映射工作。

---

二、环境准备：搭建开发环境

在开始学习之前，你需要准备好以下开发环境：

1. 开发工具安装

• JDK 1.8及以上版本
• IDE（推荐IntelliJ IDEA 或 Eclipse）
• Maven 构建工具
• MySQL 数据库（或其他数据库如PostgreSQL也行）

如果你不熟悉如何安装这些工具，可以参考官方文档或者网上搜索“安装xxx + 版本号”的教程。

2. 创建Maven项目

使用IntelliJ IDEA创建一个Maven项目，结构大致如下：

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

3. 添加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.30</version>
</dependency>

保存后Maven会自动下载相关依赖。

---

三、核心概念讲解（通俗解释）

1. 什么是Mapper接口？

你可以把它理解为DAO接口的升级版，它定义了你要对数据库做的各种操作的方法名。

例如：

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

这个接口没有实现类，但我们可以在XML里或者注解中告诉MyBatis：“当调用selectUserById时，请执行这条SQL”。

2. 什么是Mapper XML文件？

这是MyBatis最经典的配置方式。你在这里写下所有SQL语句，并绑定到对应的Mapper接口方法上。

例如：UserMapper.xml中的内容可能是这样的：

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

其中：

• namespace对应的是Mapper接口的全路径类名
• id对应的是接口中的方法名
• #{id}代表传入的参数值

3. 什么是SqlSession？

它是MyBatis的核心对象之一，相当于你的“数据库连接+操作入口”。你可以通过它获取Mapper接口的实现类。

例如：

SqlSession session = sqlSessionFactory.openSession();
try {
    UserMapper mapper = session.getMapper(UserMapper.class);
    User user = mapper.selectUserById(1);
} finally {
    session.close();
}

4. 什么是MyBatis配置文件？

这就是我们在项目中使用的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/demo_db"/>
                <property name="username" value="root"/>
                <property name="password" value="123456"/>
            </dataSource>
        </environment>
    </environments>
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

---

四、实战项目：一步步搭建一个MyBatis小项目

步骤1：创建数据库和表

首先在MySQL中创建一个数据库和一张用户表：

CREATE DATABASE demo_db;

USE demo_db;

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

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

步骤2：创建User实体类

新建src/main/java/com/example/model/User.java：

package com.example.model;

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

    // Getter / Setter 省略
    public String toString() {
        return "User{" +
                "id=" + id +
                ", name='" + name + '\'' +
                ", email='" + email + '\'' +
                '}';
    }
}

步骤3：创建UserMapper接口

新建src/main/java/com/example/mapper/UserMapper.java：

package com.example.mapper;

import com.example.model.User;

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

步骤4：创建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">
    <select id="selectUserById" resultType="com.example.model.User">
        SELECT * FROM users WHERE id = #{id}
    </select>
</mapper>

步骤5：编写主程序测试一下

新建src/main/java/com/example/App.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 App {
    public static void main(String[] args) throws Exception {
        String resource = "mybatis-config.xml";
        InputStream inputStream = Resources.getResourceAsStream(resource);
        SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);

        try (SqlSession session = sqlSessionFactory.openSession()) {
            UserMapper mapper = session.getMapper(UserMapper.class);
            User user = mapper.selectUserById(1);
            System.out.println(user);
        }
    }
}

步骤6：运行程序看看效果

确保你的数据库已经启动，并且mybatis-config.xml里的数据库配置正确。

运行App类，你会看到控制台输出类似下面的内容：

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

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

---

五、常见问题解答（FAQ）

问题1：MyBatis总是报错说找不到Mapper接口？

答：请检查以下几点：

• 接口所在的包是否被mybatis-config.xml扫描到？
• Mapper XML文件是否正确配置了namespace字段？
• XML文件是否放在resource目录，并被正确引用？

问题2：SQL语句报错，比如找不到列？

答：通常是字段名拼写错误或大小写不一致导致的。注意：

• 数据库字段名要和resultMap或resultType匹配
• 如果字段名是user_name，Java属性建议写成userName并用@Results或resultMap进行映射

问题3：MyBatis无法连接数据库？

答：请检查：

• JDBC URL是否正确？
• 用户名和密码是否正确？
• 数据库服务是否已启动？

---

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

掌握了基本用法之后，你可以继续学习以下内容：

✅ 进阶知识点

• 使用注解代替XML文件（适合小型项目）
• 动态SQL（if、choose、foreach等）
• 多表联查与resultMap
• 分页查询
• 缓存机制（一级缓存、二级缓存）
• Spring Boot整合MyBatis

✅ 实践建议

• 搭建一个完整的CRUD系统
• 使用MyBatis Generator自动生成代码
• 结合Spring Boot构建Web项目

✅ 学习资源推荐

• MyBatis官方中文文档
• 《MyBatis从入门到精通》书籍
• B站或YouTube上的MyBatis实战视频

---

总结

MyBatis虽然不像Hibernate那样完全自动化，但它的灵活性让它更适合对SQL有一定要求的项目。作为初学者，掌握其基本原理和使用方式是非常有必要的。

希望这篇教程能帮助你迈入MyBatis的世界，开启Java后端开发的新旅程！

如需源码或其他资料，也可以留言交流哦～