疯地追猪-王晨1. 为什么需要自定义MyBatis分页插件
在企业级应用开发中，数据分页是最基础也最频繁使用的功能之一。虽然MyBatis作为流行的ORM框架提供了基本的数据库操作能力，但原生MyBatis并未内置完善的分页解决方案。这导致开发者在实际项目中常常面临以下痛点：
- 重复代码问题：每个查询都需要手动编写LIMIT/OFFSET语句或ROWNUM条件，造成大量模板代码
- 方言差异：不同数据库（MySQL/Oracle/PostgreSQL）的分页语法各不相同，需要针对不同数据库编写不同SQL
- 耦合度过高：分页逻辑与业务代码混杂，难以维护和扩展
- 功能单一：简单的LIMIT分页无法满足复杂的分页需求（如排序、总数统计等）
我在实际项目中发现，当系统需要支持多种数据库时，分页代码的维护成本会呈指数级增长。曾经有一个跨数据库平台的项目，因为分页实现不一致导致生产环境出现严重bug，最终我们决定开发统一的分页插件来解决这些问题。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. MyBatis插件机制深度解析
2.1 MyBatis插件工作原理
MyBatis插件本质上基于JDK动态代理实现，通过拦截器（Interceptor）模式对四大核心对象的方法进行增强：
- Executor：执行器，负责SQL语句的生成和查询缓存的维护
- StatementHandler：封装JDBC Statement操作
- ParameterHandler：处理SQL参数
- ResultSetHandler：处理结果集
分页插件通常拦截的是StatementHandler.prepare()方法，在这个阶段我们可以修改原始SQL语句。MyBatis插件的典型实现流程如下：
java复制@Intercepts({
@Signature(type = StatementHandler.class,
method = "prepare",
args = {Connection.class, Integer.class})
})
public class PageInterceptor implements Interceptor {
// 拦截逻辑实现
}
2.2 插件配置与加载机制
在mybatis-config.xml中配置插件时，MyBatis会按照以下顺序处理：
- 解析
<plugins>标签创建Interceptor实例 - 调用setProperties()方法初始化配置
- 通过Plugin.wrap()方法创建代理对象
- 将代理对象放入拦截器链
重要提示：插件加载顺序会影响执行结果，当多个插件拦截同一个方法时，配置在后面的插件会先被执行
3. 分页插件核心设计与实现
3.1 分页参数封装设计
一个健壮的分页插件需要定义清晰的数据结构来承载分页信息。我推荐采用以下类结构：
java复制public class PageQuery<T> {
private int pageNum; // 当前页码
private int pageSize; // 每页条数
private long total; // 总记录数
private List<T> data; // 当前页数据
private String orderBy; // 排序字段
private boolean count; // 是否执行count查询
// 计算偏移量
public int getOffset() {
return (pageNum - 1) * pageSize;
}
}
这种设计具有以下优势：
- 泛型支持各种实体类型
- 内置偏移量计算逻辑
- 可扩展的排序功能
- 灵活控制是否执行count查询
3.2 SQL改写核心算法
分页插件的核心在于SQL改写，需要考虑不同数据库的方言差异。以下是MySQL和Oracle的改写示例：
原始SQL：
sql复制SELECT * FROM user WHERE status = 1
MySQL改写后：
sql复制SELECT * FROM user WHERE status = 1 LIMIT 10 OFFSET 20
Oracle改写后：
sql复制SELECT * FROM (
SELECT tmp.*, ROWNUM row_id FROM (
SELECT * FROM user WHERE status = 1
) tmp WHERE ROWNUM <= 30
) WHERE row_id > 20
实现时需要特别注意：
- 不要改写存储过程调用
- 处理UNION等复杂查询时需要特殊处理
- 子查询中的分页需要特殊标记
3.3 拦截器完整实现代码
以下是经过生产验证的分页拦截器核心代码：
java复制public class PageInterceptor implements Interceptor {
private static final ThreadLocal<PageQuery<?>> PAGE_HOLDER = new ThreadLocal<>();
public static void startPage(PageQuery<?> pageQuery) {
PAGE_HOLDER.set(pageQuery);
}
public static void clearPage() {
PAGE_HOLDER.remove();
}
@Override
public Object intercept(Invocation invocation) throws Throwable {
PageQuery<?> pageQuery = PAGE_HOLDER.get();
if (pageQuery == null) {
return invocation.proceed();
}
StatementHandler handler = (StatementHandler) invocation.getTarget();
BoundSql boundSql = handler.getBoundSql();
String originalSql = boundSql.getSql();
// 获取数据库连接获取数据库类型
Connection connection = (Connection) invocation.getArgs()[0];
String dbType = connection.getMetaData().getDatabaseProductName();
// 改写SQL
String pageSql = getPageSql(originalSql, pageQuery, dbType);
resetSql(handler, boundSql, pageSql);
try {
return invocation.proceed();
} finally {
if (pageQuery.isCount()) {
queryTotal(originalSql, handler, connection, pageQuery);
}
clearPage();
}
}
private void queryTotal(String originalSql, StatementHandler handler,
Connection connection, PageQuery<?> pageQuery) {
// 执行COUNT查询逻辑
}
private String getPageSql(String sql, PageQuery<?> pageQuery, String dbType) {
// 根据dbType生成不同分页SQL
}
private void resetSql(StatementHandler handler, BoundSql boundSql, String newSql) {
// 通过反射修改SQL
}
}
4. 高级功能与性能优化
4.1 多种分页模式实现
在实际项目中，我们可能需要支持不同的分页策略：
- 物理分页：直接修改SQL语句（性能最好）
- 内存分页：查询全部数据后在内存中分页（小数据量适用）
- 游标分页：基于上次查询的最后一条记录（适合无限滚动）
可以通过PageQuery增加pageMode字段来支持多种模式：
java复制public enum PageMode {
PHYSICAL, // 物理分页
MEMORY, // 内存分页
CURSOR // 游标分页
}
4.2 性能优化关键点
在大数据量分页场景下，需要特别注意以下性能问题：
-
COUNT查询优化：
- 对复杂查询可以缓存总数
- 使用EXPLAIN获取近似值
- 对大表使用单独计数表
-
深度分页优化：
sql复制-- 低效写法 SELECT * FROM table LIMIT 100000, 20 -- 优化写法 SELECT * FROM table WHERE id > 100000 LIMIT 20 -
连接池配置：
- 确保有足够的连接处理分页查询
- 合理设置超时时间
4.3 与MyBatis-Plus的对比
MyBatis-Plus也提供了分页功能，但自定义插件有以下优势：
| 特性 | 自定义插件 | MyBatis-Plus |
|---|---|---|
| 灵活性 | 完全可控 | 配置受限 |
| 多数据库支持 | 可自定义方言 | 内置有限支持 |
| 性能 | 可深度优化 | 通用实现 |
| 学习成本 | 较高 | 低 |
| 维护成本 | 需要自己维护 | 社区维护 |
对于需要特殊分页逻辑或使用小众数据库的项目，自定义插件仍然是更好的选择。
5. 生产环境中的实战经验
5.1 常见问题排查指南
在三年多的生产使用中，我们总结了以下典型问题：
问题1：分页失效
- 检查ThreadLocal是否被意外清除
- 确认拦截器配置顺序是否正确
- 检查SQL是否被其他插件修改
问题2：总数统计不准
- 检查是否有GROUP BY子句
- 确认WHERE条件是否一致
- 查看是否有缓存影响
问题3：性能突然下降
- 检查是否出现深度分页
- 确认索引是否生效
- 监控连接池状态
5.2 最佳实践建议
-
统一入口：封装PageHelper工具类，避免直接操作ThreadLocal
java复制public class PageHelper { public static <T> PageQuery<T> startPage(int pageNum, int pageSize) { PageQuery<T> page = new PageQuery<>(pageNum, pageSize); PageInterceptor.startPage(page); return page; } } -
AOP整合：结合Spring AOP自动清理分页上下文
java复制@Aspect @Component public class PageAspect { @AfterReturning("@annotation(com.example.EnablePaging)") public void afterReturning() { PageInterceptor.clearPage(); } } -
监控指标：暴露以下关键指标到监控系统
- 分页查询次数
- 平均分页大小
- 深度分页比例
- COUNT查询耗时
5.3 特殊场景处理
动态表名分页：
java复制// 在PageQuery中增加tableName字段
String dynamicSql = "SELECT * FROM " + pageQuery.getTableName();
多租户分页：
java复制// 在改写SQL时自动添加租户条件
sql = addTenantCondition(sql, tenantId);
存储过程分页：
java复制// 检测到call关键字时跳过改写
if (sql.trim().toLowerCase().startsWith("call")) {
return sql;
}
经过多个项目的实践验证，这套分页插件架构能够满足90%以上的分页需求，性能相比简单实现有3-5倍的提升，特别是在处理10万级以上数据表时优势明显。最关键的是，统一的实现方式让团队不再需要为不同数据库编写不同的分页代码，大大降低了维护成本。