如果你在后端日志里看到java.lang.NoClassDefFoundError: net/sf/jsqlparser/statement/select/SelectBody或者被 MyBatis-Plus 分页插件、ShardingSphere 解析器、某个自研 SQL 工具拦腰截断大概率不是 SQL 写错了而是整个 Java 生态里一个老牌 SQL 解析库 JSQLParser 的版本分裂问题。这个报错看起来像一个类找不到追下去却往往是一连串依赖冲突、包名迁移和框架版本不匹配的连锁反应。这类报错在高并发业务系统的运行时、单元测试启动期、甚至 Maven 打包阶段都可能出现凡是参与过一个 SQL 解析库被多个框架间接引用的项目大概率都踩过。这篇文章按我实际排查的顺序来写从堆栈形态、依赖树定位、框架版本匹配到 SQL 兼容性挨个拆最后给一张可直接抄的速查表帮你把net.sf.jsqlparser开头的报错一次根治。1. 先看懂报错从堆栈形态反推根因1.1 SelectBody 这个类到底是谁看包名statement.select就知道这是 JSQLParser 解析 SQL 时用来承载查询主体的接口。一条 SQL 进来JSQLParser 会生成一棵 AST 语法树SelectBody是树里最核心的节点普通查询PlainSelect、集合操作SetOperationList、带WITH的查询都会实现它。为了便于理解可以把SelectBody想象成 SELECT 语句的骨架解析器负责把字符串按规则填进骨架业务层再通过 getter 从骨架里取表名、取条件、取排序字段。这个类的名字本身没有歧义关键是包路径。老版本文档和大量教程里写的是net.sf.jsqlparser.statement.select.SelectBody新版项目里写的是com.github.jsqlparser.statement.select.SelectBody。一字之差类加载器就会把它们当成两个完全不同的类。很多框架内部拿到一个解析好的对象强转到另一个包名下的接口就抛出了标题里这个异常。所以刚开始看到这个报错不要急着怀疑 SQL 语法。报错信息里出现的是类名不是语法错误提示这往往意味着类加载链路出了问题。1.2 堆栈中常见的三种形态同样是net.sf.jsqlparser.statement.select.SelectBody不同项目抛出的实际异常类型可能完全不同排查方向也跟着变。第一种是java.lang.NoClassDefFoundError: net/sf/jsqlparser/statement/select/SelectBody。这种是运行期 JVM 加载已编译代码时发现旧包路径的类不存在通常是代码或某个框架编译期引用了旧版运行期 classpath 里却没有。场景很典型你 git pull 了同事的最新代码他换了框架版本本地 jar 没重新拉干净或者公共模块里编译好的 class 还在引用老类。第二种是java.lang.ClassNotFoundException: net.sf.jsqlparser.statement.select.SelectBody。这种是显式反射调用Class.forName时找不到类常见于中间件、SPI 初始化场景。Tomcat 加载 Web 应用的类加载器顺序问题也会触发但一般先归因到依赖缺失。第三种最折磨人java.lang.ClassCastException: com.github.jsqlparser.statement.select.PlainSelect cannot be cast to net.sf.jsqlparser.statement.select.SelectBody。这种是 classpath 里同时存在两个版本的 jar一个类被加载成新版PlainSelect代码却期待旧版接口强转失败。报错定位到的代码本身没写错错的是类身份分裂。遇到这种基本可以直接判定依赖冲突。1.3 真正祸根包名迁移造成的版本分裂为什么同一套 SQL 解析器会裂成两个类因为 JSQLParser 在 2.0 版本经历了完整迁移。1.x 时代项目托管在 SourceForge坐标是net.sf.jsqlparser:jsqlparser包名也叫net.sf.jsqlparser。后来整个项目迁到 GitHub从 2.0 开始groupId 改成com.github.jsqlparser包名也同步改成com.github.jsqlparser。这本来是一次正常的开源项目维护动作但它给所有使用方挖了一个大坑旧教程、老代码里全是net.sf的 import新框架、新 starter 里全是com.github的依赖。两者在 Maven 里是不同 groupId不会被依赖仲裁机制覆盖可以同时存在于 classpath。于是同一个工程里可能出现两个长得完全不一样的SelectBody。我见过一个真实案例项目里 MyBatis-Plus 3.4 自带了com.github.jsqlparser:jsqlparser:4.2开发同学却因为在老博客里抄了一段自定义 SQL 解析代码手动引入了net.sf.jsqlparser:jsqlparser:1.4。编译不报错因为两个包的 API 都能编译启动不报错因为类都是懒加载第一次走分页查询时框架内部拿PlainSelect往旧版SelectBody上强转立刻炸穿。这个事给我的教训是以后看到 SQL 解析库的报错先查家谱再查语法。2. 依赖冲突排查用 Maven 依赖树锁定真凶2.1 正确读取依赖树要确认是不是依赖冲突第一步是跑 Maven 依赖树。我喜欢用这两条命令mvn dependency:tree -Dincludescom.github.jsqlparser:jsqlparser mvn dependency:tree -Dincludesnet.sf.jsqlparser:jsqlparser分别查两个坐标看谁把它们带进来了。如果想偷懒直接mvn dependency:tree | grep -i jsqlparser也行但输出会混在一起不如分开看得清楚。典型的冲突输出长这样[INFO] - com.baomidou:mybatis-plus-extension:jar:3.5.3:compile [INFO] | \- com.github.jsqlparser:jsqlparser:jar:4.7:compile [INFO] - net.sf.jsqlparser:jsqlparser:jar:1.4:compile看到这个结构根因基本坐实mybatis-plus-extension带来一套com.github解析器业务模块或某个子工程又直接声明了一套net.sf解析器。Maven 的版本仲裁解决不了这个问题因为两个坐标分属不同 groupId会同时保留。于是 classpath 里既有一大堆com.github.jsqlparser的类又有一大堆net.sf.jsqlparser的类框架内部一旦强转必炸。还有一种情况是同一个 groupId 下的版本冲突比如两个依赖分别引入 4.2 和 4.7Maven 会选择路径最近的版本。这种冲突通常不报NoClassDefFoundError而是报NoSuchMethodError例如找不到getSelectBody()或某个新方法签名。这两种形态要分开记排查方向完全不同。2.2 用 jar 包内容验证类身份依赖树只能告诉你声明了哪些版本不能直接证明加载了哪些类。遇到依赖树正常但运行期仍报错的情况我建议直接用命令看 jar 内容jar tf ~/.m2/repository/net/sf/jsqlparser/jsqlparser/1.4/jsqlparser-1.4.jar | grep SelectBody jar tf ~/.m2/repository/com/github/jsqlparser/jsqlparser/4.7/jsqlparser-4.7.jar | grep SelectBody如果第一个 jar 空手而归第二个 jar 能搜出一堆com/github/jsqlparser/statement/select下的类那就说明你项目里声明的旧版依赖实际上不存在这个类真正的类都在新版 jar 里。此时抛NoClassDefFoundError就很好理解了classpath 里虽然有旧 jar但它本身就不包含新版接口JVM 找遍所有 jar 也找不到net.sf下的SelectBody。如果两个 jar 里都能搜到对应类那问题就是同时加载了新旧两个体系。这时用 Arthas 里的sc -d net.sf.jsqlparser.statement.select.SelectBody能看到它的 ClassLoader 来源通常会发现它来自某个非预期的 jar。2.3 收敛依赖的操作细节锁定版本最干净的办法是在父 POM 里加依赖管理dependencyManagement dependencies dependency groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId version4.7/version /dependency /dependencies /dependencyManagement然后在真正不需要旧版的地方排除掉传递依赖dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3/version exclusions exclusion groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId /exclusion /exclusions /dependency注意如果你排除掉框架自带的 jsqlparser就必须在dependencyManagement里显式声明一个版本否则框架运行时找不到解析器会冒出新的NoClassDefFoundError。Gradle 项目可以用强制策略configurations.all { resolutionStrategy { force com.github.jsqlparser:jsqlparser:4.7 } }这里有个取舍问题把所有版本强制统一到 4.x 通常能解决 90% 的问题但少数老框架内部用的 API 在 4.x 里变了签名强制升级后可能从NoClassDefFoundError变成NoSuchMethodError。所以收敛依赖时不能只盯着一个坐标要整体看框架的兼容矩阵。3. 框架集成场景中的版本匹配3.1 MyBatis-Plus 分页插件MyBatis-Plus 是遇到这个报错最多的场景因为它的PaginationInnerInterceptor内部会调用 jsqlparser 解析 SQL把业务 SQL 拆成 count 查询和数据查询还要提取排序条件。配置方式很常见MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));如果你的工程同时存在新旧两套 jsqlparser第一次执行分页查询时插件代码进入autoCountSql要访问SelectBody里的 selectItems、from、where 节点拿到的对象却是新版本的PlainSelect强转到旧版接口时当场抛ClassCastException。我建议先看自己用的 MyBatis-Plus 版本对应哪一代 jsqlparserMyBatis-Plus 版本默认 jsqlparser 坐标包名体系3.3.xcom.github.jsqlparser:jsqlparser:2.1com.github.jsqlparser3.4.xcom.github.jsqlparser:jsqlparser:4.2 左右com.github.jsqlparser3.5.xcom.github.jsqlparser:jsqlparser:4.7 左右com.github.jsqlparser注意MyBatis-Plus 3.3 之后基本都走com.github体系了。如果项目里出现net.sf的类多半是开发同学手动引入的旧教程依赖或者某个老版本公共模块传递进来的。排除思路很简单保留 MyBatis-Plus 自带的版本把额外声明的net.sf.jsqlparser:jsqlparser全部排除。3.2 ShardingSphere 解析引擎ShardingSphere 4.x 的 SQL 解析层直接依赖 jsqlparser用它把 SQL 解析成 AST 再做分片改写。4.1.1 对应的是 jsqlparser 4.0 左右坐标是com.github.jsqlparser。如果你在业务代码里手动写了一段net.sf.jsqlparser的解析逻辑又正好跑在 ShardingSphere 管理的连接上两个解析器一碰撞报错内容基本就是标题这串类名。ShardingSphere 5.x 已经用自研的 Antlr 解析器替换了 jsqlparser不再直接依赖它。但从 4.x 升级上来的项目代码里可能还残留一堆import net.sf.jsqlparser.statement.select.SelectBody的调用。这种兼容性断裂不是靠 Maven 锁版本能解决的得把自定义解析代码迁移到 ShardingSphere 的ParseTree接口或者干脆用新版 API 重写。如果你现在做新项目建议不要同时引入 MyBatis-Plus 分页插件和 ShardingSphere 4.x。两者都会解析和改写 SQL双解析器叠加版本冲突概率直线上升。更合理的设计是ShardingSphere 负责分库分表分页用Page对象传到 SQL 里由 ShardingSphere 统一改写或者完全手写分页参数。3.3 其他中间件与自研模块的共存问题除了这两个大框架还有一些场景也会碰到这个报错。比如自研的 SQL 审核、脱敏、血缘分析模块通常会直接在代码里写import net.sf.jsqlparser.statement.select.SelectBody;然后遍历 AST 做表名脱敏、字段权限控制。这类代码一旦和线上框架新版依赖冲突启动阶段就扛不住。还有一点很多人忽略Druid 本身有自己的 SQL Parser不依赖 jsqlparser。但你在项目里看到的某组件依赖了 jsqlparser很可能来自第三方 starter比如 dynamic-datasource 的某些版本会传递引用。所以遇到问题不要凭直觉找谁的代码里用了 SQL 解析直接看依赖树谁带进来的就查谁。自研代码层面最稳妥的做法是统一升级到com.github.jsqlparser的新 API。虽然要改的 import 不少但胜在长期兼容。我改造过一个老模块就是把所有net.sf.jsqlparser改成com.github.jsqlparser顺手加了一层SqlParserWrapper隔离后续再升级解析库只动 wrapper不动业务代码。4. 业务 SQL 触发解析异常的场景与改造4.1 哪些 SQL 写法让解析器翻车版本冲突解决之后另一个高频问题浮出水面SQL 本身合法但 jsqlparser 版本解析不了。这时报错不再是标题里的 class 异常而是JSQLParserException或UnsupportedOperationException。它和标题报错是两回事但现实里经常被人混淆所以我多写几笔。老版本对现代 SQL 方言的支持有限以下特征最容易踩雷MySQL 8 的WITH ... SELECT公共表表达式1.x 版本完全不认识。PostgreSQL 的INSERT ... RETURNING、Oracle 的MERGE INTO老版本解析会直接中止。SELECT ... FOR UPDATE SKIP LOCKED在旧版里会被拒。GROUP BY带WITH ROLLUP、CUBE低版本支持不完整。LATERAL派生表很多版本直接不支持。复杂注释、hint 片段比如/* INDEX(t idx) */某些版本会把 hint 当成普通注释拆错。这些情况本质上不是 SQL 写错而是解析器的能力边界。解决方向有三升级 jsqlparser 到 4.7 以上绕开框架的 SQL 解析逻辑或者改写 SQL 让它落在解析器的支持范围内。4.2 分页加 count 场景的实战改造分页插件生成 count 查询时经常因为复杂 SQL 触发解析异常。遇到这种场景我一般会直接跳过自动 count手动指定 count 查询PageUser page new Page(1, 20); page.setSearchCount(false); // 手动查 count Long total userMapper.selectCount(...);这样分页插件就不再对原 SQL 做二次解析改写只负责追加分页参数。对于WITHUNION 多层嵌套的大 SQL这招立竿见影。还有一个技巧用InterceptorIgnore注解跳过特定 Mapper 方法上的插件解析InterceptorIgnore(tenantLine true) ListUser queryComplex(Param(ew) WrapperUser wrapper);但它只对 MyBatis-Plus 的拦截器生效ShardingSphere 的解析器不受这个控制。如果复杂 SQL 必须走分库分表那老老实实把所有逻辑收进视图或者拆成多次查询在应用层组装。给解析器减轻压力的同时也是给数据库优化器减轻压力。5. 速查表与个人排查经验5.1 快速诊断五步法以后再遇到net.sf.jsqlparser.statement.select.SelectBody相关报错按这个顺序来先看第一个Caused by确认是NoClassDefFoundError、ClassNotFoundException、ClassCastException还是NoSuchMethodError。执行两条依赖树命令分别查com.github.jsqlparser:jsqlparser和net.sf.jsqlparser:jsqlparser。用jar tf验证两个 jar 里是否有对应类判断是缺类还是类重复。决定统一到哪个版本在dependencyManagement加版本锁定在多余依赖上做 exclusions。重新打包后先跑一次冒烟测试重点关注分页、SQL 解析相关链路。如果运行期不想重启排查Arthas 的sc -d net.sf.jsqlparser.statement.select.SelectBody能直接告诉你是被哪个 ClassLoader 加载的、classpath 里到底有没有。这一步可以快速区分本地依赖树对运行环境不对的诡异场景。5.2 报错片段与解法对照表报错片段可能原因首选解决方向NoClassDefFoundError: net/sf/jsqlparser/statement/select/SelectBody编译期引用了旧版运行期 classpath 缺类统一依赖版本确保旧 jar 的类真实存在ClassNotFoundException: net.sf.jsqlparser...SelectBody反射加载旧类classpath 里没有检查传递依赖补上或排除对应坐标ClassCastException: com.github...PlainSelect cannot be cast to net.sf...SelectBody新旧两套解析器同时存在排除一套只保留一个包名体系NoSuchMethodError: ...getSelectBody()同一坐标版本不一致API 签名变了用dependencyManagement锁版本JSQLParserExceptionSQL 语法超出当前版本解析能力升级 jsqlparser 或改写 SQL这张表我贴在团队 Wiki 里很久了每次有人报这个错先自己对号入座再决定要不要拉我进排查群。不少同事一开始都以为是数据库语法问题对着 SQL改格式改半天最后发现是 jar 包混乱。5.3 推荐版本组合与踩坑记录如果你问我现在用什么组合最省心我会说Spring Boot 2.7 MyBatis-Plus 3.5.3 的组合jsqlparser 跟着 MP 走就行不要额外手动声明任何 jsqlparser 依赖。Spring Boot 3.x 项目用 MyBatis-Plus 3.5.4 以上同理MP 自带版本已经比较新。如果项目被迫保留 ShardingSphere 4.x尽量不要让它和 MyBatis-Plus 分页插件同时工作。分库分表场景下分页逻辑交给 ShardingSphere 统一处理MyBatis-Plus 只做基础 CRUD两个解析器各管一段冲突概率会小很多。如果老工程逻辑实在动不了还有一个保守方案把所有依赖锁到net.sf.jsqlparser:jsqlparser:1.4但前提是你的框架版本都兼容 1.4。这个方案的维护成本逐年上升因为新版框架都在向com.github靠拢只能作为临时止血不能当长期策略。踩过几次坑之后我的体会是SQL 解析库相关的报错八成是版本问题两成才是语法问题。与其盯着报错里的类名猜不如先花两分钟把依赖树导出来让 classpath 里到底有哪几套解析器一目了然。这个习惯帮我省掉了很多不必要的加班。