如何在JSqlParser中实现未支持SQL特性自动报错机制

JSqlParser作为轻量级的SQL解析框架，广泛应用于SQL审计、分库分表路由等场景，但其内置的解析器对部分特殊SQL语法、小众数据库特性的支持有限。当输入包含未支持特性的SQL时，JSqlParser可能静默跳过解析或者返回不完整的解析结果，给后续业务带来隐患。实现未支持SQL特性自动报错机制，可以在解析阶段就拦截这类问题SQL，降低线上故障风险。

JSqlParser解析基础原理

JSqlParser的核心解析流程是通过CCJSqlParserManager读取SQL字符串，生成对应的抽象语法树（AST），再通过访问者模式遍历AST节点。内置的Statement接口是所有SQL语句的父接口，不同类型的SQL（如Select、Insert）都实现了该接口。未支持的SQL特性通常表现为解析时无法生成对应的AST节点，或者生成的节点缺少必要的属性。

实现自动报错的核心思路

要实现未支持特性自动报错，核心是在解析完成后，对生成的AST进行全量扫描，校验节点类型是否符合预期的支持范围，遇到未定义的节点或者不支持的属性时直接抛出异常。具体可以分为三个步骤：

• 自定义AST访问者，遍历所有解析后的节点
• 维护一个支持特性白名单，明确允许出现的节点类型和属性
• 遍历过程中匹配白名单，不匹配则抛出自定义异常

具体实现步骤

1. 自定义访问者类

继承JSqlParser内置的VoidVisitorAdapter类，重写需要校验的节点访问方法，在方法中判断节点是否属于支持范围。

import net.sf.jsqlparser.parser.CCJSqlParserManager;
import net.sf.jsqlparser.statement.Statement;
import net.sf.jsqlparser.statement.select.Select;
import net.sf.jsqlparser.statement.select.PlainSelect;
import net.sf.jsqlparser.statement.select.SelectItem;
import net.sf.jsqlparser.expression.Expression;
import net.sf.jsqlparser.expression.Function;
import net.sf.jsqlparser.visitor.VoidVisitorAdapter;
import java.io.StringReader;
import java.util.HashSet;
import java.util.Set;

public class UnsupportedSqlChecker {
    // 支持的SQL语句类型白名单
    private static final Set<Class<?>> SUPPORTED_STATEMENT_TYPES = new HashSet<>();
    // 支持的聚合函数白名单
    private static final Set<String> SUPPORTED_AGG_FUNCTIONS = new HashSet<>();

    static {
        // 初始化支持的语句类型，仅支持Select和Insert
        SUPPORTED_STATEMENT_TYPES.add(Select.class);
        // 初始化支持的聚合函数，仅支持count和sum
        SUPPORTED_AGG_FUNCTIONS.add("count");
        SUPPORTED_AGG_FUNCTIONS.add("sum");
    }

    // 自定义访问者，校验Select语句中的特性
    static class SelectFeatureVisitor extends VoidVisitorAdapter<Void> {
        @Override
        public void visit(PlainSelect plainSelect, Void context) {
            // 校验是否支持LIMIT子句，这里假设不支持LIMIT
            if (plainSelect.getLimit() != null) {
                throw new UnsupportedOperationException("当前不支持LIMIT子句");
            }
            // 继续遍历子节点
            super.visit(plainSelect, context);
        }

        @Override
        public void visit(Function function, Void context) {
            String funcName = function.getName().toLowerCase();
            // 校验聚合函数是否在白名单中
            if (!SUPPORTED_AGG_FUNCTIONS.contains(funcName)) {
                throw new UnsupportedOperationException("不支持的聚合函数: " + funcName);
            }
            super.visit(function, context);
        }
    }

    // 校验入口方法
    public static void checkSql(String sql) throws Exception {
        CCJSqlParserManager parserManager = new CCJSqlParserManager();
        Statement statement = parserManager.parse(new StringReader(sql));
        // 先校验语句类型是否在白名单中
        if (!SUPPORTED_STATEMENT_TYPES.contains(statement.getClass())) {
            throw new UnsupportedOperationException("不支持的SQL语句类型: " + statement.getClass().getSimpleName());
        }
        // 如果是Select语句，使用自定义访问者校验
        if (statement instanceof Select) {
            SelectFeatureVisitor visitor = new SelectFeatureVisitor();
            ((Select) statement).getSelectBody().accept(visitor, null);
        }
    }

    public static void main(String[] args) {
        // 测试用例1：包含不支持的LIMIT子句
        String sql1 = "SELECT id FROM user LIMIT 10";
        try {
            checkSql(sql1);
        } catch (Exception e) {
            System.out.println("SQL1校验失败: " + e.getMessage());
        }

        // 测试用例2：包含不支持的聚合函数
        String sql2 = "SELECT avg(score) FROM student";
        try {
            checkSql(sql2);
        } catch (Exception e) {
            System.out.println("SQL2校验失败: " + e.getMessage());
        }

        // 测试用例3：支持的SQL
        String sql3 = "SELECT count(id) FROM user";
        try {
            checkSql(sql3);
            System.out.println("SQL3校验通过");
        } catch (Exception e) {
            System.out.println("SQL3校验失败: " + e.getMessage());
        }
    }
}

2. 扩展支持特性范围

如果需要支持更多SQL特性，只需要往对应的白名单集合中添加对应的类或者名称即可。比如要支持Insert语句中的ON DUPLICATE KEY UPDATE特性，可以在Insert对应的访问方法中移除对该特性的校验逻辑，或者将其加入支持范围。

3. 异常统一处理

可以自定义一个统一的SQL校验异常类，将所有不支持的特性报错信息封装到该异常中，方便上层业务统一捕获处理。

public class UnsupportedSqlFeatureException extends RuntimeException {
    private final String sqlFeature;

    public UnsupportedSqlFeatureException(String message, String sqlFeature) {
        super(message);
        this.sqlFeature = sqlFeature;
    }

    public String getSqlFeature() {
        return sqlFeature;
    }
}

注意事项

在实际使用中需要注意，JSqlParser的版本更新可能会新增对部分SQL特性的支持，因此需要定期同步白名单和支持范围，避免误报。另外，对于部分解析时直接抛出解析异常的SQL，可以在调用checkSql方法前先捕获JSqlParser原生的解析异常，统一返回不支持的提示。

如果业务中需要支持动态配置允许的特性，可以将白名单改为从配置文件或者数据库加载，实现更灵活的特性管控。对于复杂的SQL特性校验，也可以结合AST节点的属性深度判断，比如校验子查询的嵌套层级是否符合要求等。

JSqlParserSQL解析自定义报错SQL特性校验Java修改时间：2026-06-21 11:33:34