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

大家好，我是一名工作5年的后端开发工程师。在带新人的过程中，我发现很多人对数据库操作感到头疼——尤其是刚学完 Java 基础，一碰到“怎么把数据存到 MySQL”就卡住了。我自己当初学的时候也一样，光是 JDBC 的 try-catch 就写得头大。

所以今天，我想用最通俗的方式，带你轻松入门 MyBatis ——一个让 Java 操作数据库变得简单又安全的工具。这篇教程专为零基础设计，只要你装好了 Java 和 IDEA，就能跟着一步步动手实践。我会结合 Spring Boot 项目，分享真实的 开发心得，并强调一些重要的 安全意识。

---

一、MyBatis 是什么？为什么需要它？

简单说：MyBatis 是一个 Java 持久层框架，用来帮你把 Java 对象和数据库记录互相转换。

• 持久层：就是负责“把内存中的数据存到硬盘（比如数据库）”的那一层代码。
• 不用 MyBatis 怎么办？你得手写 JDBC：开连接、拼 SQL、处理异常、关资源……代码又长又容易出错。
• 用了 MyBatis：你只管写 SQL 和定义 Java 类，剩下的它自动搞定。

💡 我的开发心得：MyBatis 不会替你写 SQL，而是让你更优雅地写 SQL。这比全自动 ORM（如 Hibernate）更适合需要精细控制 SQL 的场景。

---

二、环境准备（5 分钟搞定）

我们用 Spring Boot + MyBatis + MySQL 搭建一个最小可运行项目。

1. 安装必要软件

软件	版本建议	说明
JDK	17 或 21	推荐使用 LTS 版本
Maven	3.8+	项目依赖管理
MySQL	8.0+	数据库
IntelliJ IDEA	最新版	开发 IDE

2. 创建 Spring Boot 项目

访问 https://start.spring.io，选择以下依赖：

• Spring Web
• MyBatis Framework
• MySQL Driver

点击“Generate”，下载 ZIP 并解压，用 IDEA 打开。

✅ 安全提示：不要在代码中硬编码数据库密码！后面我们会用配置文件管理。

3. 配置数据库

1. 在本地 MySQL 中创建数据库：

   CREATE DATABASE mybatis_demo CHARACTER SET utf8mb4;
   

2. 修改 application.yml（或 application.properties）：

   spring:
     datasource:
       url: jdbc:mysql://localhost:3306/mybatis_demo?useSSL=false&serverTimezone=UTC
       username: root
       password: your_password  # ⚠️ 实际项目请用环境变量或配置中心
       driver-class-name: com.mysql.cj.jdbc.Driver
   
   mybatis:
     configuration:
       map-underscore-to-camel-case: true  # 自动将下划线转驼峰（user_name → userName）
   

---

三、核心概念：3 个关键角色

MyBatis 的工作流程可以简化为：

Java 对象 ↔ Mapper 接口 ↔ SQL 映射文件 ↔ 数据库

1. 实体类（Entity）

对应数据库的一张表。例如用户表：

public class User {
    private Long id;
    private String name;
    private String email;
    
    // getter / setter 省略（可用 Lombok 简化）
}

2. Mapper 接口

定义操作数据库的方法，不用写实现类！

@Mapper
public interface UserMapper {
    List<User> findAll();
    User findById(Long id);
    void insert(User user);
    void update(User user);
    void delete(Long id);
}

🔒 安全意识：所有数据库操作都应通过接口定义，避免在业务代码里直接拼接 SQL。

3. SQL 映射文件（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.demo.mapper.UserMapper">
    <select id="findAll" resultType="com.example.demo.entity.User">
        SELECT * FROM user
    </select>

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

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

    <update id="update" parameterType="com.example.demo.entity.User">
        UPDATE user SET name=#{name}, email=#{email} WHERE id=#{id}
    </update>

    <delete id="delete" parameterType="long">
        DELETE FROM user WHERE id = #{id}
    </delete>
</mapper>

📌 注意：namespace 必须是 Mapper 接口的全限定名！

同时，在 application.yml 中注册映射文件路径：

mybatis:
  mapper-locations: classpath:mapper/*.xml

---

四、实战：完成一个用户管理小项目

我们现在实现一个简单的 REST API：增删改查用户。

步骤 1：创建数据库表

CREATE TABLE user (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(100) NOT NULL UNIQUE
);

步骤 2：编写 Service 层（可选但推荐）

虽然可以直接调用 Mapper，但为了代码分层清晰，建议加一层 Service：

@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;

    public List<User> getAllUsers() {
        return userMapper.findAll();
    }

    public User getUserById(Long id) {
        return userMapper.findById(id);
    }

    public void createUser(User user) {
        userMapper.insert(user);
    }

    public void updateUser(User user) {
        userMapper.update(user);
    }

    public void deleteUser(Long id) {
        userMapper.delete(id);
    }
}

步骤 3：编写 Controller

@RestController
@RequestMapping("/users")
public class UserController {
    @Autowired
    private UserService userService;

    @GetMapping
    public List<User> list() {
        return userService.getAllUsers();
    }

    @GetMapping("/{id}")
    public User detail(@PathVariable Long id) {
        return userService.getUserById(id);
    }

    @PostMapping
    public void create(@RequestBody User user) {
        userService.createUser(user);
    }

    @PutMapping
    public void update(@RequestBody User user) {
        userService.updateUser(user);
    }

    @DeleteMapping("/{id}")
    public void delete(@PathVariable Long id) {
        userService.deleteUser(id);
    }
}

步骤 4：启动测试

1. 启动 Spring Boot 应用
2. 用 Postman 或 curl 测试：

   # 添加用户
   curl -X POST http://localhost:8080/users \
        -H "Content-Type: application/json" \
        -d '{"name":"张三","email":"zhangsan@example.com"}'
   
   # 查询所有
   curl http://localhost:8080/users
   

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

---

五、新手常见问题解答

Q1：为什么报错 “Invalid bound statement (not found)”？

原因：Mapper 接口方法名和 XML 中的 id 不一致，或者 namespace 写错了。

解决：

• 检查 XML 的 namespace 是否等于接口全类名
• 检查方法名是否和 <select id="xxx"> 中的 id 一致

Q2：中文插入数据库变成乱码？

原因：数据库或连接未使用 UTF-8。

解决：

• 创建数据库时指定 CHARACTER SET utf8mb4
• JDBC URL 加上 ?useUnicode=true&characterEncoding=utf8

Q3：如何防止 SQL 注入？

重点来了！这是安全意识的核心。

MyBatis 默认使用 #{} 占位符，会预编译 SQL，天然防注入。
❌ 错误写法（危险！）：

<!-- 不要用 ${} 拼接用户输入！ -->
SELECT * FROM user WHERE name = '${name}'

✅ 正确写法：

SELECT * FROM user WHERE name = #{name}

🛡️ 开发心得：永远不要信任前端传来的任何参数！用 #{} 而不是 ${}。

---

六、学习建议与下一步

你现在已经掌握了 MyBatis 的基础用法。但别止步于此！

推荐学习路径：

1. 进阶 SQL：学习动态 SQL（<if>, <foreach> 等）
2. 关联查询：一对一、一对多的映射（<resultMap>）
3. 分页插件：集成 PageHelper 实现分页
4. 事务管理：理解 @Transactional 的作用
5. 与 Spring Boot 深度整合：使用注解版 Mapper（省去 XML）

避坑指南：

• ❌ 不要在 Mapper XML 里写业务逻辑
• ❌ 不要返回 Map 代替实体类（除非万不得已）
• ✅ 实体类字段尽量和数据库列名保持驼峰/下划线对应
• ✅ 复杂查询先在 MySQL 客户端验证 SQL 正确性

---

结语

MyBatis 的魅力在于“简单但不失控制力”。作为后端开发者，掌握它能让你在项目中既高效又安全地操作数据库。

这篇文章源于我带实习生的真实经历——希望你能少走弯路，快速上手。如果你成功跑通了示例，不妨在评论区留言“Hello MyBatis！” 😄

技术分享的意义，就是让后来者站在我们的肩膀上看得更远。加油，未来的架构师！

项目完整代码可参考 GitHub 搜索 “springboot-mybatis-demo”，记得 star 支持开源！