DBeaver LSM 模块解析：基于 ANTLR 的 SQL 方言解析架构与扩展机制

DBeaver 需要为几十种数据库方言统一地"读懂" SQL，plugins/org.jkiss.dbeaver.model.lsm 插件就是承担这一职责的核心：它基于 ANTLR 文法构建了一套词法/语法解析基础设施（STM 包），并通过 OSGi 扩展点把"方言 → 解析器"映射成可插拔的注册机制（LSM 包）。读完本文，你将掌握 LSM 模块的 AST 节点体系、LSMAnalyzer 的解析调用链、LSMAnalyzerParameters/STMSource/STMErrorListener 等关键类型的用法，以及如何通过 lsmDialect 扩展点为特定数据库方言注册自定义解析器。

模块定位：文法、解析器与方言适配三层结构

LSM（Language/Statement Model）插件围绕三个层次组织代码（对应 README 中架构图的类职责划分）：

• 文法层：ANTLR 文法文件 SQLStandardLexer.g4 与 SQLStandardParser.g4 定义了通用 SQL 词法规则与语法规则，编译生成 SQLStandardLexer / SQLStandardParser 供各分析器复用；
• STM 基础设施层：org.jkiss.dbeaver.model.stm 包封装 ANTLR 通用能力——解析器基类、AST 节点、错误监听器、文本源抽象；
• LSM 分析器层：org.jkiss.dbeaver.model.lsm 包提供分析器接口、方言注册表和语句模型（LSMSelectStatement 等语义元素）。

解析器类体系的根基是 STMParserOverrides，它继承 ANTLR 的 Parser 并强制开启构建解析树（setBuildParseTree(true)）：

public abstract class STMParserOverrides extends Parser {
    public STMParserOverrides(@NotNull TokenStream input) {
        super(input);
        this.setBuildParseTree(true);
    }

    @Override
    public ErrorNode createErrorNode(@NotNull ParserRuleContext parent, @NotNull Token t) {
        return new STMTreeTermErrorNode(t);
    }

    @Override
    public TerminalNode createTerminalNode(@NotNull ParserRuleContext parent, @NotNull Token t) {
        return new STMTreeTermNode(t, this.getState());
    }
}

它的两个工厂方法覆写非常关键：ANTLR 构建语法树时创建节点都会走 createTerminalNode/createErrorNode，被覆写后，整棵树里的终端节点与错误节点天然就是 DBeaver 自定义的 STMTreeNode 类型——这就是 README 所说"通过继承解析器来定制 AST 节点"的实现落点。

AST 节点体系：三类节点统一于 STMTreeNode

按 README 的划分，解析树节点分三类，源码中三者的继承关系如下（节点类的实现位于 org.jkiss.dbeaver.model.stm 包）：

节点类型	类	继承的 ANTLR 基类	说明
终端节点	STMTreeTermNode	TerminalNodeImpl	对应具体词法 token（标识符、数字、运算符等）
非终端节点	STMTreeRuleNode	ParserRuleContext	对应语法规则的上下文，是规则树的"上下文对象"
错误节点	STMTreeTermErrorNode	ErrorNodeImpl	解析失败/未消费的 token 落位

三者都实现了统一的 STMTreeNode 契约（从源码结构看，它是接口而非类：三个节点类分别以 extends XxxImpl implements STMTreeNode 的方式接入 ANTLR 节点体系）。README 中"解析文本后得到 STMTreeNode 类型对象"的说法，对应到接口签名就是 LSMAnalyzer：

public interface LSMAnalyzer {
    @Nullable
    STMTreeRuleNode parseSqlQueryTree(@NotNull STMSource source, @Nullable STMErrorListener errorListener);
}

返回值声明为 STMTreeRuleNode（非终端节点），即解析结果是一棵以规则节点为根的完整语法树；返回类型带 @Nullable，意味着遇到无法恢复的识别异常时可能返回 null（见下文解析主流程）。

解析主流程：LSMAnalyzerImpl 的模板方法

所有分析器的公共逻辑集中在抽象类 LSMAnalyzerImpl。它对子类只暴露两个抽象方法，其余为模板方法：

• createParser(source, parameters)（抽象）：创建该方言的 Lexer + Parser 对，返回 Pair<TLexer, TParser>；
• parseSqlQueryImpl(parser)（抽象）：驱动 parser 执行具体入口规则并返回根节点；
• prepareParser(source, errorListener)（具体，可覆写）：调用 createParser 后，若外部传入了 errorListener，则把 lexer 和 parser 默认的 ConsoleErrorListener 移除、换上调用方指定的监听器，并将预测模式设为 PredictionMode.LL：

protected TParser prepareParser(@NotNull STMSource source, @Nullable STMErrorListener errorListener) {
    Pair<TLexer, TParser> pair = this.createParser(source, this.parameters);
    ...
    if (errorListener != null) {
        lexer.removeErrorListener(ConsoleErrorListener.INSTANCE);
        lexer.addErrorListener(errorListener);
        parser.removeErrorListener(ConsoleErrorListener.INSTANCE);
        parser.addErrorListener(errorListener);
    }
    parser.getInterpreter().setPredictionMode(PredictionMode.LL);
    return parser;
}

parseSqlQueryTree 的完整调用链是：prepareParser → parseSqlQueryImpl → result.fixup(parser)；若抛出 RecognitionException，仅记录 debug 日志并返回 null，解析错误不会向上抛出。这套"解析不抛异常、错误落到树节点"的设计正是配合 STMTreeTermErrorNode 的用途。

通用实现 SQLStandardAnalyzer 展示了标准文法下两个抽象方法的典型写法：createParser 中用 source.getStream() 构造 SQLStandardLexer，再经 CommonTokenStream 接入 SQLStandardParser；parseSqlQueryImpl 调用入口规则 parser.sqlQuery() 后，把游标之后剩余的 token 逐个包装成 STMTreeTermErrorNode 挂到根节点上——即使 parser 提前结束，"没被消费的输入"也会被显式标记为错误节点，而不是悄悄丢弃。

文本源与错误监听器：两个协作类型

README 指出解析的两个入参分别是 STMSource 与 STMErrorListener，源码如下：

STMSource 是文本源抽象，本质是向 ANTLR 提供 CharStream 的函数式接口，并内置两个静态工厂：

public interface STMSource {
    CharStream getStream();

    @NotNull
    static STMSource fromReader(@NotNull Reader reader) throws IOException {
        return new STMSourceImpl(reader);
    }

    static STMSource fromString(String string) {
        return () -> CharStreams.fromString(string);
    }
}

因此调用方可以 STMSource.fromString(sqlText) 直接解析字符串，或 STMSource.fromReader(reader) 解析流式文本。

STMErrorListener 是对 ANTLR ANTLRErrorListener 的标记式封装，用于统一错误处理类型。README 给出两种现成实现：

• STMLoggingErrorListener：把词法/语法错误写入日志，适合调试定位；
• STMSkippingErrorListener：忽略错误继续解析，适合"尽力解析"场景（例如 SQL 编辑器中尚未写完的语句）。

结合 LSMAnalyzerImpl.prepareParser 的实现可知：传入 null 时保留 ANTLR 默认监听器行为，传入具体实例时完全接管 lexer 与 parser 两侧的错误回调。

方言注册表：LSMDialectRegistry 的工作机制

具体使用哪个 LSMAnalyzer 实现，由 LSMDialectRegistry 单例决定。它的核心是一张"方言类 → 分析器工厂"的映射表：

private final Map<Class<? extends SQLDialect>, LSMAnalyzerFactory> knownLsmAnalyzerByDialects = new HashMap<>();

加载过程分三步：

1. getInstance() 首次调用时通过 Platform.getExtensionRegistry() 读取扩展点 org.jkiss.dbeaver.lsm.dialectSyntax 的全部配置项（扩展点常量即 EXTENSION_ID）；
2. loadExtensions 过滤出名为 lsmDialect 的配置元素并逐一注册；
3. registerLsmDialect 用 createExecutableExtension 实例化 analyzerFactoryClass，并按 appliesTo 子元素的 dialectClass 属性（经 AbstractDescriptor.getObjectClass 解析为具体类）写入映射表。

查找逻辑值得注意——getAnalyzerFactoryForDialect 沿方言类的父类链向上回溯查找工厂：

do {
    analyzerFactory = knownLsmAnalyzerByDialects.get(dialectClass);
    dialectClass = dialectClass.getSuperclass();
} while (analyzerFactory == null && dialectClass != null);

这意味着即使某方言没有直接注册，只要其父类链上有注册项即可命中；完全找不到时抛出 IllegalStateException（提示"驱动配置非法"），保证任何方言都必然有确定性的解析器归属。

扩展点配置：lsmDialect 的声明与注册

扩展点本身在 LSM 插件的 plugin.xml 中声明，并配有模式文件 dialectSyntax.exsd：

<extension-point id="org.jkiss.dbeaver.lsm.dialectSyntax"
                 name="Dialect Syntax Analyzer Provider"
                 schema="schema/org.jkiss.dbeaver.lsm.dialectSyntax.exsd" />

兜底注册：README 中的通用文法注册示例（appliesTo 指向 BasicSQLDialect）说明了用法意图；当前仓库快照中实际落地的兜底注册位于 org.jkiss.dbeaver.model.sql/plugin.xml，把 SQLStandardAnalyzerFactory 绑定到更上层的 AbstractSQLDialect：

<extension point="org.jkiss.dbeaver.lsm.dialectSyntax">
    <lsmDialect analyzerFactoryClass="org.jkiss.dbeaver.model.lsm.sql.dialect.SQLStandardAnalyzerFactory">
        <appliesTo dialectClass="org.jkiss.dbeaver.model.impl.sql.AbstractSQLDialect"/>
    </lsmDialect>
</extension>

这正是上节"父类链回溯"机制的实际受益场景：绝大多数数据库方言都继承自抽象基类，未单独注册时自动回落到标准分析器。SQLStandardAnalyzerFactory 的实现极其简洁（见 SQLStandardAnalyzerFactory）：

public class SQLStandardAnalyzerFactory implements LSMAnalyzerFactory {
    @Override
    public LSMAnalyzer createAnalyzer(@NotNull LSMAnalyzerParameters parameters) {
        return new SQLStandardAnalyzer(parameters);
    }
}

需要说明：README 示例中工厂方法签名为 createAnalyzer(SQLDialect dialect)，当前源码中 LSMAnalyzerFactory 的签名已演进为接收 LSMAnalyzerParameters 参数对象，方言信息经由该参数对象随分析器构造传递——README 关于"Analyzer 接受携带 SQL 语言上下文的 SQLDialect"的表述在语义上仍然成立，只是载体从裸 dialect 引用变成了参数对象。

为特定方言定制解析器：SQLite 案例

当通用文法不够用（例如需要开启方言特有的标识符引用方式），README 给出的扩展路径是三步走，以 SQLite 为例：

第一步：继承 SQLStandardAnalyzer 并覆写 prepareParser，在标准解析器上打开方言开关：

public class SQLiteSQLAnalyzer extends SQLStandardAnalyzer {
    public SQLStandardAnalyzer(@NotNull SQLDialect dialect) {
        super(dialect);
    }

    @NotNull
    @Override
    protected SQLStandardParser prepareParser(@NotNull STMSource source, @Nullable STMErrorListener errorListener) {
        SQLStandardParser parser = super.prepareParser(source, errorListener);
        parser.setIsSupportSquareBracketQuotation(true); // 允许方括号引用标识符
        return parser;
    }
}

注意覆写时机：先调 super.prepareParser 完成 lexer/parser 装配与错误监听器替换，再在现成的 parser 实例上追加方言配置——这与 LSMAnalyzerImpl.prepareParser "具体方法、可覆写"的定位一致。

第二步：实现工厂接口：

public class SQLiteAnalyzerFactory implements LSMAnalyzerFactory {
    @Override
    public LSMAnalyzer createAnalyzer(SQLDialect dialect) {
        return new SQLiteSQLAnalyzer(dialect);
    }
}

第三步：在方言插件的 plugin.xml 中注册扩展：

<extension point="org.jkiss.dbeaver.lsm.dialectSyntax">
    <lsmDialect analyzerFactoryClass="org.jkiss.dbeaver.ext.sqlite.model.SQLiteSQLAnalyzer">
        <appliesTo dialectClass="org.jkiss.dbeaver.ext.sqlite.model.SQLiteSQLDialect"/>
    </lsmDialect>
</extension>

从源码结构看，当前仓库快照中 lsmDialect 扩展项仅出现在 org.jkiss.dbeaver.model.sql/plugin.xml 的兜底注册，SQLite 插件（org.jkiss.dbeaver.ext.sqlite/plugin.xml）中目前只有 org.jkiss.dbeaver.sqlDialect 方言声明、尚无独立的 lsmDialect 注册——SQLite 示例应视为 README 给出的标准扩展范式，其方言解析当前依靠父类链回退命中标准分析器。若要真正落地该示例，需在 SQLite 插件中补齐上述三个组件并声明扩展。

文法入口规则与整体调用链小结

通用文法的入口规则定义在 SQLStandardParser.g4：

sqlQueries: sqlQuery (Semicolon sqlQuery)* Semicolon? EOF;
sqlQuery: (directSqlDataStatement|callStatement|sqlSchemaStatement|sqlTransactionStatement|sqlSessionStatement|selectStatementSingleRow) anyWord??;

sqlQueries 要求匹配到 EOF（注释标明"don't stop early, must match all input"），与 SQLStandardAnalyzer.parseSqlQueryImpl 中"剩余 token 挂为错误节点"的兜底逻辑互为补充：前者保证完整输入被约束，后者保证未被规则覆盖的部分在树中可见。

把整条调用链串起来：

1. 调用方构造 STMSource（fromString/fromReader）并选择错误监听策略（STMLoggingErrorListener 记录日志，STMSkippingErrorListener 静默跳过）；
2. 通过 LSMDialectRegistry.getInstance().getAnalyzerFactoryForDialect(dialect) 按方言类（含父类链回溯）取得 LSMAnalyzerFactory，创建 LSMAnalyzer；
3. 调用 parseSqlQueryTree(source, errorListener)：prepareParser 装配 lexer/parser 并切换错误监听器、设定 LL 预测模式；parseSqlQueryImpl 驱动入口规则产出 STMTreeRuleNode 根节点；
4. 得到的 STMTreeNode 树中，终端/规则/错误三类节点各司其职，供上层（如 SQL 编辑器的语句切分与语法感知功能）继续消费。

对需要支持新数据库的开发者，本文提供的落地清单是：准备方言类（实现/继承 SQLDialect）→ 评估能否复用 SQLStandardAnalyzer（仅参数差异则覆写 prepareParser，需要独立词法/语法则实现 createParser 返回自建 lexer/parser）→ 实现 LSMAnalyzerFactory → 在插件 plugin.xml 中声明 org.jkiss.dbeaver.lsm.dialectSyntax 扩展并指向 dialectClass。注册完成后，LSMDialectRegistry 会在平台启动时自动完成加载。