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

大家好，我是你们的老朋友小码哥！在大厂做了3年Java后端开发，平时也在B站分享技术干货。最近收到很多私信，问我：“能不能出一期MyBatis的零基础教程？”——毕竟现在几乎每个Java后端项目都离不开它。

我当初学的时候也是一头雾水：什么“持久层”、“ORM”、“映射文件”……听起来像天书。但其实，MyBatis没那么难，只要用对方法，新手也能快速上手。今天这篇教程，我就带大家用一个完整的案例，从零开始搭建并理解MyBatis的核心用法。

💡 为什么学MyBatis？
虽然现在有Spring Boot + JPA、Hibernate等更“自动化”的方案，但MyBatis因其灵活、可控、性能好，依然是国内大厂（尤其是金融、电商、甚至区块链相关系统）的首选。比如你在做区块链数据落盘、交易记录存储时，往往需要精确控制SQL，这时候MyBatis就派上用场了！

---

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

简单说：MyBatis是一个帮助Java程序和数据库“对话”的工具。

• Java程序：写业务逻辑，处理用户请求
• 数据库（如MySQL）：存储数据（比如用户信息、订单记录）
• 问题：Java是面向对象的语言，数据库是表格结构，两者“语言不通”

这时候，MyBatis就充当了“翻译官”：

• 把Java对象 → 转成SQL语句 → 存入数据库
• 把数据库查询结果 → 转成Java对象 → 返回给程序

这个过程，就叫持久化（Persistence），而MyBatis就是专门干这事的持久层框架。

---

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

我们先装好“武器”，才能开工！你需要以下工具：

工具	版本建议	说明
JDK	8 或 11	Java运行环境
Maven	3.6+	项目依赖管理（也可用Gradle，但本文用Maven）
IDE	IntelliJ IDEA / Eclipse	推荐IDEA，对MyBatis支持更好
数据库	MySQL 5.7+	本地安装或Docker启动均可

步骤1：创建Maven项目

打开IDEA → New Project → Maven → 不勾选模板 → 命名如 mybatis-demo

步骤2：添加依赖（pom.xml）

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

⚠️ 注意：如果你用的是MySQL 8.0+，记得在连接字符串里加 ?serverTimezone=Asia/Shanghai，否则可能报时区错误！

步骤3：创建数据库和表

假设我们要做一个简单的“用户管理系统”，执行以下SQL：

CREATE DATABASE mybatis_demo;
USE mybatis_demo;

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

插入两条测试数据：

INSERT INTO user (username, email) VALUES 
('alice', 'alice@example.com'),
('bob', 'bob@example.com');

---

三、核心概念：用大白话讲清楚

1. SqlSessionFactory：MyBatis的“总控中心”

你可以把它想象成工厂，专门生产“数据库操作员”（SqlSession）。整个应用只需要一个。

2. SqlSession：执行SQL的“操作员”

每次要查数据、改数据，就找它。用完记得关闭（类似数据库连接）。

3. Mapper接口 + XML映射文件：SQL的“说明书”

• Mapper接口：定义方法，比如 User selectUserById(int id);
• XML文件：写具体的SQL语句，并告诉MyBatis如何把结果转成Java对象

✅ 这就是MyBatis的精髓：解耦SQL与Java代码。你不用在Java里拼字符串写SQL，维护起来超方便！

---

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

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

步骤1：创建Java实体类（User.java）

package com.example.entity;

public class User {
    private Integer id;
    private String username;
    private String email;

    // 必须要有无参构造（MyBatis反射需要）
    public User() {}

    // Getter 和 Setter
    public Integer getId() { return id; }
    public void setId(Integer id) { this.id = id; }
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }

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

步骤2：创建Mapper接口（UserMapper.java）

package com.example.mapper;

import com.example.entity.User;

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

步骤3：编写MyBatis配置文件（mybatis-config.xml）

在 src/main/resources 下创建：

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
  PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
  "https://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?serverTimezone=Asia/Shanghai"/>
        <property name="username" value="root"/>
        <property name="password" value="你的密码"/>
      </dataSource>
    </environment>
  </environments>

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

步骤4：编写Mapper XML文件（UserMapper.xml）

在 src/main/resources/mapper/ 目录下创建：

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
  PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
  "https://mybatis.org/dtd/mybatis-3-mapper.dtd">

<mapper namespace="com.example.mapper.UserMapper">
  <select id="selectUserById" resultType="com.example.entity.User" parameterType="int">
    SELECT id, username, email FROM user WHERE id = #{id}
  </select>
</mapper>

🔍 关键点解释：

• namespace：必须和Mapper接口全路径一致
• id：对应接口中的方法名
• resultType：查询结果要转成的Java类
• #{id}：安全的参数占位符（防SQL注入）

步骤5：写测试代码（TestMyBatis.java）

package com.example;

import com.example.entity.User;
import com.example.mapper.UserMapper;
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 TestMyBatis {
    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);
        }
    }
}

运行结果：

User{id=1, username='alice', email='alice@example.com'}

✅ 恭喜！你已经成功跑通第一个MyBatis程序！

---

五、常见问题 & 避坑指南

❌ 问题1：ClassNotFoundException: com.mysql.cj.jdbc.Driver

原因：MySQL驱动没加，或版本不对。

解决：确认pom.xml中已添加 mysql-connector-java 8.x 版本。

---

❌ 问题2：The error may exist in ... Unknown column 'xxx' in 'field list'

原因：Java属性名和数据库字段名不一致（比如Java用驼峰 userName，数据库用下划线 user_name）。

解决：在XML中使用 <resultMap> 显式映射，或开启MyBatis的自动驼峰转换：

<settings>
  <setting name="mapUnderscoreToCamelCase" value="true"/>
</settings>

---

❌ 问题3：Mapper method was not found

原因：

• XML的 namespace 写错了
• 方法名 id 和接口方法名不一致
• XML文件没被MyBatis扫描到（检查 mybatis-config.xml 中的 <mappers> 配置）

---

❌ 问题4：中文乱码

解决：在JDBC URL中加上字符集参数：

?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai

---

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

你现在掌握了MyBatis最基础的查询功能。接下来可以：

1. 扩展CRUD操作

• 尝试写 insert、update、delete 方法
• 注意：增删改操作后要调用 session.commit() 提交事务！

2. 学习动态SQL

MyBatis的 <if>、<foreach> 等标签能让你写出灵活的SQL，比如：

<select id="searchUsers" resultType="User">
  SELECT * FROM user
  WHERE 1=1
  <if test="username != null">
    AND username LIKE CONCAT('%', #{username}, '%')
  </if>
</select>

3. 整合Spring Boot（强烈推荐！）

实际项目中几乎不会单独用MyBatis，而是搭配Spring Boot：

• 添加 mybatis-spring-boot-starter 依赖
• 用 @MapperScan 自动扫描Mapper
• 配置写在 application.yml 中

4. 应用场景延伸

虽然本文是通用教程，但MyBatis在区块链后端项目中也很常见。例如：

• 将区块头、交易记录持久化到MySQL
• 查询某个地址的历史交易
• 统计链上数据指标

这些场景都需要高性能、可定制的SQL，MyBatis正好满足！

---

结语

看到这里，你已经跨过了MyBatis的第一道门槛。我当初学的时候，也是从这样一个小小的 selectUserById 开始的。技术没有捷径，但有正确的路径。

记住：多敲代码，少看视频；先跑通，再优化。遇到报错别慌，90%的问题都是配置或拼写错误。

如果你觉得这篇教程对你有帮助，欢迎去B站搜“小码哥Java”，给我点个关注！我会持续更新更多实战教程，包括Spring Boot、分布式、甚至区块链后端开发。

下期预告：《MyBatis + Spring Boot 实战：打造一个简易区块链浏览器后端》

加油，未来的后端工程师！🚀