MyBatis-Plus 分页插件拦截 SQL 实现 TTS 任务分页查询
在语音合成（Text-to-Speech, TTS）系统日益普及的今天，用户不仅追求生成音频的质量，也对系统的响应速度和交互体验提出了更高要求。特别是在批量处理语音任务、管理历史记录等场景下，数据库中往往积累了成千上万条任务数据。如果前端一次性拉取全部记录，轻则页面卡顿，重则服务崩溃。
如何高效地展示这些海量任务？答案是：分页查询。而在 Java 后端开发中，MyBatis-Plus 提供了一套极为优雅的解决方案——通过其内置的分页插件自动拦截并改写 SQL，实现物理分页，无需开发者手动拼接LIMIT和COUNT语句。
这套机制用在 TTS 任务管理系统中再合适不过：既能避免内存溢出，又能提升前后端通信效率，还能让代码更简洁、可维护性更强。
分页插件是如何工作的？
MyBatis-Plus 的分页能力核心在于PaginationInnerInterceptor，它本质上是一个 MyBatis 拦截器，注册后会在每次执行查询时“介入”SQL 执行流程。
当你的 Mapper 方法返回类型为IPage<T>，并且参数中包含Page<T>对象时，插件就会被触发。它的主要工作包括：
- 解析原始 SQL：获取未分页前的查询语句。
- 生成 COUNT 查询：用于统计总条数，例如：
sql SELECT COUNT(*) FROM tts_task WHERE status = 1 - 重写主查询 SQL：根据当前数据库类型添加对应的分页子句。以 MySQL 为例：
sql SELECT * FROM tts_task WHERE status = 1 LIMIT 0, 10 - 封装结果对象：将查询到的数据列表与总数一起包装进
IPage返回。
整个过程对业务逻辑完全透明，开发者只需关注“查什么”，不用操心“怎么分页”。
值得一提的是，该插件基于ThreadLocal存储分页参数，确保多线程环境下各请求之间的隔离性，不会出现分页错乱的问题。
如何集成到 TTS 系统中？
假设我们正在构建一个基于 Spring Boot 的 TTS 服务，需要支持对语音合成任务进行分页浏览。以下是完整的落地步骤。
配置分页插件
首先，在配置类中注册MybatisPlusInterceptor并加入分页拦截器：
@Configuration @MapperScan("com.example.tts.mapper") public class MyBatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); // 根据实际使用的数据库设置 DbType interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }⚠️ 注意：如果不注册这个拦截器，即使写了
Page参数也不会生效！这是最常见的“为什么没分页？”问题根源。
定义实体类
TTS 任务通常包含输入文本、参考音频路径、输出文件位置、状态和时间戳等字段：
@Data @TableName("tts_task") public class TTSTask { private Long id; private String inputText; private String promptAudioPath; private String outputFilePath; private Integer status; // 0:待处理, 1:成功, 2:失败 private LocalDateTime createTime; private LocalDateTime updateTime; }Lombok 注解简化了 POJO 写法，而@TableName明确指定了表名映射。默认情况下，MyBatis-Plus 会自动将驼峰命名转换为下划线命名（如createTime→create_time），无需额外配置。
编写 Mapper 接口
为了让分页插件起作用，Mapper 方法必须满足两个条件之一：
- 返回类型为IPage<T>
- 使用selectPage(Page<T>, Wrapper<T>)方法
推荐自定义方法，提高语义清晰度：
public interface TTSTaskMapper extends BaseMapper<TTSTask> { /** * 分页查询所有任务 */ IPage<TTSTask> selectTaskPage(Page<TTSTask> page); /** * 按状态分页查询 */ IPage<TTSTask> selectByStatus(Page<TTSTask> page, @Param("status") Integer status); }只要参数中有Page对象，且返回值是IPage，插件就能识别并拦截。方法名本身没有强制约束。
Service 层调用
在服务层创建Page实例并传入当前页和每页数量即可完成分页查询：
@Service public class TTSTaskService { @Autowired private TTSTaskMapper ttsTaskMapper; public IPage<TTSTask> getTasksByPage(int current, int size) { // 页码从1开始 Page<TTSTask> page = new Page<>(current, size); return ttsTaskMapper.selectTaskPage(page); } public IPage<TTSTask> getTasksByStatus(int current, int size, Integer status) { Page<TTSTask> page = new Page<>(current, size); return ttsTaskMapper.selectByStatus(page, status); } }注意：Page(current, size)中的current是页码（第几页），不是偏移量。底层会自动计算offset = (current - 1) * size。
此外，建议在此层加入参数校验，防止恶意请求导致性能问题：
if (size <= 0 || size > 100) { throw new IllegalArgumentException("每页大小不得超过100"); } if (current < 1) { current = 1; }Controller 暴露 API
最后通过 REST 接口暴露给前端：
@RestController @RequestMapping("/api/tts/tasks") public class TTSTaskController { @Autowired private TTSTaskService taskService; @GetMapping("/page") public ResponseEntity<IPage<TTSTask>> getTasks( @RequestParam(defaultValue = "1") int current, @RequestParam(defaultValue = "10") int size) { IPage<TTSTask> result = taskService.getTasksByPage(current, size); return ResponseEntity.ok(result); } @GetMapping("/page/status") public ResponseEntity<IPage<TTSTask>> getTasksByStatus( @RequestParam(defaultValue = "1") int current, @RequestParam(defaultValue = "10") int size, @RequestParam Integer status) { IPage<TTSTask> result = taskService.getTasksByStatus(current, size, status); return ResponseEntity.ok(result); } }访问/api/tts/tasks/page?current=1&size=10即可获得第一页的 10 条任务数据。
返回的 JSON 结构如下：
{ "records": [ { "id": 1, "inputText": "你好世界", "promptAudioPath": "examples/prompt/audio1.wav", "outputFilePath": "@outputs/tts_20251212_113000.wav", "status": 1, "createTime": "2025-12-12T11:30:00" } ], "total": 156, "size": 10, "current": 1, "pages": 16, "searchCount": true }前端可根据total和pages渲染分页控件，实现跳转、总数显示等功能。
在真实场景中的价值体现
在一个典型的 TTS 任务管理后台中，这套分页机制解决了多个关键痛点。
避免全量加载导致的性能雪崩
早期版本若未启用分页，一次请求可能拉取上万条任务，数据库压力陡增，网络传输耗时严重，甚至引发 OOM。引入分页后，只查询所需数据，响应时间从秒级降至毫秒级。
消除重复的手动分页代码
过去每个 DAO 都要写类似的 SQL 片段：
<select id="selectByPage" resultType="TTSTask"> SELECT * FROM tts_task LIMIT #{offset}, #{limit} </select> <select id="countAll" resultType="long"> SELECT COUNT(*) FROM tts_task </select>不仅繁琐，还容易出错。现在统一由插件处理，彻底告别样板代码。
支持未来数据库迁移
不同数据库的分页语法差异显著：
| 数据库 | 分页语法 |
|---|---|
| MySQL | LIMIT offset, size |
| PostgreSQL | LIMIT size OFFSET offset |
| Oracle | ROWNUM或OFFSET ... FETCH |
如果系统将来要迁移到 Oracle 或 PG，只需修改配置中的DbType，无需改动任何 SQL 或 Java 代码，真正实现平滑过渡。
最佳实践建议
为了最大化发挥分页插件的优势，结合 TTS 场景给出以下工程建议：
✅ 合理设置最大页大小
虽然可以传size=10000，但应限制上限（如 100），避免拖垮数据库：
int pageSize = Math.min(size, 100);✅ 为常用排序字段建立索引
分页常配合排序使用，尤其是按创建时间倒序展示最新任务：
ALTER TABLE tts_task ADD INDEX idx_create_time (create_time DESC);否则会出现“深分页”问题——越往后翻页越慢。
✅ 默认按时间倒序排列
用户最关心的是最近提交的任务，因此应在查询时显式指定排序规则：
Page<TTSTask> page = new Page<>(current, size); page.addOrder(OrderItem.desc("create_time"));也可以在 XML 或 Wrapper 中统一设置。
✅ 动态条件查询 + 分页组合使用
大多数时候不只是简单分页，还需结合状态、关键字等过滤条件。此时推荐使用QueryWrapper或LambdaQueryWrapper：
LambdaQueryWrapper<TTSTask> wrapper = Wrappers.lambdaQuery(); if (status != null) { wrapper.eq(TTSTask::getStatus, status); } if (StringUtils.isNotBlank(keyword)) { wrapper.like(TTSTask::getInputText, keyword); } return ttsTaskMapper.selectPage(page, wrapper);依然能享受分页插件带来的自动 COUNT 和 SQL 改写功能。
✅ 前端做好空值与边界处理
当current=0或size=-1时，后端应做容错处理或抛出友好提示，而不是直接报错。同时前端也要验证输入合法性，减少无效请求。
插件背后的思考：为什么选择 MyBatis-Plus 而非原生 MyBatis？
有人可能会问：“我用 MyBatis 自己写分页不行吗？” 当然可以，但代价是：
- 每个分页接口都要重复编写
COUNT和LIMIT； - 不同数据库需维护多套 SQL；
- 参数绑定复杂，易出错；
- 无法统一控制最大页大小、是否启用优化等全局策略。
而 MyBatis-Plus 的分页插件把这些共性问题都封装好了，提供了一个标准化、可复用、可配置的分页模型。你只需要声明“我要分页”，剩下的交给框架。
更重要的是，它保持了与原生 MyBatis 的兼容性——你可以继续写 XML，也可以混合使用注解和 Wrapper，灵活度极高。
总结
在处理 TTS 任务这类高并发、大数据量的业务场景中，分页不仅是性能优化手段，更是系统稳定运行的基础保障。
MyBatis-Plus 的分页插件通过拦截 SQL 执行流程，实现了自动化、安全、跨数据库的物理分页，极大降低了开发门槛。结合IPage和Page对象的设计，使得分页逻辑变得极其简洁，几乎零成本接入。
更重要的是，它不仅仅是一个工具，更是一种设计思想的体现：将横切关注点（如分页、租户隔离、数据权限）抽象成拦截器，交由框架统一处理，让开发者专注于核心业务逻辑。
对于正在构建或优化 TTS 管理系统的团队来说，集成 MyBatis-Plus 分页插件是一项低投入、高回报的技术决策。无论是提升用户体验、降低运维压力，还是加快迭代速度，它都能带来实实在在的价值。
这种“润物细无声”的技术整合，正是现代 Java 应用架构演进的方向所在。
