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: truemap-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,而是建立可维护的数据访问边界:
Mapper 专注数据访问,Service 组织业务与事务。
XML 适合动态 SQL 和复杂映射,参数始终安全绑定。
查询条件复用、分页限制和稳定排序需要一起设计。
N+1、深分页和联表问题必须结合实际 SQL 与执行计划判断。
测试应连接真实数据库行为,而不是只验证 Mock 调用。
H2 能提高反馈速度,但不能替代目标数据库上的最终验证。
下一篇预告
下一篇《Spring Boot多数据源配置》将讨论多数据源的边界、事务限制,以及读写分离场景中容易忽略的一致性问题。
作者:洋洋技术笔记 发布日期:2026-11-22 系列:Spring Boot实战 - 第11篇
原文链接:洋洋的技术笔记
评论区