Java工程中JSqlParser的SQL解析与改写实践-代码聚汇网

聊到 JSqlParser，先说个场景。你负责的后台管理系统上线了一段时间，突然产品提了个需求：所有查询都要按当前登录人的数据权限自动过滤，不能像以前那样靠前端传条件；又或者，某些敏感字段要在返回前脱敏，但SQL是写在Mapper里的一百多条，总不能一条条改。这时候你自然想到“能不能在SQL执行前改一把”。手动字符串拼接会出事，正则匹配复杂SQL根本扛不住，于是你开始找能够把SQL解析成语法树再重写的工具。JSqlParser 正是干这个的：它把SQL解析成Java对象模型，你改对象再变回SQL字符串。这篇就围绕 JSqlParser 在Java工程里的实际用法，从依赖引入到复杂SQL改写踩坑，给出我在项目中验证过的一套完整方案。

JSqlParser 适用的读者很具体：用Java做数据中间件、分库分表组件、数据权限平台、审计系统、SQL防火墙、慢查询分析工具的开发者，以及被“SQL改写”需求砸中的普通业务开发。它不能帮你写SQL，也不能优化慢SQL，但它能解决“批量、安全、结构化地修改SQL”这件事。

1. 真正需要解析SQL的时候，你才会发现正则不够用

很多一开始觉得“不就是字符串替换吗”的人，最后都会回来找解析器。原因不是正则技术不行，而是改写SQL这个需求的复杂度已经超过了字符串操作能承受的上限。

1.1 字符串替换无法处理的三种典型需求

先看第一种：无条件替换表名。比如原来所有SQL都查 orders 表，现在要做分表，想把它替换成 orders_2024。用 sql.replace("orders", "orders_2024") 会遇到什么问题？如果SQL里有一个字段叫 order_status，或有一个别名叫 o，甚至注释里写了“订单查询”，替换后全部错乱。你可能会说“我用正则匹配表名位置”，但SELECT、UPDATE、DELETE、INSERT、JOIN、子查询、with语句里的表名位置规则都不一样，正则写到最后会变成一团乱麻。

再看第二种：往WHERE里追加条件。数据权限场景最常见，例如“只看本部门数据”，需要在SQL的WHERE条件中追加 AND dept_id = 'D001'。字符串拼接操作听着容易，问题在于：原SQL有没有WHERE？是 WHERE 1=1 还是直接 WHERE status = 0？有没有已经拼接了 ORDER BY、LIMIT、GROUP BY？你需要在正确位置插入，可能需要调整括号，这个用正则很难稳定完成。

第三种：改写SELECT字段列表。脱敏场景要把 phone 字段替换成 concat(left(phone,3),'****',right(phone,4))。但SQL里的 phone 可能出现在字段列表，也可能出现在WHERE条件里，还可能出现在子查询里。你只想处理SELECT列表中的那一处，不碰WHERE里的过滤条件，正则怎么区分上下文？很难。

1.2 解析器做的事情本质上是“结构化手术”

JSqlParser 把SQL字符串解析成一棵对象树。SELECT id, phone FROM user WHERE dept_id = 1 解析后，你拿到的是 Select 对象，里面是 PlainSelect，它有 SelectItems（字段列表）、FromItem（来源表）、Where（条件表达式）。要替换表名，就找到 FromItem 里的 Table 对象改掉；要追加条件，就把 Where 这个对象和新的条件对象拼接起来。

这个过程你可以理解为“在AST上做手术”。好处是：你不需要关心原SQL里表名出现在哪个字符串位置，不需要关心有没有空格、换行、注释，不需要关心关键词大小写，因为解析器已经把结构拆好了。你改完这棵树，再调用 toString()，它就自动生成规范SQL。

1.3 为什么不是ANTLR，也不是MyBatis的SQL

Java圈的开发者常问：搞SQL解析为什么不直接用ANTLR？JSqlParser 本身底层也是用JavaCC生成解析器的，你可以把它理解成一个“已经写好的、专门解析SQL的解析器库”。直接上手ANTLR，你需要自己维护grammar文件，处理各种数据库方言差异，成本非常高。而 JSqlParser 已经封装了常用SQL的解析能力，API也面向SQL改写场景设计，属于“拿来就能用”的轮子。

还有人是MyBatis重度用户，觉得MyBatis能拿到SQL。注意：MyBatis拿到的是“经过动态标签渲染、参数绑定之后”的SQL，也有可能拿到的是带 ? 的预编译SQL，这仍然是一段字符串，而不是像 JSqlParser 这样给你对象结构。而且MyBatis并不提供SQL改写和再生成的API，它也不会帮你把改后的SQL再执行，两个工具解决的问题不同。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 跑通最小例子：依赖、parse 与 Statement 类型

聊了这么多场景，先落地跑通一个最小例子。JSqlParser 的学习成本很低，核心就是几个类：CCJSqlParserUtil、Statement、Select、PlainSelect、Expression。

2.1 引入依赖和第一个解析代码

以Maven工程为例，引入：

xml复制<dependency>
    <groupId>com.github.jsqlparser</groupId>
    <artifactId>jsqlparser</artifactId>
    <version>4.5</version>
</dependency>

最新版本可以去GitHub仓库看，我这里用4.5稳定版做演示。然后写第一段：

java复制import net.sf.jsqlparser.JSQLParserException;
import net.sf.jsqlparser.parser.CCJSqlParserUtil;
import net.sf.jsqlparser.statement.Statement;

public class ParseDemo {
    public static void main(String[] args) throws JSQLParserException {
        String sql = "SELECT id, username, phone FROM sys_user WHERE dept_id = 100 AND status = 1";
        Statement statement = CCJSqlParserUtil.parse(sql);
        System.out.println(statement.getClass().getName());
        System.out.println(statement.toString());
    }
}

输出结果：

code复制net.sf.jsqlparser.statement.select.Select
SELECT id, username, phone FROM sys_user WHERE dept_id = 100 AND status = 1

CCJSqlParserUtil 就是总入口，它有几个常用静态方法：

parse(String sql)：解析单条SQL，返回 Statement
parseStatements(String sql)：解析多条SQL，返回 Statements
parseExpression(String expr)：解析单个表达式，比如 a = 1 AND b = 2
parseCondExpression(String expr)：解析条件表达式

你会发现 toString() 生成的SQL和原SQL不完全一样，比如原SQL里多个空格会被规范成单个空格。这个特性后面很多场景用到，但也要注意：如果项目要求SQL格式保持原样，JSqlParser 不保证100%保留原始格式。

2.2 Statement 是一个抽象层，下面藏着五种主要类型

Statement 是所有SQL语句的顶层接口。用 instanceof 判断具体类型：

java复制if (statement instanceof Select) {
    Select select = (Select) statement;
    // 处理查询
} else if (statement instanceof Insert) {
    Insert insert = (Insert) statement;
    // 处理插入
} else if (statement instanceof Update) {
    Update update = (Update) statement;
    // 处理更新
} else if (statement instanceof Delete) {
    Delete delete = (Delete) statement;
    // 处理删除
}

解析出来是什么类型，取决于你的SQL语句。这一层为什么重要？因为数据权限中间件很多时候既要拦截查询，也要拦截更新和删除。例如“只能更新自己部门的数据”，你的SQL是 UPDATE sys_user SET ... WHERE id = ?，你不能只处理 Select，必须走到 Update 的 Where 里追加条件。

Statement 下面的 Select 又有细分：PlainSelect 是普通查询，SetOperationList 是UNION、INTERSECT、EXCEPT这类集合查询，WithItem 是WITH语句。如果你一开始只处理 PlainSelect，遇到一个UNION查询就直接报 ClassCastException 了，这个坑下面专门展开。

2.3 解析失败又不想崩溃，怎么处理异常

CCJSqlParserUtil.parse() 会抛 JSQLParserException，说明SQL语法不符合它支持的语法。但注意，JSqlParser 对很多数据库方言支持有限，比如某些数据库的特定函数、特殊语法，它可能解析不了。所以生产代码里不能天真地让异常冒泡。

我的做法是写一个包装方法：

java复制public static Statement parseQuietly(String sql) {
    try {
        return CCJSqlParserUtil.parse(sql);
    } catch (JSQLParserException e) {
        // 打日志记录原SQL和异常原因，返回 null
        log.warn("SQL parse failed: {}", sql, e);
        return null;
    }
}

解析失败的SQL不要做改写，直接走原SQL执行，保证不会因为解析器的问题导致线上查询失败。这一点非常重要：解析器永远是旁路逻辑，不能因为它影响主流程。

3. 核心模型：语句、表达式和访问者模式，掌握这层才算入门

能解析出 Statement 对象只是第一步。真正干活的时候，你会发现所有复杂的业务逻辑都围绕“怎么找到树里某个节点”和“怎么修改某个节点”展开。这就是 JSqlParser 的 Expression 体系和访问者模式。

3.1 从 Select 到 PlainSelect，再到 FromItem 和 Where

一条 Select 语句内部的结构是这样的：

java复制Select select = (Select) statement;
SelectBody selectBody = select.getSelectBody();
if (selectBody instanceof PlainSelect) {
    PlainSelect plainSelect = (PlainSelect) selectBody;
    // 1. 字段列表
    List<SelectItem<?>> selectItems = plainSelect.getSelectItems();
    // 2. 来源表
    FromItem fromItem = plainSelect.getFromItem();
    // 3. 条件
    Expression where = plainSelect.getWhere();
    // 4. 分组、排序、分页
    List<Expression> groupBy = plainSelect.getGroupBy().getGroupByExpressionList().getExpressions();
    List<OrderByElement> orderBy = plainSelect.getOrderByElements();
    Limit limit = plainSelect.getLimit();
}

这是最常用的几个getter。注意 FromItem 是个接口，实际可能是 Table、SubSelect（子查询）、ParenthesedFromItem（带括号的形式）、LateralSubSelect 等。你要判断具体类型后再处理。

3.2 Expression 是所有条件的父类

Expression 是一个非常庞大的接口，几乎所有你能想到的条件表达式都实现了它。EqualsTo（等值比较）、GreaterThan、AndExpression（与）、OrExpression（或）、InExpression、LikeExpression、ParenthesedExpressionList 等。

比如构造一个新的条件 dept_id = 'D001'：

java复制Column deptCol = new Column("dept_id");
StringValue deptVal = new StringValue("D001");
EqualsTo eq = new EqualsTo(deptCol, deptVal);

这里 StringValue 是 JdbcParameter 之外的常量类型。如果你想要预编译参数形式，可以创建 JdbcParameter：

java复制JdbcParameter param = new JdbcParameter();

这会让生成的SQL变成 dept_id = ?，特别适合拼到预编译SQL里，防止SQL注入风险。

3.3 访问者模式为什么重要

JSqlParser 的表达式树里节点类型非常多，业务代码如果到处 instanceof，写起来会非常啰嗦。官方接口里定义了 ExpressionVisitor 这个访问者：

java复制public class MyExpressionVisitor implements ExpressionVisitor {
    @Override
    public <S> S visit(EqualsTo equalsTo, S context) {
        // 处理等值表达式
        return context;
    }
    // 其他 visit 重载方法...
}

你可以把所有 EqualsTo 里的列名打印出来，或者把所有 InExpression 提取出来。访问者模式的好处是：你只需要关心想处理的节点类型，其他类型走默认空实现即可。

不过在实际项目中，我发现写一个完整的 ExpressionVisitor 类还是有点重，大部分场景只需要“遍历整棵树找某种节点”，这时候可以借助 TablesNamesFinder 这个官方自带的访问者工具类：

java复制TablesNamesFinder tablesNamesFinder = new TablesNamesFinder();
List<String> tableList = tablesNamesFinder.getTableList(statement);
System.out.println(tableList);

它会把SQL里涉及的所有表名提取出来。这在你做SQL审计、表级权限控制时非常有用。

3.4 两个使用率极高的辅助方法

实际业务里，有两个需求出现频率特别高：提取所有表和所有列。TablesNamesFinder 帮你解决了表名提取，列提取需要自己写访问者，我这里给一个简化版参考：

java复制public class ColumnExtractor extends ExpressionVisitorAdapter<Void> {
    private final Set<String> columns = new HashSet<>();
    public Set<String> getColumns() { return columns; }
    
    @Override
    public <S> Void visit(Column column, S context) {
        columns.add(column.getColumnName());
        return null;
    }
}

ExpressionVisitorAdapter 是官方提供的适配器，你只需要重写关心的 visit 方法。从 PlainSelect 的 Where 里调用 where.accept(extractor)，就能把WHERE里的列全部收集到。这对做数据字典映射、字段级权限校验很有帮助。

4. 落地的改写场景：表名替换、数据权限过滤、字段脱敏、分页改造

学会了基础API后，接下来就是实战环节。我按亲手验证过的四个场景展开，每个场景都给出能够直接拷贝的代码模版。

4.1 表名替换，分表多租户的命根子

场景描述：系统里所有业务表 orders，现在因为数据量过大要按月分表，查询时根据时间参数替换成 orders_202401、orders_202402。

实现思路：拿到 PlainSelect 后，遍历所有 FromItem 和 Join 部分，遇到 Table 对象，判断表名后替换。但要注意，SQL里可能存在子查询，子查询内部也可能有表，只处理外层的 FromItem 是不够的。更好的做法是使用 TableVisitor 访问整棵树：

java复制public class TableReplacer implements TableVisitor<Void> {
    private final String oldTable;
    private final String newTable;
    
    public TableReplacer(String oldTable, String newTable) {
        this.oldTable = oldTable;
        this.newTable = newTable;
    }
    
    @Override
    public <S> Void visit(Table table, S context) {
        String name = table.getName();
        if (oldTable.equalsIgnoreCase(name)) {
            table.setName(newTable);
        }
        return null;
    }
    
    @Override
    public <S> Void visit(SubSelect subSelect, S context) {
        // 递归处理子查询里的表
        subSelect.getSelectBody().accept(this);
        return null;
    }
}

调用时：

java复制Select select = (Select) statement;
select.getSelectBody().accept(new TableReplacer("orders", "orders_202401"));

这里有一个现实注意点：如果你在分片中间件上做这件事，SQL可能还会包含 INSERT INTO orders 这样的语句。Insert 对象同样有 Table 字段，所以我的 TableVisitor 还要处理 Insert 及其冲突更新部分。最稳妥的方式是写一个 StatementVisitor，在 visit(Select)、visit(Insert)、visit(Update)、visit(Delete) 里分别调用表替换逻辑。老实说，如果你只需要替换表名，也可以直接遍历Statement，但写 StatementVisitor 更规范，后续扩展其他改写逻辑也方便。

4.2 数据权限过滤：往WHERE里安全追加条件

场景描述：用户只能查看 dept_id 为当前部门的数据，而且不能直接改业务SQL，需要在执行层统一改造。

实现思路：找到 PlainSelect 的 Where，如果是空，就新建一个 EqualsTo；如果不是空，就与原有条件做 AndExpression 合并。

java复制PlainSelect plainSelect = (PlainSelect) select.getSelectBody();
Expression originalWhere = plainSelect.getWhere();

Column deptCol = new Column("dept_id");
StringValue deptVal = new StringValue("D001");
EqualsTo deptEq = new EqualsTo(deptCol, deptVal);

if (originalWhere == null) {
    plainSelect.setWhere(deptEq);
} else {
    AndExpression and = new AndExpression();
    and.setLeftExpression(originalWhere);
    and.setRightExpression(deptEq);
    plainSelect.setWhere(and);
}

这一段看着简单，但里面有一个非常容易踩的坑：运算符优先级。如果原条件里包含 OR，直接拼接 AND 会产生逻辑错误。比如原SQL是 WHERE status = 0 OR status = 2，你要追加 AND dept_id = 'D001'。如果直接拼成 status = 0 OR status = 2 AND dept_id = 'D001'，由于 AND 优先级高于 OR，实际执行会变成 status = 0 OR (status = 2 AND dept_id = 'D001')，但你的意图是 (status = 0 OR status = 2) AND dept_id = 'D001'。这就不对了。

正确做法是始终给原条件加括号，使用 ParenthesedExpressionList 或直接调用 ParenthesedExpressionList（老版本是 Parenthesis）包裹：

java复制ParenthesedExpressionList<?> paren = new ParenthesedExpressionList<>(originalWhere);
AndExpression and = new AndExpression(paren, deptEq);
plainSelect.setWhere(and);

这样生成的SQL就是 (status = 0 OR status = 2) AND dept_id = 'D001'，逻辑就对了。

数据权限改造还涉及一个需要确认的问题：如果原SQL已经有 dept_id 条件怎么办？可能那个条件是业务代码故意传的，也可能用户绕过了数据权限。我的做法是先解析出Where里所有列名，如果检测到已有 dept_id 字段，就不再加了，或者根据策略选择覆盖，避免用户传入其他部门的 dept_id 来绕过权限。这个检测可以用上面写的 ColumnExtractor。

4.3 字段脱敏：只改SELECT列表，不碰WHERE

场景描述：用户查询列表时，手机号要求部分脱敏，比如 138****1234。

实现思路：遍历 PlainSelect.getSelectItems()，找到对应列的 SelectExpressionItem，把它原来的表达式替换成函数调用表达式。

看代码：

java复制List<SelectItem<?>> selectItems = plainSelect.getSelectItems();
for (int i = 0; i < selectItems.size(); i++) {
    SelectItem<?> item = selectItems.get(i);
    if (item instanceof SelectExpressionItem) {
        SelectExpressionItem sei = (SelectExpressionItem) item;
        Expression expr = sei.getExpression();
        if (expr instanceof Column) {
            Column column = (Column) expr;
            if ("phone".equalsIgnoreCase(column.getColumnName())) {
                // 构造 concat(left(phone,3),'****',right(phone,4))
                Function function = new Function();
                function.setName("concat");
                ExpressionList<?> params = ExpressionList.of(
                    new Function("left", ExpressionList.of(column, new LongValue(3))),
                    new StringValue("****"),
                    new Function("right", ExpressionList.of(column, new LongValue(4)))
                );
                function.setParameters(params);
                sei.setExpression(function);
            }
        }
    }
}

Function 是这个库中非常常用的类，我们前面看到的 left(phone,3) 本质上就是一个 Function。ExpressionList.of(...) 用于构造参数列表，注意不同版本API稍有差异，4.x版本可用。

这个场景有一个细节：如果SQL是 SELECT *，没有显式列出 phone 字段，你就无法脱敏。更麻烦的是 SELECT u.* FROM sys_user u 这种，解析器并不知道 u.* 展开了之后包含哪些列。这种情况要脱敏，只能在拿到SQL结果后再做内存脱敏，或者提前做字段映射。我会在第一版实现里把 SelectExpressionItem 中没有展开的 * 记录下来，在文档里提示产品“这部分暂时脱敏不了”。

4.4 分页改造：给原来没有LIMIT的SQL加LIMIT

场景描述：老系统有大量查询SQL没有分页，前端要求统一分页，但不想一个一个改Mapper。

实现思路：给 PlainSelect 设置 Limit 对象：

java复制Limit limit = new Limit();
limit.setRowCount(new LongValue(pageSize));
limit.setOffset(new LongValue((page - 1) * pageSize));
plainSelect.setLimit(limit);

生成的SQL变成：

sql复制SELECT ... FROM ... LIMIT 20 OFFSET 40

如果是Oracle这种不支持 LIMIT 的数据库，你要生成的是 OFFSET 40 ROWS FETCH NEXT 20 ROWS ONLY 这种语法，JSqlParser 的Oracle方言支持有限，这就是另外一个话题了。我用这个功能做的是MySQL和PostgreSQL的分页，都比较顺手。要注意：如果原SQL已经有 LIMIT，你直接替换掉 Limit 对象即可，别叠加处理导致两条 LIMIT。

还有一种情况是原SQL里带 FOR UPDATE（行锁），分页加 LIMIT 后，MySQL会报语法错误。因为 FOR UPDATE 和 LIMIT 的顺序有要求。我没找到 PlainSelect 里直接处理这个顺序的封装，遇到时会用字符串replace把 FOR UPDATE 挪到末尾，虽然不是完美方案，但能在绝大多数场景下工作。

5. 最容易翻车的SQL形态：子查询、连接、联合与复杂表达式

前面四个场景看着都顺，但真正放到生产环境，你会遇到各种各样的SQL，很多会让你怀疑是不是 JSqlParser 解析错了。这里梳理几类最容易翻车的形态和应对办法。

5.1 子查询嵌套，比想象中深得多

WHERE id IN (SELECT user_id FROM user_department WHERE dept_id = 5) 这种是典型的子查询。JSqlParser 的表达式树里，InExpression 的右侧是一个 SubSelect。你用 TablesNamesFinder 提取表名时会包含子查询里的表，但如果你想统一替换某个表名，只处理外层 FromItem 就漏了。

应对办法：务必用 TableVisitor 或 StatementVisitor 递归处理整棵树，不要只处理 FromItem 一个节点。我在第一次做多租户替换表名时，就漏掉了子查询里的表，导致租户隔离数据泄露，排查了很久。

排查技巧：改写完SQL后，打印 statement.toString()，肉眼确认子查询里的表有没有被替换，再用小数据集做验证。对于这种安全性敏感的功能，建议写单元测试，把样本SQL跑一遍，确认输出符合预期。

5.2 JOIN类型多，连接条件也要处理

JOIN 在 PlainSelect 中是 List<Join>，每个 Join 里有 FromItem 和 OnExpression。表名替换不光是 PlainSelect.getFromItem()，还要遍历 plainSelect.getJoins()。比如：

java复制SELECT * FROM orders o JOIN users u ON o.user_id = u.id

orders 在 FromItem，users 在 Join 里。如果只处理 FromItem，users 表就不会被改。你的 TableVisitor 访问 PlainSelect 时，Join 里的 FromItem 也会作为访问目标，前提是你正确调用了 plainSelect.accept(visitor)。

另外，JOIN 条件里的 ON 表达式也是一个 Expression，如果你要做列名脱敏，ON 里的 user_id 也是 Column，想过滤条件里的列名，ColumnExtractor 访问整棵 PlainSelect 就能覆盖。

5.3 UNION和WITH：PlainSelect的假设直接失效

前面说过，不是所有 Select 都是 PlainSelect。SELECT * FROM a UNION ALL SELECT * FROM b 解析出来是 SetOperationList，它有 getSelects() 方法返回多个 SelectBody。如果你只处理 PlainSelect，这段SQL会报错。

java复制SelectBody selectBody = select.getSelectBody();
if (selectBody instanceof PlainSelect) {
    PlainSelect plainSelect = (PlainSelect) selectBody;
    // 处理
} else if (selectBody instanceof SetOperationList) {
    SetOperationList setOpList = (SetOperationList) selectBody;
    for (SelectBody inner : setOpList.getSelects()) {
        if (inner instanceof PlainSelect) {
            // 递归处理每个分支
        }
    }
}

WITH cte AS (...) SELECT ... 也类似，WithItem 的 SelectBody 需要递归处理。所以如果你的数据权限组件要覆盖所有查询，写一个支持递归的方法非常有必要：接收 SelectBody，如果是 PlainSelect 就处理，如果是 SetOperationList 就遍历其内部的 SelectBody，如果是 WithItem 就递归它的子查询。

递归处理时特别注意：避免无限递归。子查询的子查询是正常的，但如果你在 SubSelect 访问器里再次调用了同一个访问器，可能会因为循环引用出问题。JSqlParser 的访问者机制通常能处理，但我吃过一次亏，在自定义访问器里对 SelectBody 又调了一次 accept，导致栈溢出。

5.4 括号和运算符优先级：别让解析器帮你背锅

复杂表达式最容易出的问题不是解析失败，而是你“新增一个条件”时改变了原有表达式的语义。前面讲的 OR 场景只是其一，还有 NOT。比如原SQL是 WHERE NOT (status = 0 AND type = 1)，你直接拼接 AND dept_id = 'D001'，生成 NOT (status = 0 AND type = 1) AND dept_id = 'D001'，这个其实没问题。但如果原SQL是 WHERE NOT status = 0，你拼成 NOT status = 0 AND dept_id = 'D001'，也没毛病。

真正麻烦的是 WHERE status = 0 OR type = 1 NOT AND dept_id 这种无意义的写法？其实不会。代码里只要记住：对任何已有的复合条件，合并前先加括号。这是我做中间件最深的一条经验。加括号不会改变SQL语义，还能避免各种优先级意外。

5.5 解析不了的SQL怎么办

无论什么时候，项目里总会有一些SQL解析不了。常见原因：

数据库特有的函数或语法（比如某些 SELECT 带特殊 Hint）
注释格式不规范
字符串里有特殊字符
多语句混在一起，没走 parseStatements

应对策略很简单：解析失败就跳过改写，原SQL执行，同时记录告警日志。一个SQL解析不了不代表系统功能不可用，但你需要尽快知道哪些SQL是解析器不支持的，后续通过升级 JSqlParser 版本、增加预处理逻辑等方式逐步覆盖。我见过有些团队追求“所有SQL都能解析”，这其实没必要，覆盖率做到95%以上已经能解决大部分业务需求了。

6. 用解析器做SQL注入拦截，比正则可靠得多

热搜里频繁出现“SQL注入万能密码绕过”和“慢SQL优化”。JSqlParser 也常在安全网关、SQL审计系统里承担“语义检查”的职责。可能有人觉得SQL注入检测用正则匹配关键字就行，比如判断有没有 ' OR 1=1 --。但攻击者的绕过手段五花八门：大小写、注释、编码、空白字符。正则很难枚举完全。用解析器做检测，本质上是从“字符串特征匹配”升级到“语法结构分析”。

6.1 解析器为什么能识别注入

SQL注入的本质是：一段用户输入被拼进了SQL，改变了SQL原本的结构。最常见的是 ' OR 1=1 -- 这种，它让原来只查询自己的SQL变成了 SELECT * FROM users WHERE username = '' OR 1=1 -- AND password = ''。

如果用 JSqlParser 解析这条SQL，它解析出的结构是：WHERE (username = '') OR (1=1)，后面的 -- AND password = '' 被当作注释忽略掉了。你从语法树上能看到这个WHERE条件里有一个 OrExpression，右侧还是一个 EqualsTo，其中左侧是 LongValue(1)，右侧也是 LongValue(1)。这种“恒真条件”在正常业务SQL里极少出现，可以作为一个告警特征。

但要注意，-- 注释在 JSqlParser 解析时可能报错，也可能正常解析。单靠解析结构判断不是银弹，还要结合参数化查询、白名单机制一起用。

6.2 一个简单的风险检测器示例

我写过一个 SqlRiskDetector，基于 JSqlParser 做两层检查：

第一层：尝试解析SQL。如果解析失败，说明SQL可能不符合规范，标记为可疑。

第二层：解析成功后，遍历表达式树，查找：

值类型与列类型不匹配（比如整型列直接和字符串常量比较）——这通常是注入特征，但也可能是业务写得不严谨，需要结合上下文
存在 1=1、1=2 这类恒真/恒假表达式
存在多个分号（多语句拼接）

大致思路：

java复制public static boolean checkDangerous(String sql) {
    try {
        Statement stmt = CCJSqlParserUtil.parse(sql);
        if (stmt instanceof Select) {
            PlainSelect ps = getPlainSelect((Select) stmt);
            Expression where = ps.getWhere();
            if (where == null) return false;
            DangerVisitor visitor = new DangerVisitor();
            where.accept(visitor);
            return visitor.isDanger();
        }
    } catch (JSQLParserException e) {
        // 解析失败也可能是注入特征
        return true;
    }
    return false;
}

实际生产中这种规则要非常谨慎，不能误伤正常SQL。比如用户搜索表单里可能故意传 1=1 来“查询全部”，这未必是攻击。所以检查结果通常只是打到审计日志或触发二次验证，不会直接阻断。

6.3 更安全的做法是永远不用字符串拼SQL

虽然 JSqlParser 能帮你识别一部分注入，但我还是强调：预防SQL注入的第一选择永远是预编译参数。JSqlParser 里创建 JdbcParameter 就是为这个准备的。如果你的数据权限改写最终生成的是 WHERE dept_id = ?，而不是 WHERE dept_id = 'D001'，那你既做到了权限隔离，又没有引入注入风险，这是一举两得。

我用 JSqlParser 做数据权限改造时，默认都生成 JdbcParameter，把参数值单独收集到一个 List<Object> 里，执行时再绑定。这样改写后的SQL可以安全地进入MyBatis或JDBC预编译流程。

7. 一些过了坑之后才懂的经验

上面是按功能主线讲的，这里再补几条散落在代码之外的经验，都是我实际做项目时踩出来的。

7.1 版本选型不要追新，但也不要太老

JSqlParser 迭代速度不算慢，不同版本API差异明显。比如老版本里 Parenthesis 类在4.x里改成了 ParenthesedExpressionList，还有 ExpressionList.of() 这种静态工厂方法都是后来加的。如果你在网络上抄到一段老代码，直接粘到新版本项目里大概率编译不过。

我的建议：新项目直接用当前稳定版，别用3.x；老项目升级前要看官方Release Note，重点看API变更。同时把核心改写逻辑封装成一个单独模块，和业务代码解耦，这样即使将来升级解析器版本，影响面也可控。

7.2 写测试案例别只写理想SQL

解析SQL这个事，边界情况特别多。我强烈建议你建立一个 sql-samples 文件夹，把你项目里真实出现的SQL样本都放进去，按“可解析/不可解析/改写正确/改写错误”分类维护。每次改代码跑一遍样本集。头几次总会发现新问题：原来 INSERT ... ON DUPLICATE KEY UPDATE 的结构和 INSERT 不同，原来 DELETE 也可以带 JOIN。

维护样本集虽然麻烦，但当你下一次改数据权限逻辑时，它能让你快速回归，避免因为一个SQL形态没覆盖导致线上事故。

7.3 性能不是主要问题，但也不要在大循环里反复解析

JSqlParser 的解析性能谈不上极致，但也不是瓶颈。一张复杂查询SQL的解析耗时大概是毫秒级，对于业务系统来说完全可以接受。唯一需要小心的是：如果你在高频接口里对同一类SQL反复解析，建议加一层本地缓存，以“原始SQL字符串”为key，缓存解析后的 Statement 对象。但要注意，Statement 对象是可变的，缓存后如果被并发修改会出问题，所以最好缓存改写后的SQL字符串，而不是缓存可变对象。

我一般这样做：

内部接口动态生成的SQL参数化程度高，没必要缓存
Mapper里那些固定不变的SQL，首次解析后缓存改写结果

7.4 改写后的SQL要先走测试环境

这句话听起来像废话，但值得反复强调：所有SQL改写逻辑上线前，必须把“改写前SQL”和“改写后SQL”都打出来，人工核对。我在一个月内遇到过两次表名替换把 order 替换成 orders_2024 后，连ORDER BY里的关键字 ORDER 都被错误匹配的情况——虽然那个bug出在我正则匹配逻辑里，但 JSqlParser 的 toString() 也让我明白了：改写和校验是两个必须同时存在的环节。改完不是结束，验证才是。

7.5 把参数类型搞清楚，别让StringValue背锅

构造表达式时要特别注意常量类型。dept_id = 'D001' 和 dept_id = 100 在 JSqlParser 里是两种不同的 Value：前者是 StringValue，后者是 LongValue。如果你把数字类型的列拼成 StringValue，生成的SQL虽然能执行，但在某些数据库里可能无法走索引，影响查询性能。所以条件追加时，最好从元数据或上下文里拿到字段类型，再选择对应的 Value 子类。

还有一个隐蔽点：如果列名本身带点号，比如 u.dept_id，用 new Column("u.dept_id") 没问题；但如果你给 Column 设置了 Table 属性，生成的SQL可能就是 u.dept_id，这时候你再去 getColumnName()，返回的可能是 dept_id 而不是 u.dept_id，遍历时要注意。

8. 结个尾：这个库值得花半天时间掌握

JSqlParser 不是我项目中唯一用到的SQL工具，但它确确实实帮我在数据权限、分表分库、脱敏等需求上省了无数脑细胞。如果你已经看到这里，说明你大概率遇到了需要改写SQL的需求。我的建议是不要犹豫，先写一个最小Demo跑通解析和toString，再把你的真实SQL放进去看看结构，最后才考虑上生产。

如果在集成过程中遇到API版本差异，优先看官方GitHub仓库的示例代码，比搜索引擎里的旧博客靠谱。遇到解析不了的SQL，先确认数据库方言，再考虑加兜底逻辑。不要试图在中间件里解决所有SQL问题，那只会让你陷入无底洞。

最后分享一个我在日常开发中屡试不爽的排查技巧：当你觉得 JSqlParser 生成的结果不对时，直接打印 statement.toString()，观察它与原SQL的差异。很多时候你会发现不是库的问题，而是你对SQL结构的认知不够完整。多试几次，你就慢慢形成对AST的直觉了。

Java工程中JSqlParser的SQL解析与改写实践