MyBatis 到底能不能让 Java 操作数据库变简单？

大家好，我是一名从培训班“毕业”的前端转后端开发者。别笑！虽然现在在做后端，但我记得自己刚接触数据库操作时那种懵圈状态——JDBC 写得满屏 try-catch，连个查询都要写半页代码。后来接触到 MyBatis，才发现：原来 Java 操作数据库可以这么清爽！

今天这篇教程，就是专门写给和我当初一样完全零基础的朋友的。你不需要懂 ORM、DAO、事务这些词，只要会点 Java 基础就行。我会用最直白的话，带你从零搭建一个能读写数据库的小项目，并且告诉你：为什么 MyBatis 是新手入门 Java 持久层的最佳选择。

---

一、MyBatis 是什么？为什么选它？

简单说：MyBatis 是一个帮你把 Java 对象和数据库记录“连起来”的工具。你不用再手写一堆 JDBC 代码，它自动帮你执行 SQL、处理结果。

但市面上还有 Hibernate、Spring Data JPA 等框架，为啥推荐 MyBatis？我们来对比一下：

框架	学习难度	SQL 控制力	适合场景	新手友好度
MyBatis	⭐⭐	完全掌控	需要灵活写 SQL 的项目	⭐⭐⭐⭐
Hibernate	⭐⭐⭐⭐	自动生成	快速开发、CRUD 为主	⭐⭐
Spring Data JPA	⭐⭐⭐	抽象接口	标准化项目、微服务	⭐⭐⭐

💡 我当初学的时候，Hibernate 自动生成的 SQL 太“黑盒”，出问题根本不知道哪错了。而 MyBatis 让你看得见、改得了，特别适合新手理解底层逻辑。

另外，虽然你可能听说过 Embedding 和 RAG（检索增强生成） 这些 AI 术语，它们主要用在大模型上下文中，比如把文本转成向量（Embedding），再通过 RAG 从数据库查相关知识辅助回答。但注意：MyBatis 本身和 Embedding/RAG 没直接关系！不过，如果你未来要做 AI 应用，很可能需要用 MyBatis 把向量数据存到数据库里——这时候它的灵活 SQL 就派上用场了！

---

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

我们需要：

• JDK 8+
• Maven（包管理）
• MySQL 数据库
• IDE（推荐 IntelliJ IDEA）

步骤 1：创建 Maven 项目

打开终端，运行：

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

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

步骤 3：准备数据库

CREATE DATABASE mybatis_demo;
USE mybatis_demo;

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

INSERT INTO user (name, email) VALUES 
('小明', 'xiaoming@example.com'),
('小红', 'xiaohong@example.com');

---

三、核心概念：3 个文件搞定一切

MyBatis 的核心就三样东西：

1. 实体类（Entity）：Java 对象，对应数据库表
2. Mapper 接口：定义你要执行哪些数据库操作
3. XML 映射文件：写具体的 SQL 语句，告诉 MyBatis 怎么查/改数据

1. 实体类 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; }
    // ... 其他 getter/setter
}

2. Mapper 接口 UserMapper.java

package com.example.mapper;

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

public interface UserMapper {
    List<User> findAll();           // 查所有用户
    User findById(int id);          // 按 ID 查
    void insert(User user);         // 插入新用户
}

3. XML 映射文件 UserMapper.xml

放在 src/main/resources/com/example/mapper/ 目录下：

<?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="findAll" resultType="com.example.model.User">
        SELECT * FROM user
    </select>

    <select id="findById" parameterType="int" resultType="com.example.model.User">
        SELECT * FROM user WHERE id = #{id}
    </select>

    <insert id="insert" parameterType="com.example.model.User">
        INSERT INTO user (name, email) VALUES (#{name}, #{email})
    </insert>
</mapper>

🔍 注意：namespace 必须和 Mapper 接口全路径一致，id 要和方法名一致！

---

四、实战：跑起来你的第一个查询

配置 MyBatis（mybatis-config.xml）

在 src/main/resources/ 下新建：

<?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/mapper/UserMapper.xml"/>
    </mappers>
</configuration>

主程序 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;
import java.util.List;

public class App {
    public static void main(String[] args) throws Exception {
        // 1. 读取配置文件
        InputStream inputStream = Resources.getResourceAsStream("mybatis-config.xml");
        // 2. 创建工厂
        SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);
        // 3. 打开会话
        try (SqlSession session = sqlSessionFactory.openSession()) {
            // 4. 获取 Mapper
            UserMapper mapper = session.getMapper(UserMapper.class);
            
            // 5. 执行查询
            List<User> users = mapper.findAll();
            for (User u : users) {
                System.out.println("用户: " + u.getName() + ", 邮箱: " + u.getEmail());
            }

            // 6. 插入新用户（注意：默认不自动提交！）
            User newUser = new User();
            newUser.setName("小刚");
            newUser.setEmail("xiaogang@example.com");
            mapper.insert(newUser);
            session.commit(); // 手动提交事务！
        }
    }
}

⚠️ 新手常见坑：插入/更新后没生效？
原因：MyBatis 默认不自动提交事务！必须调用 session.commit()。

---

五、新手高频问题解答

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

• 检查 XML 文件路径是否和 namespace 匹配
• 确保 mybatis-config.xml 中 <mappers> 引用了正确的 XML 路径

Q2：中文乱码怎么办？

在数据库连接 URL 加上编码参数：

?useUnicode=true&characterEncoding=UTF-8

Q3：能不能不用 XML，直接写注解？

可以！比如：

@Select("SELECT * FROM user WHERE id = #{id}")
User findById(int id);

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

---

六、下一步怎么学？

1. 学 Spring Boot + MyBatis：实际项目基本都用这个组合，自动配置省心
2. 掌握动态 SQL：<if>, <foreach> 等标签让你写出灵活查询
3. 理解一级/二级缓存：提升性能的关键
4. 结合连接池（如 HikariCP）：生产环境必备

最后说一句：别怕犯错。我当初光是配置文件路径就搞错十几次。但只要你跑通第一个查询，后面就会越来越顺。MyBatis 给你的是“可控的自由”——既不用手写 JDBC 的繁琐，又能随时深入 SQL 优化。

现在，去你的电脑上敲一遍代码吧！遇到问题，欢迎回来再看这篇指南。