JavaMyBatis拦截器实现自动分页方法

本文深入剖析了在Java中基于MyBatis实现高可靠性、跨数据库兼容的自动分页拦截器的核心原理与实战要点：强调必须严格遵循MyBatis插件机制——仅能通过实现Interceptor接口并精准拦截StatementHandler（推荐，用于安全改写SQL）或Executor（适用于总数统计），杜绝字符串硬拼SQL等危险操作；详解如何利用MetaObject安全修改BoundSql、通过ThreadLocal传递分页参数（避免依赖非标准args解析）、正确注册与配置插件（全限定名+Plugin.wrap），并重点揭示不同数据库方言（MySQL/LIMIT、Oracle/ROWNUM嵌套、SQL Server/OFFSET-FETCH等）下SQL重写的本质差异与避坑策略，直击开发者常踩的语法错误、代理失效、内存泄漏及多线程上下文丢失等痛点，为构建健壮、可维护的通用分页能力提供扎实可靠的技术路径。

MyBatis插件必须实现Interceptor接口，且只能拦截四大对象之一

MyBatis插件不是随便拦SQL的——它底层靠JDK动态代理，只允许对Executor、StatementHandler、ParameterHandler、ResultSetHandler这四个对象生效。想改SQL或加LIMIT，必须选StatementHandler（拼SQL前）或Executor（执行前）。选错对象，插件根本不会触发。

常见错误是直接在intercept()里解析boundSql.getSql()然后字符串拼" LIMIT ?,?"——这不行，因为原始SQL可能带ORDER BY、子查询、甚至分号，硬拼会语法报错。

• 优先拦截StatementHandler，用MetaObject修改boundSql内部字段，而不是字符串替换
• 必须调用Plugin.wrap(target, this)完成代理包装，否则Spring Boot里插件不注册
• XML中配置的interceptor类名要写全限定名，少一个包名就静默失效

分页参数不能从方法签名硬取，得靠ThreadLocal或上下文传递

MyBatis插件拿不到Mapper接口的方法参数，invocation.getArgs()里只有MappedStatement和Object（后者可能是null）。所以PageHelper.startPage(1, 10)这类调用，本质是把分页信息塞进ThreadLocal，插件里再取出来。

自己写时别学网上“从args[1]强转Map取pageNo”——那是特定封装框架的hack，原生MyBatis没这约定。

• 定义private static final ThreadLocal PAGE_HOLDER = new ThreadLocal<>()
• 业务代码调用前手动PAGE_HOLDER.set(new Page(1, 20))，插件intercept()里取，用完remove()防内存泄漏
• 如果用Spring，注意事务方法内多线程调用会导致ThreadLocal丢失，得换RequestContextHolder或显式传参

Executor拦截比StatementHandler更安全，但要注意query方法重载

拦截Executor的query(MappedStatement, Object, RowBounds, ResultHandler)看起来简单，但MyBatis 3.4+新增了带ResultHandler的重载方法，漏掉一个就会跳过插件。而且RowBounds默认是RowBounds.DEFAULT（offset=0, limit=0），不代表用户没分页需求——很多场景下业务压根没传RowBounds，全靠插件自动补。

真正要改SQL，还是得穿透到StatementHandler，但可以在Executor里先判断是否需要分页（比如检查ThreadLocal非空 + mappedStatement.getSqlCommandType() == SqlCommandType.SELECT）。

• 用Plugin.signature()声明多个@Signature，覆盖所有query重载
• 不要在Executor里直接改boundSql，因为boundSql在StatementHandler创建，此时还没生成
• 拦截Executor适合做统计总数（count(*)自动追加），但改SQL必须进StatementHandler

MySQL的LIMIT和Oracle的ROWNUM不能共用一套SQL模板

写个通用分页插件时最容易翻车：用String.format("SELECT * FROM (%s) t LIMIT %d, %d", originSql, offset, size)应付所有数据库。这在Oracle、SQL Server、PostgreSQL上全错——Oracle要ROWNUM嵌套，SQL Server要OFFSET-FETCH，PostgreSQL虽支持LIMIT但偏移量语义和MySQL不同。

MyBatis本身不解决方言问题，DatabaseIdProvider只能帮你区分数据库类型，具体SQL构造还得自己分支处理。

• 在插件里通过configuration.getDatabaseId()判断，分支写if ("mysql".equals(dbId))、else if ("oracle".equals(dbId))
• Oracle分页必须两层嵌套：SELECT * FROM (SELECT ROWNUM rn, t1.* FROM (originSql) t1 WHERE ROWNUM <= ?) WHERE rn > ?
• 别信“用limit兼容所有库”的博客，那是MySQL专用写法，其他库运行时报ORA-00933或SQLServerException

分页插件最难的从来不是拦截，而是SQL重写时对目标数据库语法边界的准确把握——少一个括号、错一个别名、漏一个WHERE ROWNUM <=条件，查出来的数据就少一半或者全乱序。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。