MybatisPlus分页踩坑：Jsqlparser与Pagehelper版本兼容性深度解析

在使用 MybatisPlus 进行快速开发时，集成 PageHelper 插件来实现物理分页是一个常见的选择。然而，许多开发者在使用过程中遇到了 MybatisPlus 和 PageHelper 分页冲突的问题，主要表现为分页失效或者查询结果异常。本文将深入分析 jsqlparser、PageHelper 和 MybatisPlus 三者之间的版本兼容问题，并提供解决方案，帮助你避免踩坑。

问题场景重现

假设我们有一个 Spring Boot 项目，使用了 MybatisPlus 和 PageHelper。我们期望通过 PageHelper 实现分页查询用户列表。如下是一个简单的用户实体类：

@Data
@TableName("user")
public class User {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String name;
    private Integer age;
}

我们在 Controller 中调用 Service 层进行分页查询：

@RestController
@RequestMapping("/user")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/list")
    public IPage<User> list(@RequestParam(defaultValue = "1") int pageNum,
                              @RequestParam(defaultValue = "10") int pageSize) {
        PageHelper.startPage(pageNum, pageSize);
        return userService.page(new Page<>(pageNum, pageSize), null);
    }
}

Service 层调用 MybatisPlus 的 page 方法：

@Service
public class UserService extends ServiceImpl<UserMapper, User> {

}

在没有正确配置的情况下，运行以上代码，你可能会发现分页并没有生效，或者查询结果不正确。这就是 MybatisPlus 和 PageHelper 冲突的典型表现。

底层原理深度剖析

要理解冲突的原因，我们需要了解这三个组件的工作原理：

1. MybatisPlus：MybatisPlus 是一个 Mybatis 的增强工具包，它提供了许多便捷的功能，包括自动生成 SQL、代码生成器、分页插件等。MybatisPlus 本身也提供了分页功能，但是它与 PageHelper 的分页机制存在冲突。

2. PageHelper：PageHelper 是一个 Mybatis 的分页插件，它通过拦截 SQL 语句，修改 SQL 语句以实现分页。PageHelper 依赖于 jsqlparser 来解析 SQL 语句。

3. jsqlparser：jsqlparser 是一个 SQL 解析器，PageHelper 使用它来解析 SQL 语句，以便在 SQL 语句中添加分页相关的语句（例如 LIMIT）。

冲突的根本原因在于，PageHelper 和 MybatisPlus 的分页机制都试图修改 SQL 语句。当它们同时启用时，可能会发生冲突，导致 SQL 语句被多次修改，从而导致分页失效或者查询结果错误。此外，不同版本的 jsqlparser 可能存在 SQL 解析的差异，这也会影响 PageHelper 的分页效果。如果你的项目中还使用了诸如 ShardingSphere 分库分表组件，更需要注意 SQL 解析的兼容性，避免出现 SQL 路由错误的情况。ShardingSphere 也会依赖 JSQLParser，需要考虑版本统一问题。

解决方案：版本兼容性配置

解决这个问题的关键在于确保 jsqlparser、PageHelper 和 MybatisPlus 三者之间的版本兼容。

步骤 1：确认版本依赖

首先，确认你使用的 MybatisPlus、PageHelper 和 jsqlparser 的版本。你可以在 pom.xml 文件中找到这些依赖的版本信息。

步骤 2：版本兼容性分析

一般来说，以下版本组合是相对稳定的：

• MybatisPlus 3.4.x + PageHelper 5.2.x + jsqlparser 4.0
• MybatisPlus 3.5.x + PageHelper 5.3.x + jsqlparser 4.3

请注意，这只是一些建议的版本组合，实际情况可能因项目而异。建议查阅官方文档或者在社区中搜索相关信息，以确定最适合你的项目的版本组合。

步骤 3：修改依赖

如果你的项目使用的版本不兼容，你需要修改 pom.xml 文件，更新依赖的版本。例如：

<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
    <version>5.3.2</version> <!-- 使用 PageHelper 5.3.2 -->
</dependency>

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.3.1</version> <!-- 使用 MybatisPlus 3.5.3.1 -->
</dependency>

<dependency>
    <groupId>com.github.jsqlparser</groupId>
    <artifactId>jsqlparser</artifactId>
    <version>4.6</version> <!-- 显式指定 jsqlparser 版本，避免版本冲突 -->
</dependency>

**务必显式指定 jsqlparser 的版本，避免由于依赖传递导致的版本冲突。**Maven 的依赖管理有时候会引入你不期望的版本。

步骤 4：配置 PageHelper 拦截器

确保 PageHelper 拦截器被正确配置。你可以在 Mybatis 的配置文件中配置 PageHelper 拦截器，也可以在 Spring Boot 的配置类中配置。

@Configuration
public class MybatisConfig {

    @Bean
    public PageInterceptor pageInterceptor() {
        PageInterceptor pageInterceptor = new PageInterceptor();
        Properties properties = new Properties();
        properties.setProperty("helperDialect", "mysql"); // 设置数据库类型
        properties.setProperty("reasonable", "true"); // 设置 reasonable 为 true，启用分页参数合理化
        properties.setProperty("supportMethodsArguments", "true"); // 支持通过方法参数传递分页参数
        properties.setProperty("params", "pageNum=pageNum;pageSize=pageSize;count=countSql");
        pageInterceptor.setProperties(properties);
        return pageInterceptor;
    }
}

步骤 5：禁用 MybatisPlus 的分页插件

由于我们使用 PageHelper 进行分页，我们需要禁用 MybatisPlus 的分页插件。你可以在 MybatisPlus 的配置类中禁用分页插件。

@Configuration
@MapperScan("com.example.mapper")
public class MybatisPlusConfig {

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

实战避坑经验总结

1. 版本一致性至关重要：在引入多个依赖于 jsqlparser 的组件时，务必确保 jsqlparser 的版本一致。可以使用 Maven 的 dependencyManagement 来统一管理依赖的版本。

2. 仔细阅读官方文档：在使用 MybatisPlus 和 PageHelper 时，务必仔细阅读官方文档，了解它们的配置方式和使用方法。官方文档通常会提供一些版本兼容性的建议。

3. 关注社区反馈：在社区中搜索相关问题，看看是否有其他开发者遇到了类似的问题。社区中通常会提供一些有用的解决方案。

4. 单元测试是关键：编写充分的单元测试，确保分页功能正常工作。单元测试可以帮助你及早发现问题，避免在生产环境中出现错误。

5. 考虑使用 MyBatis-Plus 官方分页：如果项目复杂度不高，可以考虑直接使用 MyBatis-Plus 自带的分页功能，避免引入额外的依赖。MyBatis-Plus 的分页功能也在不断完善，在一些场景下可以替代 PageHelper。

通过以上步骤，你应该能够解决 MybatisPlus 和 PageHelper 分页冲突的问题，并实现正确的分页功能。记住，版本兼容性是解决问题的关键。