错？手把手教你排查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.1PageHelper: 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.2JSQLParser 4.5解析器实现基于JavaCC完全重写API稳定性较低较高语法支持有限更全面性能一般显著提升通过调试代码我发现问题出在MyBatis-Plus尝试使用JSQLParser 4.5解析SQL时由于类加载器加载了PageHelper提供的3.2版本导致解析失败。3. 解决方案对比与实践面对这种依赖冲突通常有三种解决思路3.1 排除PageHelper中的JSQLParser这是最简单的解决方案让PageHelper使用MyBatis-Plus提供的JSQLParser 4.5dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper/artifactId version5.3.2/version exclusions exclusion groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId /exclusion /exclusions /dependency优点改动最小只需排除一个依赖保持MyBatis-Plus的原生行为缺点PageHelper可能对特定JSQLParser版本有隐式依赖如果PageHelper后续升级依赖版本可能需要重新调整3.2 统一排除并显式引入JSQLParser更彻底的解决方案是统一排除所有传递依赖然后显式引入特定版本dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.4.1/version exclusions exclusion groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId /exclusion /exclusions /dependency dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper/artifactId version5.3.2/version exclusions exclusion groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId /exclusion /exclusions /dependency !-- 显式引入统一版本 -- dependency groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId version4.5/version /dependency优点完全控制JSQLParser版本避免任何潜在的版本冲突适合复杂项目依赖管理缺点配置较为繁琐需要确保所选版本与所有依赖兼容3.3 升级MyBatis-Plus版本理论上升级MyBatis-Plus到最新版本可能解决兼容性问题。但这种方法有几个潜在风险商业项目稳定性风险新版本可能引入未知问题API变更风险MyBatis-Plus不同版本间API可能有变化级联升级需求可能需要同时升级其他依赖提示在生产环境中升级核心框架版本前务必在测试环境充分验证并准备好回滚方案。4. 预防依赖冲突的最佳实践通过这次排查我总结了几条预防类似问题的经验定期检查依赖树mvn dependency:tree -Dincludescom.github.jsqlparser使用dependencyManagement统一版本dependencyManagement dependencies dependency groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId version4.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版本编写集成测试验证分页功能
MyBatis-Plus和PageHelper混用，分页查询报count()错？手把手教你排查JSQLParser版本冲突
发布时间：2026/5/20 2:35:17
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.1PageHelper: 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.2JSQLParser 4.5解析器实现基于JavaCC完全重写API稳定性较低较高语法支持有限更全面性能一般显著提升通过调试代码我发现问题出在MyBatis-Plus尝试使用JSQLParser 4.5解析SQL时由于类加载器加载了PageHelper提供的3.2版本导致解析失败。3. 解决方案对比与实践面对这种依赖冲突通常有三种解决思路3.1 排除PageHelper中的JSQLParser这是最简单的解决方案让PageHelper使用MyBatis-Plus提供的JSQLParser 4.5dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper/artifactId version5.3.2/version exclusions exclusion groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId /exclusion /exclusions /dependency优点改动最小只需排除一个依赖保持MyBatis-Plus的原生行为缺点PageHelper可能对特定JSQLParser版本有隐式依赖如果PageHelper后续升级依赖版本可能需要重新调整3.2 统一排除并显式引入JSQLParser更彻底的解决方案是统一排除所有传递依赖然后显式引入特定版本dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.4.1/version exclusions exclusion groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId /exclusion /exclusions /dependency dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper/artifactId version5.3.2/version exclusions exclusion groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId /exclusion /exclusions /dependency !-- 显式引入统一版本 -- dependency groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId version4.5/version /dependency优点完全控制JSQLParser版本避免任何潜在的版本冲突适合复杂项目依赖管理缺点配置较为繁琐需要确保所选版本与所有依赖兼容3.3 升级MyBatis-Plus版本理论上升级MyBatis-Plus到最新版本可能解决兼容性问题。但这种方法有几个潜在风险商业项目稳定性风险新版本可能引入未知问题API变更风险MyBatis-Plus不同版本间API可能有变化级联升级需求可能需要同时升级其他依赖提示在生产环境中升级核心框架版本前务必在测试环境充分验证并准备好回滚方案。4. 预防依赖冲突的最佳实践通过这次排查我总结了几条预防类似问题的经验定期检查依赖树mvn dependency:tree -Dincludescom.github.jsqlparser使用dependencyManagement统一版本dependencyManagement dependencies dependency groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId version4.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版本编写集成测试验证分页功能
![千问 LeetCode 2499.让数组不相等的最小总代价 public long minimumTotalCost(int[] nums1, int[] nums2)](http://pic.xiahunao.cn/yaotu/千问 LeetCode 2499.让数组不相等的最小总代价 public long minimumTotalCost(int[] nums1, int[] nums2))
![DeepSeek LeetCode 2503.矩阵查询可获得的最大分数 public int[] maxPoints(int[][] grid, int[] queries)](http://pic.xiahunao.cn/yaotu/DeepSeek LeetCode 2503.矩阵查询可获得的最大分数 public int[] maxPoints(int[][] grid, int[] queries))
