MybatisPlus邂逅PageHelper：分页难题终极解决方案及版本兼容避坑指南

在实际的项目开发中，MybatisPlus和PageHelper都是非常流行的分页解决方案。MybatisPlus的Wrapper简化了数据库操作，PageHelper则提供了方便的分页功能。然而，当两者同时使用时，特别是旧版本组合时，很容易出现分页失效、数据错乱等问题。本文将深入探讨MybatisPlus和PageHelper分页冲突的原因，并提供有效的解决方案，同时聚焦jsqlparser、pagehelper、MybatisPlus三者的版本兼容问题。

问题场景重现

假设我们有一个User表，需要进行分页查询。我们使用了MybatisPlus的Wrapper构造查询条件，并使用PageHelper进行分页。

// UserMapper.java
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.example.entity.User;
import org.apache.ibatis.annotations.Mapper;

@Mapper
public interface UserMapper extends BaseMapper<User> {

}

// UserService.java
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.example.entity.User;
import com.example.mapper.UserMapper;
import com.github.pagehelper.PageHelper;
import com.github.pagehelper.PageInfo;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class UserService {

    @Autowired
    private UserMapper userMapper;

    public PageInfo<User> getUserList(int pageNum, int pageSize) {
        PageHelper.startPage(pageNum, pageSize); // 开启PageHelper分页

        QueryWrapper<User> queryWrapper = new QueryWrapper<>();
        // 添加一些查询条件
        queryWrapper.like("name", "test");

        List<User> userList = userMapper.selectList(queryWrapper);  // 使用MybatisPlus的查询方法

        return new PageInfo<>(userList);
    }
}

然而，在执行上述代码时，我们可能会遇到以下问题：

• 分页失效：查询结果返回了所有数据，没有进行分页。
• 数据错乱：查询结果分页不正确，例如第一页显示了第二页的数据。
• 控制台报错： 出现SQL解析错误，提示不支持某些SQL语法。

这些问题往往与jsqlparser、pagehelper、MybatisPlus三者的版本兼容性有关。

底层原理深度剖析

PageHelper 的核心原理是使用Mybatis的Interceptor（拦截器）对SQL进行拦截，并在SQL语句中添加 limit 和 offset 关键字，实现分页功能。它依赖于 jsqlparser 解析SQL，添加分页参数。

MybatisPlus 提供了强大的Wrapper功能，方便构建复杂的SQL查询条件。它本身也带有分页插件，但默认情况下可能未启用，或者与PageHelper的配置冲突。

当PageHelper和MybatisPlus同时使用时，如果jsqlparser版本过低，可能无法正确解析MybatisPlus生成的SQL语句，导致分页失效。或者，PageHelper的分页逻辑与MybatisPlus的分页插件发生冲突，导致数据错乱。

常见的冲突点在于：

• SQL解析：jsqlparser版本过低，无法解析MybatisPlus复杂的SQL结构，导致PageHelper无法正确添加分页参数。
• 分页逻辑：PageHelper和MybatisPlus都尝试修改SQL，导致相互干扰，最终结果不符合预期。
• 配置冲突：MybatisPlus内置分页插件和PageHelper同时启用，导致重复分页。

例如，某个项目使用了较低版本的 jsqlparser (例如 3.x)，而 MybatisPlus 生成的 SQL 语句包含复杂的嵌套查询或自定义函数，jsqlparser 无法正确解析，导致 PageHelper 无法在 SQL 中注入分页逻辑，从而返回了所有数据。

解决方案

解决MybatisPlus和PageHelper分页冲突的关键在于：

1. 升级版本：确保jsqlparser、pagehelper、MybatisPlus的版本兼容。建议升级到较新的稳定版本，例如：

   • MybatisPlus: 3.5.x 或更高版本
   • PageHelper: 5.3.x 或更高版本
   • jsqlparser: 4.6 或更高版本（通常由 PageHelper 依赖引入）

   在 pom.xml 文件中添加或更新依赖项：

   <dependency>
       <groupId>com.github.pagehelper</groupId>
       <artifactId>pagehelper-spring-boot-starter</artifactId>
       <version>5.3.2</version>
   </dependency>
   <dependency>
       <groupId>com.baomidou</groupId>
       <artifactId>mybatis-plus-boot-starter</artifactId>
       <version>3.5.3.1</version>
   </dependency>
   

   需要特别注意的是，检查依赖传递，确保项目中不存在多个版本的 jsqlparser。可以使用 Maven 的 dependency tree 命令查看依赖关系，排除低版本 jsqlparser 的干扰。

   

2. 禁用MybatisPlus内置分页插件：如果项目中同时使用了PageHelper和MybatisPlus，建议禁用MybatisPlus的内置分页插件，避免冲突。可以在MybatisPlus的配置中进行设置：

   @Configuration
   public class MybatisPlusConfig {
   
       @Bean
       public MybatisPlusInterceptor mybatisPlusInterceptor() {
           MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
           // 禁用 MybatisPlus 内置分页插件
           //interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
           return interceptor;
       }
   }
   

   或者在 application.yml 中配置：

   mybatis-plus:
     configuration:
       interceptors:
         - com.baomidou.mybatisplus.extension.plugins.inner.BlockAttackInnerInterceptor # 防全表更新、删除插件
   

3. 配置PageHelper：确保PageHelper的配置正确，例如：

   pagehelper.helperDialect=mysql
   pagehelper.reasonable=true
   pagehelper.supportMethodsArguments=true
   pagehelper.params=count=countSql
   

   • helperDialect：指定数据库方言，例如mysql、oracle等。
   • reasonable：分页参数合理化，当pageNum<=0时会查询第一页，pageNum>总页数时会查询最后一页。
   • supportMethodsArguments：支持通过Mapper接口参数来传递分页参数。
   • params：为了支持count=countSql这种写法，允许修改count参数名称。

4. 使用PageInfo获取分页信息：使用com.github.pagehelper.PageInfo类获取分页信息，而不是使用MybatisPlus的IPage接口。

   

   PageInfo<User> pageInfo = new PageInfo<>(userList);
   System.out.println("总页数：" + pageInfo.getPages());
   System.out.println("当前页：" + pageInfo.getPageNum());
   System.out.println("每页大小：" + pageInfo.getPageSize());
   System.out.println("总记录数：" + pageInfo.getTotal());
   

5. 检查SQL语句：仔细检查MybatisPlus生成的SQL语句，确保SQL语句的语法正确，没有潜在的错误。可以使用Mybatis的日志功能，输出执行的SQL语句。

   logging:
     level:
       com.example.mapper: debug # 设置Mapper接口的日志级别为debug
   

6. 手动分页 (作为最后的兜底方案): 如果以上方法仍然无法解决问题，可以考虑手动进行分页。这意味着你需要自己计算offset和limit，并将它们添加到SQL语句中。这种方法比较繁琐，但可以确保分页的正确性。

实战避坑经验总结

• 版本兼容性至关重要：在引入MybatisPlus和PageHelper时，务必仔细检查三者的版本兼容性。阅读官方文档和社区讨论，了解已知的问题和解决方案。
• 避免重复配置：避免同时启用MybatisPlus和PageHelper的分页功能。选择其中一种方式，并禁用另一种。
• SQL日志是好帮手：通过开启SQL日志，可以清晰地看到执行的SQL语句，方便排查问题。
• 单元测试验证：编写单元测试，验证分页功能的正确性。确保在各种情况下，分页都能正常工作。
• 关注jsqlparser的更新：jsqlparser作为SQL解析器，其更新往往会影响到PageHelper的功能。关注jsqlparser的更新日志，及时升级版本。

在实际项目中，很多时候还会遇到由于使用了数据库中间件（例如 ShardingSphere、Mycat）导致分页失效的情况。这是因为这些中间件可能会重写 SQL 语句，导致 PageHelper 无法正确识别和处理。 此时，需要仔细阅读中间件的文档，了解其 SQL 重写规则，并根据实际情况进行调整。

通过以上的分析和解决方案，相信您能够更好地解决MybatisPlus和PageHelper的分页冲突问题，提高开发效率和代码质量。同时，也希望本文能够帮助您避免在项目中踩坑，减少不必要的麻烦。