MyBatis-Plus和PageHelper混用，分页查询报count()错？手把手教你排查JSQLParser版本冲突
MyBatis-Plus与PageHelper混用引发的JSQLParser版本冲突全解析
最近在重构一个老项目时，我遇到了一个令人抓狂的问题——原本运行良好的分页查询突然开始报count()相关的SQL解析错误。更诡异的是，这个功能之前一直正常工作，最近也没有修改过相关代码。经过长达两天的排查，最终发现是MyBatis-Plus和PageHelper混用导致的JSQLParser版本冲突问题。这个问题在Java后端开发中相当典型，特别是当项目同时使用这两个流行的分页插件时。
1. 问题现象与初步排查
那天下午，我正在开发一个管理后台的分页查询接口，突然收到了一连串的错误报警。控制台输出的错误信息大致如下：
Caused by: net.sf.jsqlparser.parser.ParseException: Encountered unexpected token: "(" "(" at line 1, column 15.这个错误发生在执行分页查询的count()语句时。奇怪的是，相同的代码在上周还运行良好，最近也没有修改过任何分页相关的逻辑。
首先，我检查了项目中的依赖版本：
- MyBatis-Plus: 3.4.1
- PageHelper: 5.3.2
这两个版本理论上应该是兼容的。于是我开始怀疑是不是Maven依赖出现了问题。运行mvn dependency:tree命令后，果然发现了猫腻：
[INFO] +- com.baomidou:mybatis-plus-boot-starter:jar:3.4.1:compile [INFO] | \- com.github.jsqlparser:jsqlparser:jar:4.5:compile [INFO] +- com.github.pagehelper:pagehelper:jar:5.3.2:compile [INFO] | \- com.github.jsqlparser:jsqlparser:jar:3.2:compile可以看到，MyBatis-Plus引入了JSQLParser 4.5，而PageHelper依赖的是JSQLParser 3.2。这就是典型的依赖冲突！
2. 深入理解JSQLParser的作用
JSQLParser是一个Java编写的SQL语句解析器，它能够将SQL语句解析为Java对象，便于程序分析和修改。在分页插件中，它的主要作用有两个：
- 解析原始SQL：识别查询的主体部分
- 生成count查询：将原始查询转换为计算总数的SQL
不同版本的JSQLParser在语法解析上可能存在差异。特别是从3.x升级到4.x时，项目进行了大规模重构，导致API不兼容。
关键差异对比：
| 特性 | JSQLParser 3.2 | JSQLParser 4.5 |
|---|---|---|
| 解析器实现 | 基于JavaCC | 完全重写 |
| API稳定性 | 较低 | 较高 |
| 语法支持 | 有限 | 更全面 |
| 性能 | 一般 | 显著提升 |
通过调试代码，我发现问题出在MyBatis-Plus尝试使用JSQLParser 4.5解析SQL时，由于类加载器加载了PageHelper提供的3.2版本，导致解析失败。
3. 解决方案对比与实践
面对这种依赖冲突，通常有三种解决思路：
3.1 排除PageHelper中的JSQLParser
这是最简单的解决方案，让PageHelper使用MyBatis-Plus提供的JSQLParser 4.5：
<dependency> <groupId>com.github.pagehelper</groupId> <artifactId>pagehelper</artifactId> <version>5.3.2</version> <exclusions> <exclusion> <groupId>com.github.jsqlparser</groupId> <artifactId>jsqlparser</artifactId> </exclusion> </exclusions> </dependency>优点：
- 改动最小，只需排除一个依赖
- 保持MyBatis-Plus的原生行为
缺点：
- PageHelper可能对特定JSQLParser版本有隐式依赖
- 如果PageHelper后续升级依赖版本，可能需要重新调整
3.2 统一排除并显式引入JSQLParser
更彻底的解决方案是统一排除所有传递依赖，然后显式引入特定版本：
<dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.4.1</version> <exclusions> <exclusion> <groupId>com.github.jsqlparser</groupId> <artifactId>jsqlparser</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>com.github.pagehelper</groupId> <artifactId>pagehelper</artifactId> <version>5.3.2</version> <exclusions> <exclusion> <groupId>com.github.jsqlparser</groupId> <artifactId>jsqlparser</artifactId> </exclusion> </exclusions> </dependency> <!-- 显式引入统一版本 --> <dependency> <groupId>com.github.jsqlparser</groupId> <artifactId>jsqlparser</artifactId> <version>4.5</version> </dependency>优点：
- 完全控制JSQLParser版本
- 避免任何潜在的版本冲突
- 适合复杂项目依赖管理
缺点：
- 配置较为繁琐
- 需要确保所选版本与所有依赖兼容
3.3 升级MyBatis-Plus版本
理论上，升级MyBatis-Plus到最新版本可能解决兼容性问题。但这种方法有几个潜在风险：
- 商业项目稳定性风险：新版本可能引入未知问题
- API变更风险：MyBatis-Plus不同版本间API可能有变化
- 级联升级需求：可能需要同时升级其他依赖
提示：在生产环境中升级核心框架版本前，务必在测试环境充分验证，并准备好回滚方案。
4. 预防依赖冲突的最佳实践
通过这次排查，我总结了几条预防类似问题的经验：
定期检查依赖树：
mvn dependency:tree -Dincludes=com.github.jsqlparser使用dependencyManagement统一版本：
<dependencyManagement> <dependencies> <dependency> <groupId>com.github.jsqlparser</groupId> <artifactId>jsqlparser</artifactId> <version>4.5</version> </dependency> </dependencies> </dependencyManagement>避免功能重叠的库混用：MyBatis-Plus和PageHelper都提供分页功能，尽量选择其中一个
建立依赖变更记录：任何依赖调整都应该记录并通知团队
常见依赖冲突排查步骤：
- 重现问题并分析错误堆栈
- 检查相关依赖的版本
- 生成依赖树分析冲突
- 确定解决方案并测试
- 记录解决方案和原因
5. 深入理解分页插件工作原理
为了更好地理解这个问题，我们需要了解这两个分页插件的工作原理：
MyBatis-Plus分页流程：
- 创建
IPage参数对象 - 拦截器
MybatisPlusInterceptor拦截查询 - 使用JSQLParser解析原始SQL
- 生成count查询并执行
- 修改原始SQL添加分页条件
- 执行分页查询
PageHelper分页流程：
- 通过
PageHelper.startPage()设置分页参数 - 拦截器
PageInterceptor拦截查询 - 使用JSQLParser解析SQL
- 生成count查询
- 修改SQL添加分页逻辑
两者都依赖JSQLParser，但实现细节和对JSQLParser版本的适应性不同，这就导致了混用时的兼容性问题。
在实际项目中，如果必须同时使用这两个插件，建议：
- 明确区分使用场景（如MyBatis-Plus用于常规分页，PageHelper用于特殊复杂查询）
- 统一JSQLParser版本
- 编写集成测试验证分页功能