在 Spring Boot 中使用 MyBatis 的 XML 文件编写 SQL 语句详解

前言

在现代 Java Web 开发中，Spring Boot 和 MyBatis 是两个非常流行的技术框架。它们的结合使得数据库操作变得更加简洁和高效。本文将详细介绍如何在 Spring Boot 项目中使用 MyBatis 的 XML 文件来编写 SQL 语句，包括配置、代码结构、SQL 编写技巧以及最佳实践等内容。

一、什么是 MyBatis？

MyBatis 是一个基于 Java 的持久层框架，它允许开发者通过 XML 或注解方式编写 SQL，并与 Java 对象进行映射（ORM）。相比 Hibernate 等全自动 ORM 框架，MyBatis 更加灵活，适用于需要对 SQL 进行精细控制的场景。

二、Spring Boot + MyBatis 的基本架构

典型的 Spring Boot + MyBatis 项目结构如下：

src
└── main
    ├── java
    │   └── com.example.demo
    │       ├── DemoApplication.java
    │       ├── controller
    │       ├── service
    │       ├── mapper
    │       └── model
    └── resources
        ├── application.properties
        └── mapper
            └── UserMapper.xml

其中 mapper 包下的接口与 resources/mapper 下的 XML 文件是一一对应的。

⚙️ 三、搭建环境

1. 添加依赖（Maven）

<dependencies>
    <!-- Spring Boot Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>

    <!-- MyBatis Starter -->
    <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>3.0.3</version>
    </dependency>

    <!-- MySQL 驱动 -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.33</version>
    </dependency>
</dependencies>

2. 配置数据库连接（application.properties）

spring.datasource.url=jdbc:mysql://localhost:3306/demo_db?useSSL=false&serverTimezone=UTC
spring.datasource.username=root
spring.datasource.password=123456
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

mybatis.mapper-locations=classpath:mapper/**/*.xml
mybatis.type-aliases-package=com.example.demo.model

四、编写 Mapper 接口和 XML 文件

1. 创建实体类（Model）

package com.example.demo.model;

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

    // Getter and Setter
}

2. 创建 Mapper 接口

package com.example.demo.mapper;

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

public interface UserMapper {
    List<User> getAllUsers();
    User getUserById(Long id);
    void insertUser(User user);
    void updateUser(User user);
    void deleteUserById(Long id);
}

3. 创建 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="getAllUsers" resultType="User">
        SELECT * FROM users
    </select>

    <!-- 根据ID查询用户 -->
    <select id="getUserById" parameterType="long" resultType="User">
        SELECT * FROM users WHERE id = #{id}
    </select>

    <!-- 插入用户 -->
    <insert id="insertUser">
        INSERT INTO users (name, email)
        VALUES (#{name}, #{email})
    </insert>

    <!-- 更新用户 -->
    <update id="updateUser">
        UPDATE users
        SET name = #{name}, email = #{email}
        WHERE id = #{id}
    </update>

    <!-- 删除用户 -->
    <delete id="deleteUserById">
        DELETE FROM users WHERE id = #{id}
    </delete>

</mapper>

五、动态 SQL 使用详解

MyBatis 提供了强大的动态 SQL 功能，常见标签有 <if>、<choose>、<when>、<set>、<where>、<foreach> 等。

示例：根据条件查询用户

Mapper 接口：

List<User> searchUsers(@Param("name") String name, @Param("email") String email);

XML 文件：

<select id="searchUsers" resultType="User">
    SELECT * FROM users
    <where>
        <if test="name != null and name != ''">
            AND name LIKE CONCAT('%', #{name}, '%')
        </if>
        <if test="email != null and email != ''">
            AND email LIKE CONCAT('%', #{email}, '%')
        </if>
    </where>
</select>

示例：批量插入用户

<insert id="batchInsert">
    INSERT INTO users (name, email)
    VALUES
    <foreach collection="list" item="user" separator=",">
        (#{user.name}, #{user.email})
    </foreach>
</insert>

六、测试 MyBatis SQL

可以创建一个简单的 Service 层调用 Mapper 并打印结果。

Service 示例：

@Service
public class UserService {

    @Autowired
    private UserMapper userMapper;

    public void printAllUsers() {
        List<User> users = userMapper.getAllUsers();
        users.forEach(System.out::println);
    }
}

Controller 示例：

@RestController
@RequestMapping("/users")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping
    public void getUsers() {
        userService.printAllUsers();
    }
}

七、MyBatis XML 常见标签总结

八、最佳实践建议

1. 命名规范统一：XML 文件名与 Mapper 接口名保持一致。
2. SQL 与业务逻辑分离：将 SQL 放在 XML 中，便于维护和审计。
3. 使用 <where> 和 <set> 避免语法错误。
4. 合理使用 <resultMap> 映射复杂对象关系。
5. 开启 MyBatis 日志输出，方便调试：

   logging:
     level:
       com.example.demo.mapper: debug
   

九、扩展功能推荐

• PageHelper 分页插件：轻松实现分页查询。
• MyBatis Generator：自动生成 Model、Mapper 和 XML 文件。
• MyBatis Plus：增强型 MyBatis 工具包，简化 CRUD 操作。

十、结语

在 Spring Boot 中使用 MyBatis 的 XML 方式编写 SQL，不仅保留了 SQL 的灵活性，还利用了框架提供的强大映射能力。通过本篇博客，你已经掌握了从项目搭建到 SQL 编写的完整流程，以及动态 SQL 的高级用法。希望你在实际项目中能够熟练运用这些知识，写出更优雅、高效的数据库操作代码！