侧边栏壁纸
博主头像
洋洋的技术笔记

行动起来,活在当下

  • 累计撰写 25 篇文章
  • 累计创建 3 个标签
  • 累计收到 0 条评论

目 录CONTENT

文章目录

Spring Boot整合MyBatis最佳实践

洋洋的技术笔记
2026-11-22 / 0 评论 / 0 点赞 / 4 阅读 / 0 字

Spring Boot整合MyBatis最佳实践

MyBatis 把 SQL 的控制权留给开发者,但“能查出数据”只是起点。稳定的项目还需要清晰的 Mapper 边界、可维护的 SQL 映射、明确的事务范围,以及覆盖真实数据库行为的测试。

上一篇《Spring Boot跨域处理方案》解决了前后端请求链中的跨域问题。本文进入数据访问层,以任务管理功能为例,完成 Spring Boot 与 MyBatis 的整合,并讨论 XML 映射、动态查询、分页、事务和常见性能问题。

环境说明:示例使用 Java 17、Spring Boot 3.x、MyBatis Spring Boot Starter 3.0.x、Maven 和 H2 数据库。H2 用于隔离运行示例,生产项目应使用实际数据库验证 SQL、索引和分页行为。示例中的领域对象是任务 Task,不包含用户权限等完整业务实现。


一、明确 MyBatis 在项目中的职责

MyBatis 负责 SQL 与 Java 对象之间的映射,不负责替我们决定业务规则。推荐保持以下边界:

  • Controller 处理 HTTP 参数和响应;

  • Service 组织业务流程与事务;

  • Mapper 只描述数据访问操作;

  • XML 或注解编写 SQL,显式处理字段映射;

  • 数据库约束与索引保证数据完整性和查询效率。

不要把大量业务判断写进 XML,也不要为了少一个 Service 方法而从 Controller 直接调用 Mapper。简单项目可以减少仪式,但层级职责不能随查询复杂度一起失控。


二、引入依赖并配置数据源

在 Spring Boot 3.x 项目中加入 MyBatis Starter:

<properties>
    <java.version>17</java.version>
    <mybatis-spring-boot.version>3.0.4</mybatis-spring-boot.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>${mybatis-spring-boot.version}</version>
    </dependency>
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

mybatis-spring-boot-starter 应与目标 Spring Boot 大版本匹配,不要直接混用面向 Spring Boot 2 的旧 Starter。

本地示例配置:

spring:
  datasource:
    url: jdbc:h2:mem:taskdb;MODE=MySQL;DB_CLOSE_DELAY=-1
    driver-class-name: org.h2.Driver
    username: sa
    password:
  sql:
    init:
      mode: always

mybatis:
  mapper-locations: classpath:/mappers/*.xml
  configuration:
    map-underscore-to-camel-case: true

map-underscore-to-camel-case 能把 created_at 映射到 createdAt,但它不能代替所有 resultMap。字段含义不同、联表查询或构造复杂对象时,应显式声明映射。

生产配置不要把数据库密码提交到仓库,也不要为了排查问题长期开启完整 SQL 参数日志。


三、建立表结构与领域对象

示例表包含主键、标题、状态和时间字段:

CREATE TABLE task (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    title VARCHAR(100) NOT NULL,
    status VARCHAR(20) NOT NULL,
    created_at TIMESTAMP NOT NULL
);

对应 Java 对象:

package com.example.task;

import java.time.LocalDateTime;

public class Task {
    private Long id;
    private String title;
    private String status;
    private LocalDateTime createdAt;

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
    public String getStatus() { return status; }
    public void setStatus(String status) { this.status = status; }
    public LocalDateTime getCreatedAt() { return createdAt; }
    public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; }
}

真实项目还可以区分数据库实体、接口 DTO 和领域对象。并非每张表都必须机械地拆出多层模型,但不要把数据库实体直接当作所有外部接口的默认返回类型。

数据库字段应设置长度和非空约束,状态字段在业务层校验允许值。仅靠页面下拉框不能防止非法数据写入。


四、Mapper 接口与 XML 映射

Mapper 接口定义数据访问契约:

package com.example.task;

import java.util.List;
import java.util.Optional;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

@Mapper
public interface TaskMapper {
    int insert(Task task);

    Optional<Task> findById(long id);

    List<Task> search(
            @Param("status") String status,
            @Param("keyword") String keyword,
            @Param("limit") int limit,
            @Param("offset") long offset
    );

    long count(@Param("status") String status, @Param("keyword") String keyword);

    int markCompleted(@Param("id") long id);
}

@Param 给参数提供稳定名称,XML 中不要依赖编译器是否保留方法参数名。

src/main/resources/mappers/TaskMapper.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.task.TaskMapper">
    <resultMap id="taskMap" type="com.example.task.Task">
        <id property="id" column="id"/>
        <result property="title" column="title"/>
        <result property="status" column="status"/>
        <result property="createdAt" column="created_at"/>
    </resultMap>

    <sql id="taskColumns">id, title, status, created_at</sql>

    <insert id="insert" parameterType="com.example.task.Task"
            useGeneratedKeys="true" keyProperty="id">
        INSERT INTO task (title, status, created_at)
        VALUES (#{title}, #{status}, #{createdAt})
    </insert>

    <select id="findById" resultMap="taskMap">
        SELECT <include refid="taskColumns"/>
        FROM task
        WHERE id = #{id}
    </select>

    <sql id="searchCondition">
        <where>
            <if test="status != null and !status.isBlank()">
                AND status = #{status}
            </if>
            <if test="keyword != null and !keyword.isBlank()">
                AND title LIKE CONCAT('%', #{keyword}, '%')
            </if>
        </where>
    </sql>

    <select id="search" resultMap="taskMap">
        SELECT <include refid="taskColumns"/>
        FROM task
        <include refid="searchCondition"/>
        ORDER BY created_at DESC, id DESC
        LIMIT #{limit} OFFSET #{offset}
    </select>

    <select id="count" resultType="long">
        SELECT COUNT(*) FROM task
        <include refid="searchCondition"/>
    </select>

    <update id="markCompleted">
        UPDATE task SET status = 'COMPLETED'
        WHERE id = #{id}
    </update>
</mapper>

这里复用查询条件,保证列表与总数一致;排序增加 id,避免相同时间戳下顺序不稳定。#{} 使用预编译参数,不要把用户输入通过 ${} 拼进 SQL。

${} 只适合极少数无法参数化的可信标识符,例如经过服务器端白名单校验的排序列。关键字、状态、ID 等普通值都必须使用 #{}。


五、Service 负责参数处理与事务边界

数据访问层不应该猜测空关键字代表什么,也不应该接收未经限制的页大小。把这些规则放在 Service:

package com.example.task;

import java.time.LocalDateTime;
import java.util.List;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class TaskService {
    private final TaskMapper taskMapper;

    public TaskService(TaskMapper taskMapper) {
        this.taskMapper = taskMapper;
    }

    @Transactional
    public Task create(String title) {
        String normalizedTitle = title == null ? "" : title.trim();
        if (normalizedTitle.isEmpty()) {
            throw new IllegalArgumentException("标题不能为空");
        }
        Task task = new Task();
        task.setTitle(normalizedTitle);
        task.setStatus("TODO");
        task.setCreatedAt(LocalDateTime.now());
        taskMapper.insert(task);
        return task;
    }

    @Transactional(readOnly = true)
    public List<Task> search(String status, String keyword, int page, int size) {
        if (page < 1 || size < 1 || size > 100) {
            throw new IllegalArgumentException("分页参数不合法");
        }
        String normalizedStatus = normalize(status);
        String normalizedKeyword = normalize(keyword);
        long offset = (long) (page - 1) * size;
        return taskMapper.search(normalizedStatus, normalizedKeyword, size, offset);
    }

    @Transactional
    public boolean complete(long id) {
        return taskMapper.markCompleted(id) == 1;
    }

    private String normalize(String value) {
        if (value == null || value.isBlank()) {
            return null;
        }
        return value.trim();
    }
}

事务应围绕完整业务用例,而不是默认套在每个 Mapper 方法上。readOnly = true 是只读意图与优化提示,不等于数据库权限控制;真正的数据安全仍依赖账号权限和约束。

还要避免同类内部方法自调用导致事务代理不生效,并确认异常回滚规则符合业务预期。涉及多个外部系统时,一个本地数据库事务不能提供跨系统原子性。


六、分页不能只写一个 LIMIT

分页接口通常同时需要列表与总数,因此要确保 search 和 count 使用完全相同的过滤条件。页大小必须有上限,避免客户端请求超大结果集。

深分页中的大 OFFSET 仍可能让数据库扫描并丢弃大量记录。数据量增长后,可以评估基于稳定排序键的游标分页,例如上一页最后一条记录的 (created_at, id)。游标方案需要唯一、稳定的排序,不适合所有后台页面,不必为了“高级”而提前替换普通分页。

如果引入 PageHelper 等分页插件,应确认版本兼容性、线程上下文清理和实际生成 SQL;它不会自动解决索引、深分页或联表性能问题。


七、XML 与注解怎么选

简单 SQL 可以使用 @Select,动态条件、复用片段和复杂结果映射通常更适合 XML。选择后应保持一致,不要同一操作在接口注解和 XML 中各写一份。

无论采用哪种形式,都应遵守:

  • 显式列出查询字段,避免无必要的 SELECT *;

  • 普通参数使用 #{},禁止直接拼接用户输入;

  • 动态 SQL 的空条件行为经过测试,避免意外退化为全表更新或全表删除;

  • 列表查询必须有合理上限与稳定排序;

  • 更新、删除检查受影响行数,并按业务定义处理 0 行结果。


八、避免 N+1 查询与过度联表

查询任务列表后,再为每条任务单独查询负责人,会形成 N+1 次 SQL。可以通过一次批量查询按 ID 分组,或者使用边界清晰的联表查询解决。

但一次性联出所有关联对象也不是最佳实践。字段过多、笛卡尔积、重复行和巨大结果集会制造新的问题。建议先通过实际 SQL 与执行计划定位瓶颈,再选择批量查询、联表或调整接口结构。

MyBatis 的懒加载也不是免费优化。离开预期会话范围后访问关联属性,可能触发意外查询或加载异常。接口返回对象前,应明确哪些关联数据已经加载。


九、用集成测试验证真实 SQL

下面的测试使用真实 Spring 容器和内存数据库,不只是 Mock Mapper:

package com.example.task;

import static org.assertj.core.api.Assertions.assertThat;

import java.util.List;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.transaction.annotation.Transactional;

@SpringBootTest
@Transactional
class TaskServiceTest {
    @Autowired
    TaskService service;

    @Test
    void createsTaskAndReturnsGeneratedId() {
        Task task = service.create("  编写 MyBatis 示例  ");

        assertThat(task.getId()).isNotNull();
        assertThat(task.getTitle()).isEqualTo("编写 MyBatis 示例");
        assertThat(task.getStatus()).isEqualTo("TODO");
    }

    @Test
    void searchesByKeywordAndStatusWithPagination() {
        service.create("整理周报");
        service.create("整理月报");
        Task completed = service.create("周报归档");
        service.complete(completed.getId());

        List<Task> page = service.search("TODO", "周报", 1, 10);

        assertThat(page).extracting(Task::getTitle).containsExactly("整理周报");
        assertThat(service.search("COMPLETED", "周报", 1, 10))
                .extracting(Task::getTitle)
                .containsExactly("周报归档");
    }
}

@Transactional 让每个测试结束后回滚,避免数据相互污染。它能验证当前 SQL 与映射,却不能覆盖事务提交后的并发行为。生产数据库与 H2 在方言、索引、大小写和锁方面可能不同,关键功能仍需在实际数据库环境验证。

还应补充空条件、非法页码、不存在 ID、重复数据、并发更新和事务回滚等用例。只打印查询结果的“测试”无法自动发现回归。


十、上线前检查清单

  • [ ] Starter 与 Spring Boot 大版本匹配,依赖来源明确。

  • [ ] Mapper XML 的 namespace、方法名和参数名与接口一致。

  • [ ] SQL 参数使用 #{},动态排序等标识符经过白名单限制。

  • [ ] 列表与总数条件一致,分页有上限和稳定排序。

  • [ ] 更新、删除有明确条件,并检查受影响行数。

  • [ ] Service 事务覆盖完整业务用例,异常与回滚规则明确。

  • [ ] 已查看真实 SQL 和执行计划,没有无意识 N+1 查询。

  • [ ] 集成测试真实执行,关键 SQL 在目标数据库验证。

  • [ ] 日志不包含密码、令牌或不必要的敏感查询参数。

  • [ ] 数据库账号遵循最小权限,连接信息不进入仓库。


十一、总结

Spring Boot 整合 MyBatis 的重点不是配置一个 Starter,而是建立可维护的数据访问边界:

  1. Mapper 专注数据访问,Service 组织业务与事务。

  2. XML 适合动态 SQL 和复杂映射,参数始终安全绑定。

  3. 查询条件复用、分页限制和稳定排序需要一起设计。

  4. N+1、深分页和联表问题必须结合实际 SQL 与执行计划判断。

  5. 测试应连接真实数据库行为,而不是只验证 Mock 调用。

  6. H2 能提高反馈速度,但不能替代目标数据库上的最终验证。

下一篇预告

下一篇《Spring Boot多数据源配置》将讨论多数据源的边界、事务限制,以及读写分离场景中容易忽略的一致性问题。


作者:洋洋技术笔记 发布日期:2026-11-22 系列:Spring Boot实战 - 第11篇


原文链接:洋洋的技术笔记

0

评论区