我最早在系统里认真引入JSqlParser是因为做内部数据网关时遇到一个很实际的需求所有写操作必须强制携带WHERE条件所有查询语句要自动拼上租户隔离条件上线前还要把每条业务SQL里的表名、列名捞出来做一遍权限白名单。当时我的第一反应是写正则结果线上环境很快教我做人——SQL注释、大小写、子查询、字符串里藏关键字各种边角情况让正则越写越长、越改越脆最后还是老老实实换成了JSqlParser。这篇文章就是那段时间实战经验的完整总结。我会从为什么正则搞不定SQL解析讲起再带你走一遍JSqlParser的接入流程、核心的Visitor机制最后给出三个可以直接抄进项目的生产级场景SQL审计、分页改写、脱敏和行级权限以及版本迁移和性能方面的踩坑记录。不管你是做数据平台、中间件还是普通业务系统里想对SQL做二次加工这篇内容应该都能直接帮上忙。1. 从正则失控到ASTJSqlParser解决的到底是什么问题1.1 正则匹配SQL的三大死穴先看一个最典型的例子。你准备拦截所有DELETE语句于是写了类似这样的正则if (sql.toUpperCase().matches(.*\\bDELETE\\b.*)) { // 判定为危险SQL }表面上它能匹配DELETE FROM t WHERE id 1但下面的SQL它一样会误判SELECT * FROM operation_log WHERE detail 用户执行了DELETE操作更离谱的是如果你用同样的思路去反过来判断这是不是一条查询还会被字符串字面量里的内容骗得团团转。SQL文本的解析难点在于关键字可能出现在字符串里、注释里也可能被换行和空格分隔得七零八落引号内部还有转义规则比如SQL里两个连续单引号表示一个单引号字符。这些都不是正则能干净处理的问题——要正确区分关键字和字符串内容你本质上已经需要实现一个词法分析器了。第二个死穴是结构识别。就算你勉强用正则匹配到了表名也拿不到哪一段是WHERE条件、哪一段是子查询、哪一段是JOIN的右侧表这样的结构信息。分页改写、租户条件拼接、列脱敏这些操作全都依赖准确的结构定位。第三个死穴是维护成本。每条业务SQL都有各种变形你每修掉一个边界情况正则就膨胀一层最终变成一团谁都看不懂的字符迷宫。我见过生产环境里一百多行的超长正则与其说是技术方案不如说是技术债。1.2 JSqlParser的定位SQL文本与对象树之间的翻译官JSqlParser做的事情本质上很单纯它把一段SQL文本解析成一棵Java对象树AST抽象语法树。顶层是Statement接口针对不同语句类型有不同实现——Select、Insert、Update、Delete、CreateTable、Truncate等等。往下拆Select里有一个SelectBody最常用的是PlainSelect它对应一条普通SELECT查询查询列、来源表、JOIN、WHERE、GROUP BY、ORDER BY、LIMIT全都挂在它上面。一旦SQL变成了对象树你对SQL的一切操作就从正则匹配文本升级为读写Java对象想改WHERE就setWhere新的条件表达式想查表名就遍历FromItem想加LIMIT就构造一个Limit对象塞进去。改完之后调用statement.toString()就能把对象树重新渲染成SQL文本。这里有个很能说明可信度的背景你平时用的MyBatis-Plus分页插件底层做SQL改写用的就是JSqlParser。网上搜mybatisplus根据java实体类生成创建表的sql语句这类需求时也经常会碰到它。也就是说这套解析能力是经过海量生产环境验证的不是某个Github小项目自娱自乐。2. 环境接入与第一条解析代码把SQL变成对象树的完整路径2.1 Maven依赖与版本选择引入方式很简单一个依赖就够了dependency groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId version4.9/version /dependency版本选择我的建议是新项目无脑4.x老项目如果没特殊原因也尽快从3.x迁过来。网上搜到的大量教程和博客写的是3.x的API和4.x差别不小——最典型的就是Select.getPlainSelect()这种老写法在新版本里已经不被推荐了要改成select.getSelectBody()。如果你们项目里有MyBatis-Plus或其他中间件传递依赖了老版本记得用Maven的dependencyManagement把版本统一起来不然运行时很容易出现NoSuchMethodError。2.2 最小示例parse()和parseStatements()的差别解析入口是CCJSqlParserUtil工具类使用套路非常固定import net.sf.jsqlparser.parser.CCJSqlParserUtil; import net.sf.jsqlparser.statement.Statement; import net.sf.jsqlparser.statement.select.Select; String sql SELECT id, name, age FROM users WHERE status 1 ORDER BY id DESC; Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Select select) { System.out.println(select.getSelectBody().getClass()); } System.out.println(重新生成的SQL: statement);运行结果是class net.sf.jsqlparser.statement.select.PlainSelect最后一行打印出来的是被解析器规范化过的SQL文本。这里有两个容易踩的点第一parse()方法只接受单条SQL遇到分号切分的多条语句会直接抛JSQLParserException第二如果需要批量处理多条语句要用parseStatements()它返回ListStatement。比如你要分析一个MyBatis的Mapper XML里全部的SQL片段或者做SQL脚本扫描用后者就对了。2.3 拆解PlainSelectSELECT语句的对象树长什么样拿到PlainSelect之后常用的方法就这几个getSelectItems()查询列列表每一项是SelectExpressionItem或者SelectAllItemgetFromItem()主表可能是Table也可能是SubSelect子查询、ParenthesedSelect括号包裹的子查询getJoins()JOIN列表每个Join对象用getRightItem()拿到JOIN右侧的表或子查询getWhere()过滤条件返回一个Expression可能是EqualsTo、AndExpression、InExpression等getGroupBy()、getOrderByElements()、getLimit()分别对应分组、排序、分页getDistinct()对应SELECT DISTINCT做过SQL去重查询改写的话会碰到它。理解这棵对象树有个生活化的类比SQL文本是超市的购物小票JSqlParser按照固定的排版规则把每一件商品分门别类放进对应的抽屉FromItem抽屉里躺着买了什么Where抽屉里躺着采购条件你想要哪一类就去哪个抽屉拿而不是在一整张小票上反复肉眼扫描。3. Visitor机制访问者模式如何简化AST遍历3.1 不用Visitor会怎样instanceof地狱假设你想写一个工具提取一条SQL里出现的所有表名。没有Visitor的话你得先instanceof判断是不是PlainSelect再判断FromItem是不是Table不是Table就判断是不是SubSelect是SubSelect还得把它内部的SelectBody再重复来一轮碰到JOIN里的子查询又是一轮。代码会迅速变成层层嵌套的instanceof判断逻辑稍微复杂一点就令人头大。Visitor模式解决这个问题的思路是反转控制你不必主动去问这个节点是什么类型而是把你自己作为访问者交给对象树让每个节点主动调用你对应的visit方法。沿用生活类比这就好比住酒店时不是你自己一间间敲门问你是不是行政房而是房务人员拿着访客名单挨个房间带你进去处理该处理的事。3.2 三种VisitorStatementVisitor、SelectVisitor、ExpressionVisitorJSqlParser里常用的Visitor分成三个层级StatementVisitor站在顶层负责Select、Insert、Update、Delete、CreateTable等语句级节点的分发SelectVisitor站在查询内部负责PlainSelect、SetOperationListUNION系列、WithItemCTE、ParenthesedSelect这些查询体的分发ExpressionVisitor站在表达式层面负责Column列引用、LongValue数字、EqualsTo等比较表达式、AndExpression逻辑表达式、Function函数调用等的分发。实际开发时我不建议直接实现Visitor接口因为接口方法太多。直接用官方提供的Adapter类就好StatementVisitorAdapter、SelectVisitorAdapter、ExpressionVisitorAdapter它们把所有方法都实现了空版本你只需要重写关心的那一两个方法。3.3 完整示例提取表名和查询列的通用工具我把工作里最常用的SQL元信息提取器整理成可直接运行的代码提取表名和查询列import net.sf.jsqlparser.expression.Column; import net.sf.jsqlparser.expression.ExpressionVisitorAdapter; import net.sf.jsqlparser.parser.CCJSqlParserUtil; import net.sf.jsqlparser.schema.Table; import net.sf.jsqlparser.statement.Statement; import net.sf.jsqlparser.statement.select.*; import java.util.ArrayList; import java.util.List; public class SqlMetaExtractor { private final ListString tables new ArrayList(); private final ListString columns new ArrayList(); public static SqlMetaExtractor extract(String sql) throws Exception { Statement statement CCJSqlParserUtil.parse(sql); if (!(statement instanceof Select select)) { throw new IllegalArgumentException(只支持 SELECT 语句); } return new SqlMetaExtractor().analyze(select); } private SqlMetaExtractor analyze(Select select) { select.getSelectBody().accept(selectVisitor); return this; } private final SelectVisitor selectVisitor new SelectVisitorAdapter() { Override public void visit(PlainSelect plainSelect) { collectFromItem(plainSelect.getFromItem()); if (plainSelect.getJoins() ! null) { for (Join join : plainSelect.getJoins()) { collectFromItem(join.getRightItem()); } } for (SelectItem? selectItem : plainSelect.getSelectItems()) { if (selectItem instanceof SelectExpressionItem expressionItem expressionItem.getExpression() instanceof Column column) { columns.add(column.getColumnName()); } } if (plainSelect.getWhere() ! null) { plainSelect.getWhere().accept(expressionVisitor); } } }; private final ExpressionVisitor expressionVisitor new ExpressionVisitorAdapter() { Override public void visit(Column column) { columns.add(column.getColumnName()); } }; private void collectFromItem(FromItem fromItem) { if (fromItem instanceof Table table) { tables.add(table.getName()); } else if (fromItem instanceof SubSelect subSelect) { subSelect.getSelectBody().accept(selectVisitor); } else if (fromItem instanceof ParenthesedSelect parenthesedSelect) { parenthesedSelect.getSelectBody().accept(selectVisitor); } } public ListString getTables() { return tables; } public ListString getColumns() { return columns; } public static void main(String[] args) throws Exception { String sql SELECT u.id, u.name, o.order_no FROM users u JOIN orders o ON u.id o.user_id WHERE u.age 18 AND o.status 1; SqlMetaExtractor meta SqlMetaExtractor.extract(sql); System.out.println(表: meta.getTables()); System.out.println(列: meta.getColumns()); } }输出表: [users, orders] 列: [id, name, order_no, age, status]两个细节提醒。第一如果WHERE条件里还藏着子查询比如WHERE id IN (SELECT user_id FROM blacklist)上面这个例子不会自动把blacklist表捞出来因为ExpressionVisitorAdapter默认不会递归进子查询体。要处理这种情况再重写ExpressionVisitor的visit(SubSelect)方法手动调用subSelect.getSelectBody().accept(selectVisitor)即可。第二任何提取逻辑都不要假设字段非空getJoins()、getWhere()、getOrderByElements()返回null是非常常见的事。3.4 修改AST给WHERE动态追加租户条件的标准姿势解析不只是用来读更常用的是改。下面这段代码是行级权限场景的核心逻辑给查询SQL动态追加一个租户条件。import net.sf.jsqlparser.expression.Expression; import net.sf.jsqlparser.expression.StringValue; import net.sf.jsqlparser.expression.operators.relational.EqualsTo; import net.sf.jsqlparser.expression.operators.relational.AndExpression; import net.sf.jsqlparser.parser.CCJSqlParserUtil; import net.sf.jsqlparser.schema.Column; import net.sf.jsqlparser.statement.Statement; import net.sf.jsqlparser.statement.select.PlainSelect; import net.sf.jsqlparser.statement.select.Select; public String appendTenantCondition(String sql, String tenantColumn, String tenantValue) throws Exception { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Select select select.getSelectBody() instanceof PlainSelect plainSelect) { Expression tenantCondition new EqualsTo( new Column(tenantColumn), new StringValue(tenantValue) ); if (plainSelect.getWhere() null) { plainSelect.setWhere(tenantCondition); } else { plainSelect.setWhere(new AndExpression(plainSelect.getWhere(), tenantCondition)); } return select.toString(); } return sql; }这个方法的巧妙之处在于我完全不用关心原SQL里有没有ORDER BY、有没有LIMIT、有没有GROUP BY因为setWhere()只是替换了AST里条件这一个节点其它节点纹丝不动。要是用字符串拼接你得先判断WHERE关键字的位置还得注意不能把条件插到JOIN ON错误的位置复杂SQL换个写法就全崩。这就是AST修改最大的价值。4. 三个生产级实战场景审计、分页、脱敏4.1 危险SQL拦截无WHERE条件的DELETE/UPDATE直接拒绝我在数据网关里做的最简单也最刚需的一件事是拦截无WHERE条件的写操作。代码很短import net.sf.jsqlparser.statement.delete.Delete; import net.sf.jsqlparser.statement.update.Update; import net.sf.jsqlparser.statement.truncate.Truncate; public static void auditForMutation(String sql) throws Exception { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Delete delete) { if (delete.getWhere() null) { throw new IllegalStateException(拦截DELETE语句缺少WHERE条件); } } else if (statement instanceof Update update) { if (update.getWhere() null) { throw new IllegalStateException(拦截UPDATE语句缺少WHERE条件); } } else if (statement instanceof Truncate) { throw new IllegalStateException(拦截TRUNCATE语句被禁用); } }为什么这种方案比正则可靠因为解析器压根不关心SQL的外在形态。delete from t和DELETE\tFROM\n t甚至中间堆满注释解析出来的AST里Delete.getWhere()一样是null拦截逻辑完全一致。想绕过以后再试试把关键字拆开、把表名用反引号包起来、加多层括号解析器照样能还原出最本质的AST结构。再进一步做SQL注入风险扫描也可以基于这套AST结构。比如检查WHERE条件里是否存在恒真表达式或者扫描StringValue里是否出现可疑的注入负载。注意这里只做结构检查不要试图自己去解读SQL语义否则又变成写第二次正则了。4.2 分页改写自动给查询追加LIMIT与OFFSET中间件开发里最常见的需求是给没有分页的查询自动加上分页。MyBatis-Plus的分页插件内部也是类似逻辑import net.sf.jsqlparser.expression.LongValue; import net.sf.jsqlparser.statement.select.Limit; public String addPage(String sql, long limit, long offset) throws Exception { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Select select select.getSelectBody() instanceof PlainSelect plainSelect) { if (plainSelect.getLimit() ! null) { throw new IllegalArgumentException(原SQL已包含LIMIT); } Limit pageLimit new Limit(); pageLimit.setRowCount(new LongValue(limit)); if (offset 0) { pageLimit.setOffset(new LongValue(offset)); } plainSelect.setLimit(pageLimit); return select.toString(); } return sql; }调用addPage(SELECT * FROM orders WHERE status 1, 20, 0)生成的SQL是SELECT * FROM orders WHERE status 1 LIMIT 20如果offset传20生成的是SELECT * FROM orders WHERE status 1 LIMIT 20 OFFSET 20。这里要说一个兼容性小心得LIMIT n OFFSET m这种写法在MySQL 8.0和PostgreSQL里都支持但老版本MySQL5.6及以前只认LIMIT m, n。如果你们的数据库版本比较老就得在拿到AST之后自己控制toString的渲染方式或者干脆用Oracle的ROWNUM思路去改写。先想清楚目标数据库再动手不然线上会出大问题。另外如果原SQL已经有LIMIT我的建议是不要静默覆盖。分页中间件应该直接抛错或走另一个分支让上层决定是合并还是拒绝。很多线上故障都是我明明没让分页器改这条SQL它却偷偷把LIMIT改了导致的。4.3 列级脱敏与行级权限AST替换的另一类妙用最后一个场景是脱敏。比如用户表里有手机号字段普通接口不允许明文返回但后台报表又需要看到一定规则下的打码结果。最优雅的做法是在SQL层直接改写查询列public String maskColumn(String sql, String columnName, String maskExpression) throws Exception { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Select select select.getSelectBody() instanceof PlainSelect plainSelect) { for (SelectItem? selectItem : plainSelect.getSelectItems()) { if (selectItem instanceof SelectExpressionItem expressionItem expressionItem.getExpression() instanceof Column column column.getColumnName().equalsIgnoreCase(columnName)) { expressionItem.setExpression(CCJSqlParserUtil.parseExpression(maskExpression)); } } return select.toString(); } return sql; }调用方式String maskedSql maskColumn( SELECT id, name, phone FROM users WHERE id 1, phone, concat(left(phone, 3), ****, right(phone, 4)) );原SQL会变成SELECT id, name, concat(left(phone, 3), ****, right(phone, 4)) FROM users WHERE id 1。这里AST替换和字符串替换最大的区别是它只作用于真正代表被查询列的节点。如果某条记录里用户昵称恰好是phone这两个字母或者某条SQL的WHERE条件里出现status phone这样的字符串字面量字符串替换会全部误伤AST替换则完全免疫。行级权限就是在前面3.4节的appendTenantCondition基础上做的动态条件拼接。SaaS系统里最常见的多租户隔离本质就是给每个请求的SQL自动加上tenant_id xxx。这套逻辑我实际给好几个项目打过底稳定得很关键就是别在业务代码里手写SQL拼接统一走这个解析改写层。5. 实测复盘版本差异、失败降级与性能调优5.1 从3.x迁到4.x必须注意的API变化网上大量教程写的还是3.x时代的API直接抄会踩坑。我迁移时遇到的主要变化有这么几处变化点3.x写法4.x推荐写法获取查询体select.getPlainSelect()select.getSelectBody()括号子查询类名ParenthesisSelectParenthesedSelect查询列类型SelectItemSelectItemT泛型分组对象表达式列表GroupByElement对象4.2之后StatementVisitor新增了一些方法如果你实现的是接口而不是用Adapter升级后会发现编译报错这也是我强烈建议用Adapter的原因。迁移建议就一条先升级依赖然后把所有自定义Visitor类跑一遍编译期报错照着报错逐个改。别想着运行时慢慢发现Visitor接口的方法签名变化在编译期就能暴露大部分问题这是成本最低的迁移路径。5.2 解析失败的那些复杂SQL降级策略比解析本身更重要再强的解析器也有解析不了的时候。我遇到的失败案例大致分三类MyBatis动态SQL没有完全渲染的模板比如SQL里残留${param}或#{param}占位符这类严格来说不是合法SQL需要先渲染再解析MySQL的版本化注释/*! ... */、Oracle的CONNECT BY层次查询等方言特性在部分版本里解析器支持不完整极端复杂的嵌套视图、超长CTE链偶尔也会触发内部错误。针对这些情况我的处理原则是失败不可怕可怕的是因为失败把业务搞挂。所有调用入口统一做三件事捕获JSQLParserException以及可能的运行时异常记WARN日志并保存原始SQL返回原始SQL作为降级结果让请求继续走不在解析层拦断业务用计数器统计解析失败率超过阈值就告警把失败SQL存下来定期人工review。这个降级策略我实际用下来的感受是解析覆盖率能做到99%以上剩下的1%走原样放行业务感知不到任何变化。但前提是日志要打清楚否则排查问题时会非常痛苦。5.3 性能实测与缓存设计一个高质量的SqlParserService封装关于性能我给出一个量级参考单表单条件SELECT从解析到toString一次完整往返大概几十到一两百微秒带多个JOIN、子查询、CTE的复杂SQL可能到1~3毫秒。单次请求完全无感但如果放在每天跑几百万次的批处理链路里这个开销就不能忽视了。优化方案通常分两层。第一层是复用对同一段SQL文本把解析结果放进LRU缓存key就是SQL原文value可以是Statement对象也可以是你已经算完的提取结果。Caffeine写个几十行就能搞定缓存命中后一次字符串比较的成本几乎可以忽略。第二层是控制范围不是每条SQL都需要完整遍历AST提前用简单的关键字判断跳过明显不需要处理的语句能省下很多无谓的解析开销。这里有个容易被忽视的线程安全问题CCJSqlParserUtil.parse()每次都会新建解析器多线程安全但如果你为了性能直接复用CCJSqlParser实例它不是线程安全的并发场景会出奇怪问题。我在项目里就是把逻辑封装成一个SqlParserService统一管缓存、管解析、管异常降级业务侧只用传SQL进去、拿结果出来内部细节全部屏蔽掉。最后再补充一个我自己的小习惯statement.toString()输出的SQL不保证和输入逐字节一致解析器会把大小写、空格、换行规范化。所以如果你要做SQL签名、哈希比对一定要基于原始SQL做不要拿toString之后的结果去比否则同一个逻辑的SQL前后两次的哈希值会对不上。这个坑我栽过一次希望你们别再栽。
我最早在系统里认真引入JSqlParser是因为做内部数据网关时遇到一个很实际的需求所有写操作必须强制携带WHERE条件所有查询语句要自动拼上租户隔离条件上线前还要把每条业务SQL里的表名、列名捞出来做一遍权限白名单。当时我的第一反应是写正则结果线上环境很快教我做人——SQL注释、大小写、子查询、字符串里藏关键字各种边角情况让正则越写越长、越改越脆最后还是老老实实换成了JSqlParser。这篇文章就是那段时间实战经验的完整总结。我会从为什么正则搞不定SQL解析讲起再带你走一遍JSqlParser的接入流程、核心的Visitor机制最后给出三个可以直接抄进项目的生产级场景SQL审计、分页改写、脱敏和行级权限以及版本迁移和性能方面的踩坑记录。不管你是做数据平台、中间件还是普通业务系统里想对SQL做二次加工这篇内容应该都能直接帮上忙。1. 从正则失控到ASTJSqlParser解决的到底是什么问题1.1 正则匹配SQL的三大死穴先看一个最典型的例子。你准备拦截所有DELETE语句于是写了类似这样的正则if (sql.toUpperCase().matches(.*\\bDELETE\\b.*)) { // 判定为危险SQL }表面上它能匹配DELETE FROM t WHERE id 1但下面的SQL它一样会误判SELECT * FROM operation_log WHERE detail 用户执行了DELETE操作更离谱的是如果你用同样的思路去反过来判断这是不是一条查询还会被字符串字面量里的内容骗得团团转。SQL文本的解析难点在于关键字可能出现在字符串里、注释里也可能被换行和空格分隔得七零八落引号内部还有转义规则比如SQL里两个连续单引号表示一个单引号字符。这些都不是正则能干净处理的问题——要正确区分关键字和字符串内容你本质上已经需要实现一个词法分析器了。第二个死穴是结构识别。就算你勉强用正则匹配到了表名也拿不到哪一段是WHERE条件、哪一段是子查询、哪一段是JOIN的右侧表这样的结构信息。分页改写、租户条件拼接、列脱敏这些操作全都依赖准确的结构定位。第三个死穴是维护成本。每条业务SQL都有各种变形你每修掉一个边界情况正则就膨胀一层最终变成一团谁都看不懂的字符迷宫。我见过生产环境里一百多行的超长正则与其说是技术方案不如说是技术债。1.2 JSqlParser的定位SQL文本与对象树之间的翻译官JSqlParser做的事情本质上很单纯它把一段SQL文本解析成一棵Java对象树AST抽象语法树。顶层是Statement接口针对不同语句类型有不同实现——Select、Insert、Update、Delete、CreateTable、Truncate等等。往下拆Select里有一个SelectBody最常用的是PlainSelect它对应一条普通SELECT查询查询列、来源表、JOIN、WHERE、GROUP BY、ORDER BY、LIMIT全都挂在它上面。一旦SQL变成了对象树你对SQL的一切操作就从正则匹配文本升级为读写Java对象想改WHERE就setWhere新的条件表达式想查表名就遍历FromItem想加LIMIT就构造一个Limit对象塞进去。改完之后调用statement.toString()就能把对象树重新渲染成SQL文本。这里有个很能说明可信度的背景你平时用的MyBatis-Plus分页插件底层做SQL改写用的就是JSqlParser。网上搜mybatisplus根据java实体类生成创建表的sql语句这类需求时也经常会碰到它。也就是说这套解析能力是经过海量生产环境验证的不是某个Github小项目自娱自乐。2. 环境接入与第一条解析代码把SQL变成对象树的完整路径2.1 Maven依赖与版本选择引入方式很简单一个依赖就够了dependency groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId version4.9/version /dependency版本选择我的建议是新项目无脑4.x老项目如果没特殊原因也尽快从3.x迁过来。网上搜到的大量教程和博客写的是3.x的API和4.x差别不小——最典型的就是Select.getPlainSelect()这种老写法在新版本里已经不被推荐了要改成select.getSelectBody()。如果你们项目里有MyBatis-Plus或其他中间件传递依赖了老版本记得用Maven的dependencyManagement把版本统一起来不然运行时很容易出现NoSuchMethodError。2.2 最小示例parse()和parseStatements()的差别解析入口是CCJSqlParserUtil工具类使用套路非常固定import net.sf.jsqlparser.parser.CCJSqlParserUtil; import net.sf.jsqlparser.statement.Statement; import net.sf.jsqlparser.statement.select.Select; String sql SELECT id, name, age FROM users WHERE status 1 ORDER BY id DESC; Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Select select) { System.out.println(select.getSelectBody().getClass()); } System.out.println(重新生成的SQL: statement);运行结果是class net.sf.jsqlparser.statement.select.PlainSelect最后一行打印出来的是被解析器规范化过的SQL文本。这里有两个容易踩的点第一parse()方法只接受单条SQL遇到分号切分的多条语句会直接抛JSQLParserException第二如果需要批量处理多条语句要用parseStatements()它返回ListStatement。比如你要分析一个MyBatis的Mapper XML里全部的SQL片段或者做SQL脚本扫描用后者就对了。2.3 拆解PlainSelectSELECT语句的对象树长什么样拿到PlainSelect之后常用的方法就这几个getSelectItems()查询列列表每一项是SelectExpressionItem或者SelectAllItemgetFromItem()主表可能是Table也可能是SubSelect子查询、ParenthesedSelect括号包裹的子查询getJoins()JOIN列表每个Join对象用getRightItem()拿到JOIN右侧的表或子查询getWhere()过滤条件返回一个Expression可能是EqualsTo、AndExpression、InExpression等getGroupBy()、getOrderByElements()、getLimit()分别对应分组、排序、分页getDistinct()对应SELECT DISTINCT做过SQL去重查询改写的话会碰到它。理解这棵对象树有个生活化的类比SQL文本是超市的购物小票JSqlParser按照固定的排版规则把每一件商品分门别类放进对应的抽屉FromItem抽屉里躺着买了什么Where抽屉里躺着采购条件你想要哪一类就去哪个抽屉拿而不是在一整张小票上反复肉眼扫描。3. Visitor机制访问者模式如何简化AST遍历3.1 不用Visitor会怎样instanceof地狱假设你想写一个工具提取一条SQL里出现的所有表名。没有Visitor的话你得先instanceof判断是不是PlainSelect再判断FromItem是不是Table不是Table就判断是不是SubSelect是SubSelect还得把它内部的SelectBody再重复来一轮碰到JOIN里的子查询又是一轮。代码会迅速变成层层嵌套的instanceof判断逻辑稍微复杂一点就令人头大。Visitor模式解决这个问题的思路是反转控制你不必主动去问这个节点是什么类型而是把你自己作为访问者交给对象树让每个节点主动调用你对应的visit方法。沿用生活类比这就好比住酒店时不是你自己一间间敲门问你是不是行政房而是房务人员拿着访客名单挨个房间带你进去处理该处理的事。3.2 三种VisitorStatementVisitor、SelectVisitor、ExpressionVisitorJSqlParser里常用的Visitor分成三个层级StatementVisitor站在顶层负责Select、Insert、Update、Delete、CreateTable等语句级节点的分发SelectVisitor站在查询内部负责PlainSelect、SetOperationListUNION系列、WithItemCTE、ParenthesedSelect这些查询体的分发ExpressionVisitor站在表达式层面负责Column列引用、LongValue数字、EqualsTo等比较表达式、AndExpression逻辑表达式、Function函数调用等的分发。实际开发时我不建议直接实现Visitor接口因为接口方法太多。直接用官方提供的Adapter类就好StatementVisitorAdapter、SelectVisitorAdapter、ExpressionVisitorAdapter它们把所有方法都实现了空版本你只需要重写关心的那一两个方法。3.3 完整示例提取表名和查询列的通用工具我把工作里最常用的SQL元信息提取器整理成可直接运行的代码提取表名和查询列import net.sf.jsqlparser.expression.Column; import net.sf.jsqlparser.expression.ExpressionVisitorAdapter; import net.sf.jsqlparser.parser.CCJSqlParserUtil; import net.sf.jsqlparser.schema.Table; import net.sf.jsqlparser.statement.Statement; import net.sf.jsqlparser.statement.select.*; import java.util.ArrayList; import java.util.List; public class SqlMetaExtractor { private final ListString tables new ArrayList(); private final ListString columns new ArrayList(); public static SqlMetaExtractor extract(String sql) throws Exception { Statement statement CCJSqlParserUtil.parse(sql); if (!(statement instanceof Select select)) { throw new IllegalArgumentException(只支持 SELECT 语句); } return new SqlMetaExtractor().analyze(select); } private SqlMetaExtractor analyze(Select select) { select.getSelectBody().accept(selectVisitor); return this; } private final SelectVisitor selectVisitor new SelectVisitorAdapter() { Override public void visit(PlainSelect plainSelect) { collectFromItem(plainSelect.getFromItem()); if (plainSelect.getJoins() ! null) { for (Join join : plainSelect.getJoins()) { collectFromItem(join.getRightItem()); } } for (SelectItem? selectItem : plainSelect.getSelectItems()) { if (selectItem instanceof SelectExpressionItem expressionItem expressionItem.getExpression() instanceof Column column) { columns.add(column.getColumnName()); } } if (plainSelect.getWhere() ! null) { plainSelect.getWhere().accept(expressionVisitor); } } }; private final ExpressionVisitor expressionVisitor new ExpressionVisitorAdapter() { Override public void visit(Column column) { columns.add(column.getColumnName()); } }; private void collectFromItem(FromItem fromItem) { if (fromItem instanceof Table table) { tables.add(table.getName()); } else if (fromItem instanceof SubSelect subSelect) { subSelect.getSelectBody().accept(selectVisitor); } else if (fromItem instanceof ParenthesedSelect parenthesedSelect) { parenthesedSelect.getSelectBody().accept(selectVisitor); } } public ListString getTables() { return tables; } public ListString getColumns() { return columns; } public static void main(String[] args) throws Exception { String sql SELECT u.id, u.name, o.order_no FROM users u JOIN orders o ON u.id o.user_id WHERE u.age 18 AND o.status 1; SqlMetaExtractor meta SqlMetaExtractor.extract(sql); System.out.println(表: meta.getTables()); System.out.println(列: meta.getColumns()); } }输出表: [users, orders] 列: [id, name, order_no, age, status]两个细节提醒。第一如果WHERE条件里还藏着子查询比如WHERE id IN (SELECT user_id FROM blacklist)上面这个例子不会自动把blacklist表捞出来因为ExpressionVisitorAdapter默认不会递归进子查询体。要处理这种情况再重写ExpressionVisitor的visit(SubSelect)方法手动调用subSelect.getSelectBody().accept(selectVisitor)即可。第二任何提取逻辑都不要假设字段非空getJoins()、getWhere()、getOrderByElements()返回null是非常常见的事。3.4 修改AST给WHERE动态追加租户条件的标准姿势解析不只是用来读更常用的是改。下面这段代码是行级权限场景的核心逻辑给查询SQL动态追加一个租户条件。import net.sf.jsqlparser.expression.Expression; import net.sf.jsqlparser.expression.StringValue; import net.sf.jsqlparser.expression.operators.relational.EqualsTo; import net.sf.jsqlparser.expression.operators.relational.AndExpression; import net.sf.jsqlparser.parser.CCJSqlParserUtil; import net.sf.jsqlparser.schema.Column; import net.sf.jsqlparser.statement.Statement; import net.sf.jsqlparser.statement.select.PlainSelect; import net.sf.jsqlparser.statement.select.Select; public String appendTenantCondition(String sql, String tenantColumn, String tenantValue) throws Exception { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Select select select.getSelectBody() instanceof PlainSelect plainSelect) { Expression tenantCondition new EqualsTo( new Column(tenantColumn), new StringValue(tenantValue) ); if (plainSelect.getWhere() null) { plainSelect.setWhere(tenantCondition); } else { plainSelect.setWhere(new AndExpression(plainSelect.getWhere(), tenantCondition)); } return select.toString(); } return sql; }这个方法的巧妙之处在于我完全不用关心原SQL里有没有ORDER BY、有没有LIMIT、有没有GROUP BY因为setWhere()只是替换了AST里条件这一个节点其它节点纹丝不动。要是用字符串拼接你得先判断WHERE关键字的位置还得注意不能把条件插到JOIN ON错误的位置复杂SQL换个写法就全崩。这就是AST修改最大的价值。4. 三个生产级实战场景审计、分页、脱敏4.1 危险SQL拦截无WHERE条件的DELETE/UPDATE直接拒绝我在数据网关里做的最简单也最刚需的一件事是拦截无WHERE条件的写操作。代码很短import net.sf.jsqlparser.statement.delete.Delete; import net.sf.jsqlparser.statement.update.Update; import net.sf.jsqlparser.statement.truncate.Truncate; public static void auditForMutation(String sql) throws Exception { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Delete delete) { if (delete.getWhere() null) { throw new IllegalStateException(拦截DELETE语句缺少WHERE条件); } } else if (statement instanceof Update update) { if (update.getWhere() null) { throw new IllegalStateException(拦截UPDATE语句缺少WHERE条件); } } else if (statement instanceof Truncate) { throw new IllegalStateException(拦截TRUNCATE语句被禁用); } }为什么这种方案比正则可靠因为解析器压根不关心SQL的外在形态。delete from t和DELETE\tFROM\n t甚至中间堆满注释解析出来的AST里Delete.getWhere()一样是null拦截逻辑完全一致。想绕过以后再试试把关键字拆开、把表名用反引号包起来、加多层括号解析器照样能还原出最本质的AST结构。再进一步做SQL注入风险扫描也可以基于这套AST结构。比如检查WHERE条件里是否存在恒真表达式或者扫描StringValue里是否出现可疑的注入负载。注意这里只做结构检查不要试图自己去解读SQL语义否则又变成写第二次正则了。4.2 分页改写自动给查询追加LIMIT与OFFSET中间件开发里最常见的需求是给没有分页的查询自动加上分页。MyBatis-Plus的分页插件内部也是类似逻辑import net.sf.jsqlparser.expression.LongValue; import net.sf.jsqlparser.statement.select.Limit; public String addPage(String sql, long limit, long offset) throws Exception { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Select select select.getSelectBody() instanceof PlainSelect plainSelect) { if (plainSelect.getLimit() ! null) { throw new IllegalArgumentException(原SQL已包含LIMIT); } Limit pageLimit new Limit(); pageLimit.setRowCount(new LongValue(limit)); if (offset 0) { pageLimit.setOffset(new LongValue(offset)); } plainSelect.setLimit(pageLimit); return select.toString(); } return sql; }调用addPage(SELECT * FROM orders WHERE status 1, 20, 0)生成的SQL是SELECT * FROM orders WHERE status 1 LIMIT 20如果offset传20生成的是SELECT * FROM orders WHERE status 1 LIMIT 20 OFFSET 20。这里要说一个兼容性小心得LIMIT n OFFSET m这种写法在MySQL 8.0和PostgreSQL里都支持但老版本MySQL5.6及以前只认LIMIT m, n。如果你们的数据库版本比较老就得在拿到AST之后自己控制toString的渲染方式或者干脆用Oracle的ROWNUM思路去改写。先想清楚目标数据库再动手不然线上会出大问题。另外如果原SQL已经有LIMIT我的建议是不要静默覆盖。分页中间件应该直接抛错或走另一个分支让上层决定是合并还是拒绝。很多线上故障都是我明明没让分页器改这条SQL它却偷偷把LIMIT改了导致的。4.3 列级脱敏与行级权限AST替换的另一类妙用最后一个场景是脱敏。比如用户表里有手机号字段普通接口不允许明文返回但后台报表又需要看到一定规则下的打码结果。最优雅的做法是在SQL层直接改写查询列public String maskColumn(String sql, String columnName, String maskExpression) throws Exception { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Select select select.getSelectBody() instanceof PlainSelect plainSelect) { for (SelectItem? selectItem : plainSelect.getSelectItems()) { if (selectItem instanceof SelectExpressionItem expressionItem expressionItem.getExpression() instanceof Column column column.getColumnName().equalsIgnoreCase(columnName)) { expressionItem.setExpression(CCJSqlParserUtil.parseExpression(maskExpression)); } } return select.toString(); } return sql; }调用方式String maskedSql maskColumn( SELECT id, name, phone FROM users WHERE id 1, phone, concat(left(phone, 3), ****, right(phone, 4)) );原SQL会变成SELECT id, name, concat(left(phone, 3), ****, right(phone, 4)) FROM users WHERE id 1。这里AST替换和字符串替换最大的区别是它只作用于真正代表被查询列的节点。如果某条记录里用户昵称恰好是phone这两个字母或者某条SQL的WHERE条件里出现status phone这样的字符串字面量字符串替换会全部误伤AST替换则完全免疫。行级权限就是在前面3.4节的appendTenantCondition基础上做的动态条件拼接。SaaS系统里最常见的多租户隔离本质就是给每个请求的SQL自动加上tenant_id xxx。这套逻辑我实际给好几个项目打过底稳定得很关键就是别在业务代码里手写SQL拼接统一走这个解析改写层。5. 实测复盘版本差异、失败降级与性能调优5.1 从3.x迁到4.x必须注意的API变化网上大量教程写的还是3.x时代的API直接抄会踩坑。我迁移时遇到的主要变化有这么几处变化点3.x写法4.x推荐写法获取查询体select.getPlainSelect()select.getSelectBody()括号子查询类名ParenthesisSelectParenthesedSelect查询列类型SelectItemSelectItemT泛型分组对象表达式列表GroupByElement对象4.2之后StatementVisitor新增了一些方法如果你实现的是接口而不是用Adapter升级后会发现编译报错这也是我强烈建议用Adapter的原因。迁移建议就一条先升级依赖然后把所有自定义Visitor类跑一遍编译期报错照着报错逐个改。别想着运行时慢慢发现Visitor接口的方法签名变化在编译期就能暴露大部分问题这是成本最低的迁移路径。5.2 解析失败的那些复杂SQL降级策略比解析本身更重要再强的解析器也有解析不了的时候。我遇到的失败案例大致分三类MyBatis动态SQL没有完全渲染的模板比如SQL里残留${param}或#{param}占位符这类严格来说不是合法SQL需要先渲染再解析MySQL的版本化注释/*! ... */、Oracle的CONNECT BY层次查询等方言特性在部分版本里解析器支持不完整极端复杂的嵌套视图、超长CTE链偶尔也会触发内部错误。针对这些情况我的处理原则是失败不可怕可怕的是因为失败把业务搞挂。所有调用入口统一做三件事捕获JSQLParserException以及可能的运行时异常记WARN日志并保存原始SQL返回原始SQL作为降级结果让请求继续走不在解析层拦断业务用计数器统计解析失败率超过阈值就告警把失败SQL存下来定期人工review。这个降级策略我实际用下来的感受是解析覆盖率能做到99%以上剩下的1%走原样放行业务感知不到任何变化。但前提是日志要打清楚否则排查问题时会非常痛苦。5.3 性能实测与缓存设计一个高质量的SqlParserService封装关于性能我给出一个量级参考单表单条件SELECT从解析到toString一次完整往返大概几十到一两百微秒带多个JOIN、子查询、CTE的复杂SQL可能到1~3毫秒。单次请求完全无感但如果放在每天跑几百万次的批处理链路里这个开销就不能忽视了。优化方案通常分两层。第一层是复用对同一段SQL文本把解析结果放进LRU缓存key就是SQL原文value可以是Statement对象也可以是你已经算完的提取结果。Caffeine写个几十行就能搞定缓存命中后一次字符串比较的成本几乎可以忽略。第二层是控制范围不是每条SQL都需要完整遍历AST提前用简单的关键字判断跳过明显不需要处理的语句能省下很多无谓的解析开销。这里有个容易被忽视的线程安全问题CCJSqlParserUtil.parse()每次都会新建解析器多线程安全但如果你为了性能直接复用CCJSqlParser实例它不是线程安全的并发场景会出奇怪问题。我在项目里就是把逻辑封装成一个SqlParserService统一管缓存、管解析、管异常降级业务侧只用传SQL进去、拿结果出来内部细节全部屏蔽掉。最后再补充一个我自己的小习惯statement.toString()输出的SQL不保证和输入逐字节一致解析器会把大小写、空格、换行规范化。所以如果你要做SQL签名、哈希比对一定要基于原始SQL做不要拿toString之后的结果去比否则同一个逻辑的SQL前后两次的哈希值会对不上。这个坑我栽过一次希望你们别再栽。
