零基础也能学会：MyBatis 入门实战指南

大家好，我是你们的技术培训负责人。每年我都会带几十位刚毕业的应届生进入后端开发的世界。我注意到，很多同学在学习 Java 持久层框架时，面对 MyBatis 总是既期待又忐忑。其实我当初学的时候也一样——看到 XML、SQL 映射、Session 等一堆术语就头大。但别担心，只要跟着动手做一遍，你会发现 MyBatis 比你想象中友好得多！

这篇文章专为完全零基础的同学设计，哪怕你只写过“Hello World”，也能一步步搭建起自己的第一个 MyBatis 项目。我们会用最直白的语言、最实用的代码，带你从零走到能操作数据库。

---

为什么后端开发需要 MyBatis？

在 Java 后端开发中，我们经常要和数据库打交道——比如保存用户信息、查询订单记录。传统做法是用 JDBC（Java Database Connectivity）直接写 SQL，但这样代码冗长、容易出错，还难以维护。

MyBatis 就是一个帮你简化数据库操作的框架。它把 Java 对象和 SQL 语句“自动配对”，让你专注业务逻辑，而不是反复写 Connection、PreparedStatement 这些样板代码。

📌 小贴士：虽然这篇文章讲的是 Java 框架，但作为全栈开发者，你也可能用到 JavaScript 前端调用后端接口。理解 MyBatis 能让你更清楚后端数据是怎么来的！

---

第一步：搭建开发环境

我们使用最主流的组合：Java + Maven + MySQL + MyBatis

所需工具清单

工具	版本建议	说明
JDK	11 或 17	Java 开发环境
Maven	3.6+	项目依赖管理
MySQL	5.7+ 或 8.0	数据库
IDE	IntelliJ IDEA / VS Code	推荐 IDEA，对 Java 支持更好

创建项目（Maven 方式）

1. 打开终端，执行：

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

2. 进入项目目录：

cd mybatis-demo

3. 编辑 pom.xml，添加 MyBatis 和 MySQL 依赖：

<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</td>
    </dependency>
    
    <!-- 单元测试（可选） -->
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.13.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

4. 刷新 Maven 项目（IDEA 中右键 → Reload Projects）

---

第二步：理解 MyBatis 的核心概念

别被术语吓到！记住这三个关键词就够了：

1. Mapper（映射器）

一个接口，定义你要执行的数据库操作，比如 getUserById(int id)。

2. SQL 映射文件（XML）

一个 .xml 文件，里面写真实的 SQL 语句，并告诉 MyBatis 如何把结果转成 Java 对象。

3. SqlSession

MyBatis 的“工作窗口”，通过它调用 Mapper 方法，执行 SQL。

💡 我当初学的时候总混淆 Mapper 接口和 XML 文件的关系。其实很简单：接口定义“做什么”，XML 定义“怎么做”。

---

第三步：动手实战——实现用户查询功能

我们来做一个最简单的功能：根据 ID 查询用户信息。

步骤 1：创建数据库和表

在 MySQL 中执行：

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 
('张三', 'zhangsan@example.com'),
('李四', 'lisi@example.com');

步骤 2：配置 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"
  "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?useSSL=false&amp;serverTimezone=UTC"/>
        <property name="username" value="root"/>
        <property name="password" value="your_password"/>
      </dataSource>
    </environment>
  </environments>
  
  <!-- 注册 Mapper XML 文件 -->
  <mappers>
    <mapper resource="UserMapper.xml"/>
  </mappers>
</configuration>

⚠️ 注意：把 your_password 替换成你的 MySQL 密码！

步骤 3：创建 User 实体类

在 src/main/java/com/example 下新建 User.java：

package com.example;

public class User {
    private int id;
    private String name;
    private String email;
    
    // 必须有无参构造函数（MyBatis 需要）
    public User() {}
    
    // 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 + "'}";
    }
}

步骤 4：编写 Mapper 接口

新建 UserMapper.java：

package com.example;

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

步骤 5：编写 SQL 映射文件（UserMapper.xml）

在 src/main/resources 下新建 UserMapper.xml：

<?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.UserMapper">
  <select id="selectUserById" resultType="com.example.User" parameterType="int">
    SELECT id, name, email FROM user WHERE id = #{id}
  </select>
</mapper>

🔍 关键点解释：

• namespace 必须和 Mapper 接口全路径一致
• id 对应接口方法名
• #{id} 是参数占位符，MyBatis 会自动替换

步骤 6：编写测试代码

修改 App.java（或新建测试类）：

package com.example;

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 {
        // 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, name='张三', email='zhangsan@example.com'}

恭喜！你已经成功运行了第一个 MyBatis 程序！

---

新手常见问题解答

❓ 为什么报 “Mapper not found” 错误？

• 检查 mybatis-config.xml 中是否注册了 XML 文件
• 检查 XML 的 namespace 是否和接口全路径一致
• 检查 XML 文件是否放在 resources 目录下（Maven 会自动打包）

❓ 参数传递多个怎么办？

可以用 @Param("name") 注解：

User selectUser(@Param("id") int id, @Param("name") String name);

XML 中用 #{id} 和 #{name} 引用。

❓ 能不用 XML 吗？

可以！MyBatis 支持注解方式（适合简单 SQL）：

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

但复杂 SQL 还是推荐 XML，更清晰。

---

下一步学习建议

1. 掌握 CRUD 全套操作：尝试实现插入、更新、删除
2. 学习动态 SQL：<if>、<foreach> 等标签处理条件查询
3. 集成 Spring Boot：实际项目中 MyBatis 通常和 Spring 一起用
4. 理解一级/二级缓存：提升性能的关键机制

🌟 最后提醒：不要死记语法！MyBatis 的核心思想是 “SQL 与 Java 分离”。只要你理解了这个理念，剩下的都是细节。

---

希望这篇教程能帮你迈出后端开发的第一步。如果你正在学 JavaScript 前端，不妨试着用 Fetch 或 Axios 调用你刚写的 Java 接口——前后端联调的成就感，绝对值得你继续深入！

有问题随时留言，我会一一解答。加油，未来的后端工程师！