黑河市all1. 项目概述
最近在技术社区看到不少开发者反馈MyBatis-Plus分页插件突然失效的问题，特别是在同时使用PageHelper的场景下。作为一个长期使用MyBatis-Plus的老手，我深知这背后的"假分页"陷阱有多隐蔽。今天我们就来彻底扒开这个问题的底层原理，让你不仅知道怎么解决，更明白为什么会出现这种情况。
这个问题通常表现为：明明配置了MyBatis-Plus的分页插件，查询时也传入了Page对象，但执行的SQL却没有LIMIT语句，返回的却是全部数据。更诡异的是，单独测试MyBatis-Plus分页功能时一切正常，只有当项目中同时存在PageHelper时才会出现这种情况。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心原理剖析
2.1 MyBatis-Plus分页机制
MyBatis-Plus的分页插件（PaginationInnerInterceptor）是通过MyBatis的拦截器机制实现的。它的核心工作流程是这样的：
- 拦截Executor的query方法
- 判断方法参数中是否包含IPage实例
- 如果有分页参数，就改写原始SQL，添加LIMIT语句
- 执行count查询获取总数
- 返回封装好的Page对象
关键源码片段（简化版）：
java复制public class PaginationInnerInterceptor implements InnerInterceptor {
@Override
public void beforeQuery(Executor executor, MappedStatement ms,
Object parameter, RowBounds rowBounds, ResultHandler resultHandler,
BoundSql boundSql) {
if (parameter instanceof IPage) {
// 处理分页逻辑
String originalSql = boundSql.getSql();
String pageSql = dialect.buildPaginationSql(originalSql,
(IPage)parameter);
// 反射修改boundSql的sql字段
resetSql(ms, boundSql, pageSql);
}
}
}
2.2 PageHelper的工作原理
PageHelper同样是通过MyBatis拦截器实现分页，但它的触发机制不同：
- 通过PageHelper.startPage()静态方法设置线程局部变量
- 拦截Executor的query方法
- 从线程局部变量获取分页参数
- 改写SQL添加分页语句
- 清除线程局部变量
关键区别在于：PageHelper的分页参数是通过方法调用设置的，而不是通过方法参数传递的。
2.3 冲突的根源
当两个插件同时存在时，执行顺序就变得至关重要。在MyBatis中，拦截器的执行顺序与配置顺序相反（后配置的先执行）。通常的冲突场景：
- 开发者先配置PageHelper，后配置MyBatis-Plus分页插件
- 执行查询时，MyBatis-Plus的拦截器先执行（因为它后配置）
- MyBatis-Plus检查方法参数，没有发现IPage实例（因为参数是PageHelper的Page）
- 跳过分页处理
- PageHelper的拦截器后执行，正常处理分页
- 但此时SQL已经被MyBatis-Plus处理过，可能产生预期外的行为
3. 解决方案与最佳实践
3.1 明确的使用规范
经过多次实践，我总结出以下可靠方案：
- 统一分页方式：整个项目只使用一种分页方案（推荐MyBatis-Plus）
- 如果必须混用：
- 确保MyBatis-Plus的配置在PageHelper之后
- 使用明确的参数传递方式
- 避免在同一个线程中混用两种方式
3.2 配置示例
正确的配置顺序（Spring Boot示例）：
java复制@Configuration
public class MybatisConfig {
// 先配置PageHelper
@Bean
public PageInterceptor pageInterceptor() {
PageInterceptor pageInterceptor = new PageInterceptor();
Properties properties = new Properties();
properties.setProperty("helperDialect", "mysql");
pageInterceptor.setProperties(properties);
return pageInterceptor;
}
// 后配置MyBatis-Plus分页插件
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
return interceptor;
}
}
3.3 常见问题排查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 分页完全不生效 | 1. 插件未正确配置 2. 配置顺序错误 |
1. 检查拦截器是否生效 2. 调整配置顺序 |
| 返回总数为0 | count查询被干扰 | 检查是否有其他拦截器修改SQL |
| 分页参数混乱 | 线程局部变量未清除 | 确保在finally块中调用PageHelper.clearPage() |
| 性能突然下降 | 执行了全表扫描 | 检查最终执行的SQL是否包含LIMIT |
4. 深度优化建议
4.1 自定义分页拦截器
对于高级场景，可以考虑实现自定义分页逻辑：
java复制public class CustomPaginationInterceptor implements InnerInterceptor {
@Override
public void beforeQuery(Executor executor, MappedStatement ms,
Object parameter, RowBounds rowBounds, ResultHandler resultHandler,
BoundSql boundSql) {
// 同时支持IPage和PageHelper的分页参数
IPage pageParam = getPageParam(parameter);
if (pageParam == null) {
pageParam = PageHelper.getLocalPage();
}
if (pageParam != null) {
// 统一的分页处理逻辑
handlePagination(boundSql, pageParam);
}
}
}
4.2 性能优化技巧
-
避免不必要的count查询：
java复制// 当只需要数据不需要总数时 Page<User> page = new Page<>(1, 10, false); -
优化count语句：
java复制// 在实体类上指定count查询 @TableName(value = "user", resultMap = "userMap") public class User { // ... } -
大数据量分页优化：
sql复制-- 使用延迟关联优化大数据量分页 SELECT * FROM user INNER JOIN ( SELECT id FROM user LIMIT 1000000, 10 ) AS tmp USING(id)
5. 实战经验分享
在实际项目中，我遇到过几个典型的坑：
-
Spring的@Transactional导致的问题：
- 现象：分页在事务方法中失效
- 原因：Spring会创建新的Executor，导致拦截器链重新执行
- 解决：确保分页参数在事务方法内部设置
-
MyBatis二级缓存引发的诡异现象：
- 现象：相同查询参数返回不同分页结果
- 原因：缓存了分页前的原始结果
- 解决：禁用分页查询的二级缓存或自定义缓存key
-
PageHelper的线程污染问题：
java复制try { PageHelper.startPage(1, 10); // 查询操作 } finally { // 必须清理，否则会影响后续查询 PageHelper.clearPage(); } -
MyBatis-Plus的自动优化陷阱：
- 现象：简单的count查询被优化成复杂查询
- 解决：通过@SqlParser注解控制优化行为
最后分享一个我总结的黄金法则：在分页查询场景下，永远要检查最终执行的SQL语句。很多看似诡异的问题，通过查看实际执行的SQL都能快速定位原因。可以使用以下配置开启SQL日志：
properties复制# application.properties
mybatis-plus.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl