JSqlParser实战：SQL解析、表名提取与安全改写指南

做后端开发经常要和SQL打交道尤其是负责数据分析平台、SQL审核工具或者数据中台这类系统时需求往往会从“把SQL跑通”变成“把SQL拆开看”。如果你也遇到过这种情况拿到一段SQL想知道它查了哪些表、更新了哪些字段、WHERE条件里过滤了什么、能不能动态加一个分页限制这时候JSqlParser就是那个能把业务从“正则地狱”里捞出来的库。JSqlParserJava SQL Parser是一个纯Java实现的SQL语法解析器它能把一条SQL字符串解析成一棵语法树通过这棵树你可以拿到SQL里几乎所有的结构化信息。这篇文章我把自己在项目里踩过的坑、总结出来的用法一次性写完内容包括JSqlParser的依赖引入、核心API使用、表名提取、SQL改写、注入检测等高频场景也包括一些官方文档里不会写的经验。适合正在做SQL分析工具、数据血缘、慢SQL优化或者准备Java面试时想深入理解SQL解析原理的开发者。1. 为什么不用正则去解析SQL很多人在第一次接触到“解析SQL”这个需求时第一反应是写正则。比如要提取SQL里的表名就匹配from\s(\w)这个模式。这种做法在小场景下看起来能跑但只要SQL稍微复杂一点就会崩。举个例子一条SQL里出现了子查询嵌套、别名、JOIN、括号包裹的条件正则一匹配就容易把子查询里的表名当成主查询的表名或者是把别名当成了真实表名。更麻烦的是SQL标准本身非常灵活字段里可以有函数、表达式、CASE WHEN、字符串常量这些内容里也可能出现“from”或者表名关键字正则根本区分不了哪些是语法结构哪些是数据内容。JSqlParser解决这个问题的核心思路是做真正的语法解析而不是文本匹配。它基于JavaCC生成了解析器会把输入的SQL字符串按照SQL语法规则拆解成语法树。语法树上的每一个节点都有明确的类型Table表示表Column表示字段EqualsTo表示等值比较LongValue表示数值字面量。程序只需要遍历这棵树就能准确地拿到结构化信息。这个“结构化”的价值非常大。拿表名提取来说正则方案需要维护一套复杂的模式匹配逻辑一遇到边界情况就出bug而基于JSqlParser的方案只需要递归检查每个节点是不是Table类型无论SQL里嵌套了多少层子查询、JOIN、WITH临时表都不会漏掉也不会误判。一句话总结SQL解析本质上是个语法分析问题正确做法是交给解析器处理而不是埋头写正则。2. 环境准备与最简解析流程2.1 Maven依赖引入JSqlParser在Maven Central上有正式版本直接在pom.xml里加依赖即可。我项目里长期使用的是4.x主线版本API稳定、资料也多适合生产环境dependency groupIdcom.github.jsqlparser/groupId artifactIdjsqlparser/artifactId version4.9/version /dependency如果你是2024年之后新建的项目也可以尝试5.x版本。不过5.x之后做了模块化拆分类名和部分接口有调整老代码迁移时需要改一些地方这个我在后面“踩坑”部分会详细说。初次接触的话建议直接上手4.9文档丰富、社区问答多遇到问题好找解决方案。2.2 解析一条SQL并打印核心信息依赖引入后最快上手的方式就是写一个能跑的示例。我放一个最基础的用法解析一条SELECT语句然后输出它的语句类型、查询的表、WHERE条件import net.sf.jsqlparser.JSQLParserException; import net.sf.jsqlparser.parser.CCJSqlParserUtil; import net.sf.jsqlparser.statement.Statement; import net.sf.jsqlparser.statement.select.PlainSelect; import net.sf.jsqlparser.statement.select.Select; import net.sf.jsqlparser.statement.select.SelectBody; import net.sf.jsqlparser.statement.select.Table; public class JsqlParserDemo { public static void main(String[] args) throws JSQLParserException { String sql SELECT u.id, u.name, o.order_no FROM t_user u JOIN t_order o ON u.id o.user_id WHERE u.status 1 AND o.amount 100 ORDER BY o.create_time DESC; Statement statement CCJSqlParserUtil.parse(sql); System.out.println(解析结果类型: statement.getClass().getSimpleName()); if (statement instanceof Select) { Select select (Select) statement; SelectBody selectBody select.getSelectBody(); if (selectBody instanceof PlainSelect) { PlainSelect plainSelect (PlainSelect) selectBody; // 提取表 System.out.println(查询表: plainSelect.getFromItem()); // 提取where条件 System.out.println(WHERE条件: plainSelect.getWhere()); } } } }运行这个程序输出效果大致是解析结果类型: Select 查询表: t_user AS u WHERE条件: (u.status 1) AND (o.amount 100)注意看getFromItem()返回的是t_user AS u这说明解析器把表名和别名都拿出来了不需要自己再去截取字符串拆别名。getWhere()返回的是带括号的条件表达式这个表达式本身也是一棵树可以继续往下遍历。2.3 Statement接口与常见类型JSqlParser把所有SQL统一抽象成一个Statement接口。判断一条SQL到底是不是SELECT只需要用instanceof判断具体类型即可。常用的类型有这几个语句类型对应类说明查询Select所有SELECT语句内部还有PlainSelect、SetOperationList、WithItem等子类更新UpdateUPDATE语句插入InsertINSERT语句删除DeleteDELETE语句建表CreateTableCREATE TABLE语句事务Commit / Rollback事务控制语句管理TruncateTRUNCATE语句在实际开发里我一般会先判断类型再进入对应的分支处理。比如做一个SQL审核工具DELETE和TRUNCATE就要走高危告警做一个数据血缘系统只关心SELECT里的读表关系做一个写操作分析平台重点看INSERT、UPDATE、DELETE涉及的表和字段。3. SQL语法树的核心结构与遍历方式3.1 把SQL想象成一棵嵌套的树理解JSqlParser关键是改变对SQL的认知方式不要把它看成一行字符串而是看成一棵树。拿最普通的SELECT语句举例它的树结构大致是Select └── SelectBodyPlainSelect ├── SelectItem列表查询字段 ├── FromItem主表/子查询/JOIN对象 ├── JoinsJOIN列表 ├── Where条件表达式树 ├── GroupBy分组表达式 ├── Having分组过滤条件 └── OrderBy排序条件每个节点都可以继续往下拆。Where里可能是AndExpression、EqualsTo、GreaterThan这种比较节点SelectItem里可能是Column、Function、CaseExpressionFromItem可能是Table、SubSelect、LateralSubSelect甚至可能是括号包裹的多个SELECT集合操作UNION。这个树型结构带来的直接好处是你可以在任意层级做“定点分析”。比如只想知道WHERE条件里用了哪些字段就遍历Where表达式树只想知道SELECT后面查询了哪些字段就遍历SelectItem列表。这种精细度是正则方案完全达不到的。3.2 PlainSelect最核心的访问入口在所有SQL类型里Select又细分为很多子类型。而实际项目中90%以上的查询都是最普通的SELECT ... FROM ... WHERE ...结构这种结构对应PlainSelect类。从Select对象拿到PlainSelect的标准姿势是if (statement instanceof Select) { Select select (Select) statement; SelectBody body select.getSelectBody(); if (body instanceof PlainSelect) { PlainSelect ps (PlainSelect) body; // ps.getSelectItems(); 查询字段 // ps.getFromItem(); 主表 // ps.getJoins(); JOIN列表 // ps.getWhere(); 条件 // ps.getGroupBy(); 分组 // ps.getHaving(); having // ps.getOrderByElements(); 排序 // ps.getLimit(); 分页 // ps.getForUpdate(); 是否for update } }为什么要区分SelectBody因为SQL里有UNION、INTERSECT、EXCEPT这类集合操作。一条SELECT * FROM A UNION SELECT * FROM B的SelectBody不是PlainSelect而是SetOperationList它里面会包含两个PlainSelect。如果代码里不判断类型直接强转PlainSelect就会抛异常。这是我在实际项目中遇到过很典型的坑。3.3 FromItem的多样性表、子查询、JOIN嵌套getFromItem()的返回类型是FromItem这个接口名看起来人畜无害实际上它的实现类有Table、SubSelect、LateralSubSelect、ParenthesisFromItem等。也就是说FROM后面不一定是表也可能是子查询。在一次真正的表名提取里必须同时处理这几种情况如果FromItem是Table直接取表名。如果FromItem是SubSelect递归进去继续提取内部SQL的表。处理getJoins()列表里的每个JOIN对象JOIN的右边可能是表也可能是子查询。我自己写的递归提取表名方法核心逻辑是先处理主表再遍历JOIN列表最后递归处理子查询三个步骤缺一不可。这段代码在后面“抽取SQL中的所有表名”里会完整给出。3.4 访问者模式遍历表达式的正确姿势WHERE条件里的表达式树建议用访问者模式Visitor去遍历而不是手动写一堆instanceof判断。JSqlParser原生支持ExpressionVisitor接口通过实现这个接口可以让解析器自动把表达式树里的每个节点“分发”到对应的处理方法里。public class TableNameExtractor implements ExpressionVisitor { Override public void visit(Column column) { System.out.println(发现字段: column.getColumnName()); } Override public void visit(EqualsTo expr) { expr.getLeftExpression().accept(this); expr.getRightExpression().accept(this); } // 其他方法省略记得左右表达式都要遍历 }这个模式的精髓在于你实现了visit(Column)之后无论表达式嵌套多深括号套括号、函数套函数、CASE WHEN套子查询只要每个容器节点的方法里都调用了accept(this)字段提取就不会漏。不过要提醒一下ExpressionVisitor接口的方法非常多有几十个每个版本还不完全一样直接实现会写一堆空方法。我一般用一个匿名内部类配合instanceof判断来做代码更少实际效果是一样的。4. 高频实操场景与核心实现4.1 抽取SQL中的所有表名表名提取是JSqlParser最常见的使用场景数据血缘、SQL审核、敏感表监控都会用到。核心思路是递归主表、JOIN表、子查询里的表都要提取。这里给一个可以直接用的完整方法import net.sf.jsqlparser.JSQLParserException; import net.sf.jsqlparser.expression.Expression; 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 TableExtractor { public static ListString extractTables(String sql) throws JSQLParserException { ListString tables new ArrayList(); Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Select) { Select select (Select) statement; extractFromSelectBody(select.getSelectBody(), tables); } return tables; } private static void extractFromSelectBody(SelectBody selectBody, ListString tables) { if (selectBody instanceof PlainSelect) { PlainSelect plainSelect (PlainSelect) selectBody; extractFromItem(plainSelect.getFromItem(), tables); if (plainSelect.getJoins() ! null) { for (Join join : plainSelect.getJoins()) { extractFromItem(join.getRightItem(), tables); } } } else if (selectBody instanceof SetOperationList) { SetOperationList setOperationList (SetOperationList) selectBody; for (SelectBody body : setOperationList.getSelects()) { extractFromSelectBody(body, tables); } } } private static void extractFromItem(FromItem fromItem, ListString tables) { if (fromItem instanceof Table) { Table table (Table) fromItem; tables.add(table.getFullyQualifiedName()); } else if (fromItem instanceof SubSelect) { SubSelect subSelect (SubSelect) fromItem; extractFromSelectBody(subSelect.getSelectBody(), tables); } else if (fromItem instanceof ParenthesisFromItem) { ParenthesisFromItem parenthesisFromItem (ParenthesisFromItem) fromItem; extractFromItem(parenthesisFromItem.getFromItem(), tables); } // 如果是LateralSubSelect等特殊类型按自己的业务决定要不要继续递归 } }这段代码处理了三种核心情况普通表、子查询、括号包裹的FROM项。JOIN右表如果也是子查询同样会走extractFromItem递归下去。我在数据血缘项目里就是基于这段代码扩展的。实际使用时注意一个细节Table.getFullyQualifiedName()返回的是带schema前缀的表名比如db.t_user如果你只要原始表名用getName()即可。另外同一个表在JOIN里可能出现多次是否需要去重看业务需求。4.2 SQL注入特征检测从语法层面识别风险SQLSQL注入检测是安全类产品的常见需求。网上很多资料教的都是正则匹配select.*from、union、单引号这类特征误报率极高。JSqlParser方案的优势在于可以基于语法树做更精准的判断。一个基础的风险SQL识别逻辑包含这些维度语句类型是否是DROP、TRUNCATE、ALTER等高风险操作WHERE条件里是否有恒真表达式干扰比如11这种弱特征原始SQL里是否含注释符因为许多注入绕过是塞注释符干扰解析是否使用了堆叠查询多语句用JSqlParser做语句类型判断非常方便import net.sf.jsqlparser.statement.drop.Drop; import net.sf.jsqlparser.statement.truncate.Truncate; public static boolean isHighRisk(String sql) throws JSQLParserException { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Drop) { return true; } if (statement instanceof Truncate) { return true; } return false; }不过这里必须提醒一句JSqlParser擅长的是语法解析注释符和字符串里的内容解析之后会被丢弃或隐藏所以如果要做严格的注入检测不能只靠解析结果需要同时结合原始SQL字符串做文本层面的辅助检查。我在实际项目中的做法是双轨并行先用解析器做结构判断再用特征正则做文本辅助标记两个维度结合降低漏报和误报。4.3 动态分页改写给原生SQL套上分页壳慢SQL治理平台、数据导出工具都会遇到一个需求用户输入一段完整查询SQL系统要自动给这段SQL加上分页限制。比如原来是SELECT * FROM t_order现在要改成SELECT * FROM t_order LIMIT 100, 20。JSqlParser做这件事比字符串拼接靠谱得多因为能直接操作语法树节点import net.sf.jsqlparser.expression.LongValue; import net.sf.jsqlparser.statement.select.PlainSelect; import net.sf.jsqlparser.statement.select.Select; import net.sf.jsqlparser.statement.select.Limit; public static String appendPagination(String sql, long offset, long rowCount) throws JSQLParserException { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Select) { Select select (Select) statement; SelectBody selectBody select.getSelectBody(); if (selectBody instanceof PlainSelect) { PlainSelect plainSelect (PlainSelect) selectBody; Limit limit new Limit(); limit.setOffset(new LongValue(offset)); limit.setRowCount(new LongValue(rowCount)); plainSelect.setLimit(limit); return select.toString(); } } return null; }调用方式String sql SELECT id, name, amount FROM t_order WHERE status 1; System.out.println(appendPagination(sql, 100, 20));输出结果SELECT id, name, amount FROM t_order WHERE status 1 LIMIT 100, 20这个方案的妙处在于SQL字符串里本身如果已经有LIMIT子句setLimit会覆盖原有的如果是UNION这类集合操作需要额外处理SetOperationList但思路完全一致。反过来也可以利用这个能力做“去分页”传入一个带LIMIT的SQL把getLimit()置空就得到了全量查询语句。这在写数据导出功能时非常实用。4.4 查询字段提取与列血缘分析做数据血缘系统时除了表名还需要知道一条SQL里查询了哪些字段、这些字段和表的对应关系。这个需求用JSqlParser遍历SelectItem就能实现。SelectItem有两种普通字段SelectExpressionItem和AllColumnsSELECT *的情况。普通字段的提取逻辑如下import net.sf.jsqlparser.statement.select.SelectExpressionItem; import net.sf.jsqlparser.statement.select.SelectItem; import net.sf.jsqlparser.schema.Column; public static void printSelectColumns(String sql) throws JSQLParserException { Statement statement CCJSqlParserUtil.parse(sql); Select select (Select) statement; SelectBody selectBody select.getSelectBody(); if (selectBody instanceof PlainSelect) { PlainSelect ps (PlainSelect) selectBody; for (SelectItem item : ps.getSelectItems()) { if (item instanceof SelectExpressionItem) { SelectExpressionItem sei (SelectExpressionItem) item; if (sei.getExpression() instanceof Column) { Column column (Column) sei.getExpression(); System.out.println(字段: column.getColumnName() , 所属表: column.getTable().getName()); } } } } }测试一下输入: SELECT u.id, u.name, o.amount FROM t_user u JOIN t_order o ON u.id o.user_id 输出: 字段: id, 所属表: u 字段: name, 所属表: u 字段: amount, 所属表: o字段血缘分析比表血缘复杂的地方在于字段可能来自函数计算COUNT(*)、CASE表达式、子查询这时候单纯取Column还不够需要用Visitor递归表达式树。但基础的“哪个表查了哪些字段”这个层级上面的代码已经能覆盖。4.5 给UPDATE/DELETE语句加安全过滤条件还有一个我一直在用的场景给UPDATE和DELETE语句自动追加安全条件。很多后台管理系统的批量操作需要限制影响范围防止全表更新或全表删除。比如运营人员执行UPDATE t_user SET status 0系统要强制改写为UPDATE t_user SET status 0 WHERE tenant_id 100。JSqlParser处理UPDATE时可以拿到Update对象用setWhere()追加条件import net.sf.jsqlparser.statement.update.Update; import net.sf.jsqlparser.expression.operators.relational.EqualsTo; import net.sf.jsqlparser.expression.LongValue; import net.sf.jsqlparser.schema.Column; public static String safeUpdate(String sql, long tenantId) throws JSQLParserException { Statement statement CCJSqlParserUtil.parse(sql); if (statement instanceof Update) { Update update (Update) statement; if (update.getWhere() null) { EqualsTo eq new EqualsTo(); eq.setLeftExpression(new Column(tenant_id)); eq.setRightExpression(new LongValue(tenantId)); update.setWhere(eq); } else { // 如果已有where条件要拼接一个AND } return update.toString(); } return null; }注意如果原SQL已有WHERE条件直接setWhere会覆盖原条件正确做法是把原条件当左子树新条件当右子树用AndExpression拼接。这个属于比较细节的操作但写错会导致“安全条件失效”比不处理更危险。5. 常见问题与排查技巧实录5.1 版本差异导致API不兼容我踩过最深的坑就是版本升级。JSqlParser从4.x升级到5.x之后ExpressionVisitor接口的方法签名出现了调整以前写的Visitor实现类直接编译报错。另外5.x版本做了模块拆分包路径也有变化。给新项目选版本时我给一个建议如果只是做基础解析、表名提取、SQL改写直接锁4.9版本简单、稳、资料多如果有特殊语法注册需求或者想用最新能力再考虑5.x但要做好适配工作。项目里务必将版本号写死到pom.xml不要用LATEST这种写法否则哪天依赖自动升级了代码就会在不知不觉中编译失败。5.2 SQL方言支持不完全JSqlParser默认支持的是标准SQL语法对个别数据库方言支持不全或者支持程度有限。我实际遇到过的典型案例Oracle的CONNECT BY PRIOR层次查询SQL Server的TOP n配合ORDER BY子查询写法MySQL的ON DUPLICATE KEY UPDATE新版有所支持但老版本解析容易出错各种MERGE INTO写法遇到解析异常JSQLParserException时我的排查套路是先看具体报错位置确认是哪个SQL片段不支持然后针对这个片段做预处理。比如早期版本不支持某个语法我就用正则把那段替换成等价的标准写法再交给解析器处理。这算是一个“正则辅助解析器”的兜底方案不算优雅但能解决实际问题。5.3 分号处理一次解析一条语句CCJSqlParserUtil.parse()一次只解析一条SQL语句。如果你传给它SELECT 1; SELECT 2;会直接抛解析异常。处理多语句批量SQL时我建议先按分号拆分再逐条解析。后台管理类工具经常会面临一个复杂SQL包多分号且字符串带分号的情况纯Split不可靠最好是先做词法级别的清洗遍历字符串识别出单引号字符串区间和注释区间在它们之外再按分号切分。5.4 会被忽略的注释和HintJSqlParser解析时会跳过SQL里的注释--、/* */这在大部分场景下没问题。但如果你做SQL审计需要保留完整SQL时要注意解析后再转成字符串时注释已经不见了。另外MySQL的Hint注释例如/* INDEX(t_user idx_name) */解析行为依赖版本有些版本会把它直接丢掉有些版本会塞进前缀对象里。处理方式的差别会导致SQL改写后Hint丢失影响执行计划这是跑生产任务前必须检查的点。5.5 超大SQL解析耗时与内存我在做SQL平台时有一批复杂的批量INSERT和超长存储过程文本一条SQL的文本能到几MB。JSqlParser对这种超大输入的解析会明显变慢也会占用较多内存。排查建议先用try-catch捕获JSQLParserException超时或异常时返回原始SQL兜底执行不要让解析器故障阻塞生产链路。性能敏感的接入场景可以给解析操作加一个超时控制或者干脆限制可解析SQL的最大长度超过长度走旁路逻辑。6. 实战心得补充最后说一点我个人的感受。JSqlParser不是万能的它没法做到100%兼容所有数据库方言但这不妨碍它成为我工具箱里一个非常可靠的基础组件。用好这个小库的关键是理解它的核心抽象一切SQL都是树一切分析都是遍历。只要你掌握了Statement、SelectBody、PlainSelect、Expression这几层核心类型很多复杂需求都能拆成“遍历 判断 改写”三步走。我在实际项目里的做法是围绕JSqlParser封装一个统一的SQL解析服务对外提供extractTables、getDetailColumns、addLimit、safeRewrite这些业务方法内部统一处理异常和方言兼容。这样一来上层调用方完全不感知解析细节后续如果从4.x升级到5.x只需要改一个实现类就能完成切换。还有一个小技巧值得分享当你不确定某个语法结构在语法树里的位置时最快的排查方法不是查文档而是写一段小代码用System.out.println把解析后的对象整体打印出来。JSqlParser的toString()会把语法树还原成SQL字符串你可以先解析一个目标SQL再主动setWhere(null)或者setLimit(null)看输出的SQL变化就能快速理解每个setter方法对应的是哪个节点。这个方法我用了很多年比读源码手册效率高得多。