Antlr语法解析实战：从文法设计到符号表与表达式求值

做编译原理相关项目或者自研工具链的时候，最卡人的往往不是后面那些“高级”算法，而是开头那一关：怎么把一段文本变成程序能理解的结构。我最早是照着编译原理教材手写递归下降解析器，几百行代码应付一个简单表达式还行，一旦语法规则多起来，改一处就要牵连一片，调试到怀疑人生。直到后来在项目里用上 Antlr 这个开源语法分析工具，整个思路才真正打开。Antlr 全称是 ANother Tool for Language Recognition，由 Terence Parr 长期维护，能把语法规则直接转成可运行的词法分析器和语法分析器，编译原理里的很多经典问题都被它封装掉了，你要做的就是专注在语法本身的表达上。这篇文章想用一套完整实操，把“Antlr 做语法解析”这条链路讲透：从文法设计、代码生成，到符号表实现、表达式求值，再到常见的坑。适合正在啃编译原理的学生，也适合想在业务里引入 DSL 的工程师。

1. 先搞明白：Antlr 到底替我们做了什么

1.1 从一段文本到语法树，中间发生了什么

编译原理课上一定讲过这个词法分析和语法分析的先后顺序。一段源代码先进入词法分析器，也就是 scanner，把字符流切成有意义的 Token，比如关键字、变量名、数字、运算符；然后语法分析器 parser 按照文法规则把这些 Token 组装成一棵语法树。Antlr 厉害的地方在于，它同时生成 Lexer 和 Parser，你在一个 .g4 文件里写规则，它会产出两个核心类：一个负责切词，一个负责解析。

很多初学者以为“语法分析”就是拿正则匹配一下文本，其实差了十万八千里。正则很擅长判断“这个符号串长什么样”，但表达不出嵌套结构。你没法用正则判断 ((1+2)*3) 的括号配不配对，更别说把它们组织成一棵树。Antlr 的语法规则是基于上下文无关文法的，天然支持递归嵌套，比如表达式里还能套表达式，这就是它能处理语言的基本原因。

Antlr 最终产出的是解析树，也叫 ParseTree。这棵树把 Token 按照文法规则的层次关系完整保留下来。你可以在树上看到 expr 节点，下面挂着运算符和子表达式。后面任何你想做的事情——求值、翻译、静态检查、生成中间代码——都是从这棵树开始的。语义分析阶段的符号表、类型检查，都建立在这棵树的基础上。

1.2 手写解析器和 Antlr 的取舍

我记得自己第一次认真想用 Antlr，是被某个项目的配置格式折磨得够呛。当时需要解析一种自定义的查询语言，语法规则大概有三十多条，手写递归下降的代码将近两千行，而且每个函数都长得很像：先 lookahead 一个 Token，判断分支，然后递归调用。一旦改动语法结构，相关函数基本全部要动。后面把同一套文法用 Antlr 重写，.g4 文件只有几百行，生成的代码能直接跑，维护成本降了一个量级。

但我要说一句公道话：手写 parser 不是没有价值。对于只有几个规则的 DSL，比如只解析 key=value 形式的配置，手写会更快，也不需要引入运行时依赖。另外，在极致性能场景下，比如数据库内核里那种每秒解析上万条 SQL 的系统，手写的递归下降 parser 通常比 Antlr 生成的通用 parser 快很多，因为可以针对特定文法做大量手工优化。Antlr 的定位是让你在绝大多数场景下节省人力，而不是在每一种场景里都做到理论最快。

版本方面现在不用纠结了，直接用 Antlr4。4.x 对比 3.x 最核心的变化是采用了自适应 LL(*) 算法，可以处理大多数左递归文法，不再需要你手工消除左递归。这意味着你可以直接写 expr: expr '+' expr 这种自然规则，语法文件的可读性提升明显。

1.3 Antlr 在各语言生态里的位置

Antlr 的老家是 Java，但它生成的代码支持很多语言目标，比如 Python、C#、JavaScript、Go、Swift、C++。你在 Java 后端项目里经常能看到它的身影，很多数据查询工具、报表引擎、规则引擎的解析层都是基于 Antlr 做的。我自己在 Java 项目里用得最多，配一个 Maven 插件就能在 build 阶段自动从 .g4 生成 parser 代码，非常方便。

顺带提一句，很多人问“Swift 编译原理跟 Antlr 有什么关系”。Swift 编译器本身有自己手写的 parser，并没有直接用 Antlr，但社区里有很多人基于 Antlr 写 Swift 语法解析器，用来做代码分析、自动重构、文档生成。这说明一个道理：Antlr 不只是玩具，它可以承担工业级语言前端的一部分工作。你掌握这套工具之后，遇到任何“需要把文本变成结构化数据”的场景，都会比那些只会调现成库的人多一个底层武器。

2. 动手：用 Antlr 写一个计算器帮你建立完整心智模型

2.1 环境准备：搞定 antlr4 运行环境

我以 Java 环境为例，因为 Antlr 对 Java 的支持最成熟。先确保本机有 JDK 8 以上，然后下载 Antlr 的完整 jar 包。可以在官网下载 antlr-4.13.2-complete.jar，之后配置一个别名，把 jar 包路径加进去，方便在命令行调用。我自己在 Mac 上通常会写进 ~/.zshrc：

bash复制alias antlr4='java -jar ~/tools/antlr-4.13.2-complete.jar'
alias grun='java -cp .:$HOME/tools/antlr-4.13.2-complete.jar org.antlr.v4.gui.TestRig'

grun 是 Antlr 自带的测试工具，用它可以很方便地查看 Token 流和语法树图形界面，调试文法阶段能省很多事。如果你用 IntelliJ IDEA，强烈建议装一个 ANTLR v4 插件，它能在编辑器里直接预览语法树，鼠标点到哪条规则，树就高亮到哪，调试体验比命令行好太多。

Maven 项目里则是在 pom.xml 里加依赖和插件：

xml复制<dependencies>
    <dependency>
        <groupId>org.antlr</groupId>
        <artifactId>antlr4-runtime</artifactId>
        <version>4.13.2</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.antlr</groupId>
            <artifactId>antlr4-maven-plugin</artifactId>
            <version>4.13.2</version>
            <executions>
                <execution>
                    <goals>
                        <goal>antlr4</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

插件默认会去 src/main/antlr4 目录下找后缀为 .g4 的语法文件，编译时自动生成 parser 源码。

2.2 设计文法文件：一个计算器该怎么描述

我们的目标是解析类似 1+2*3、(1+2)*4 这样的算术表达式。新建一个 Calc.g4 文件，Antlr 的文法文件第一行要声明 grammar 名字，最好跟文件名保持一致：

antlr复制grammar Calc;

prog: stat+ ;

stat: expr NEWLINE        # printExpr
    | ID '=' expr NEWLINE # assign
    ;

expr: expr op=('*'|'/') expr  # MulDiv
    | expr op=('+'|'-') expr  # AddSub
    | INT                     # int
    | ID                      # id
    | '(' expr ')'            # parens
    ;

MUL : '*' ;
DIV : '/' ;
ADD : '+' ;
SUB : '-' ;
ID  : [a-zA-Z_][a-zA-Z_0-9]* ;
INT : [0-9]+ ;
NEWLINE : '\r'? '\n' ;
WS : [ \t]+ -> skip ;

这里面有几件值得细说的事情。词法规则一般全大写，语法规则全小写，这是 Antlr 的强约定。expr 规则的几种选择写在|后面，并且给每个分支起了别名，比如 # MulDiv、# AddSub，这些别名会直接用来生成 visitor 方法名，后面遍历树的时候非常有用。

优先级怎么处理？Antlr4 在左递归规则里按声明顺序决定优先级，越靠前的规则优先级越高。所以 MulDiv 写在 AddSub 前面，乘除法自然比加减法绑得更紧。经典面试题“括号优先级最高”也直接支持：'(' expr ')' 分支的存在让括号整个作为一个子表达式。

最后是空白字符问题。WS : [ \t]+ -> skip 表示空格和 Tab 直接丢弃，不进入 Token 流。如果不写这条，输入里的空格会导致解析失败，或者变成额外的 Token 干扰规则匹配。

2.3 生成代码并跑通第一个程序

在终端执行：

bash复制antlr4 Calc.g4
javac Calc*.java

这里有个历史包袱：Antlr4 完成为 .g4 生成的是 CalcLexer、CalcParser 以及一组 visitor/listener 基类，但课程和教科书里常常把“词法分析器”说成 Lexer，把“语法分析器”说成 Parser，这其实是编译原理术语在 Antlr 里的直接对应。接下来写一个主函数调用它：

java复制import org.antlr.v4.runtime.*;
import org.antlr.v4.runtime.tree.*;

public class CalcMain {
    public static void main(String[] args) throws Exception {
        CharStream input = CharStreams.fromString("1+2*3\n");
        CalcLexer lexer = new CalcLexer(input);
        CommonTokenStream tokens = new CommonTokenStream(lexer);
        CalcParser parser = new CalcParser(tokens);
        ParseTree tree = parser.prog();
        System.out.println(tree.toStringTree(parser));
    }
}

运行之后如果输出类似 (prog (stat (expr (expr 1) + (expr (expr 2) * (expr 3))) \n)) 这样的嵌套串，说明解析链路没问题。Antlr 的 toStringTree 是肉眼快速验证解析结果最简单的途径，比调试器直观。

2.4 影响解析结果的隐藏细节：隐式 Token 和跳过空白

首次接触 Antlr 的人最容易踩的一个坑是隐式 Token。在语法规则里直接写了字符串字面量，比如 '+'、'='，Antlr 会自动为它创建一个匿名词法规则。如果这个字面量在多个语法规则里反复出现，问题还不大，但它会和显式词法规则产生优先级冲突。

举个例子，你写了一条 ID : [a-zA-Z]+ ;，同时在语法规则里写了 'select'。如果输入的文本是 select，Antlr 会把它匹配成哪个？答案是 'select' 这个隐式字面量，因为隐式字面量的优先级高于同长度的显式规则。这通常不是你想要的结果，因为 select 可能应该被当成 ID 传播到后面逻辑里。解决办法是在词法规则里显式声明关键字：

antlr复制SELECT : 'select' ;
ID : [a-zA-Z]+ ;

然后语法规则里用 SELECT 而不是 'select'。这对所有做 DSL 的人都适用：关键字最好显式定义在词法规则里，而不是散落在语法规则字符串中。

空白字符跳过规则同样有讲究。上面写的是 -> skip，意思是丢弃 Token。还可以用 -> channel(HIDDEN)，把空白放到隐藏通道，这样 parser 看不到空白，但你能从 Token 流里拿到原始位置信息，做代码格式化工具时特别有用。计算器不需要位置信息，所以 skip 就够。

3. 解析树之后：你要在符号表上花心思

3.1 解析树并不等于最终想要的数据结构

很多人刚学会 Antlr 会陷入一种错觉：拿到 ParseTree 就等于解析成功了。其实 ParseTree 里面塞满了文法细节，比如括号节点、. 分隔符、逗号这些“语法糖”都在树里。你要是直接基于它做求值，每遇到一种文法修改都要跟着改，非常痛苦。

编译原理的经典做法是构建 AST，也就是抽象语法树，把编程语言里真正需要的结构提炼出来。比如表达式 (1+2) 在 ParseTree 里会有一个 parens 节点，里面再挂 expr 子节点，但在 AST 里可以直接变成一个 BinaryExpr(left=1, op=+, right=2)，括号这个信息完全消失了，因为括号本来就只是控制优先级，表达式结构已经隐含了优先级。

不过 Antlr 有个务实的选择：你可以不显式建 AST，而是直接遍历 ParseTree，配合 visitor 或者 listener 在运行时拼装自己的对象。小项目这么做完全没问题，省去一堆节点类。但如果语言比较复杂，比如后面要多次遍历语法信息做优化，那还是老老实实建 AST，把语义信息缓存到节点上。

3.2 设计一个带作用域的符号表

符号表是编译原理课程里的重头戏，对应到实操里，一般就是维护一组“名字到符号信息”的映射，并处理作用域。Antlr 本身不管符号表，它只负责告诉你“这里出现了一个变量名叫 a”，至于 a 是什么意思、类型是什么、作用域在哪，全得你实现。

我先定义一个最基本的符号表来演示：

java复制public class Symbol {
    String name;
    String type;
    public Symbol(String name, String type) {
        this.name = name;
        this.type = type;
    }
}

再定义一个作用域接口。作用域之间会有嵌套关系，比如函数体里面能看到全局的变量，但全局看不到函数体里面的局部变量：

java复制public interface Scope {
    String getScopeName();
    Scope getEnclosingScope();
    void define(Symbol sym);
    Symbol resolve(String name);
}

主流的实现方式是使用一个 BaseScope 类，内部放一个 Map<String, Symbol>。定义新变量时，如果当前作用域里已经有同名变量，就报重复定义错误；解析变量时，从当前作用域往上层逐级查找：

java复制public Symbol resolve(String name) {
    Symbol s = symbols.get(name);
    if (s != null) return s;
    if (enclosingScope != null) return enclosingScope.resolve(name);
    return null;
}

这就是符号表最核心的“作用域链”查找逻辑。很多编译原理简答题让你描述符号表怎么组织，核心就是 Map + 父级作用域指针。你把这个代码写熟，面试笔试基本都能应对。

3.3 用监听器还是访问器：Antlr 两种遍历方式的取舍

Antlr4 默认生成两套 ParseTree 遍历接口：listener（监听器模式）和 visitor（访问者模式）。它们的区别很本质：listener 是“外部驱动”的，你实现一个 BaseListener，然后让 ParseTreeWalker 自动深度优先遍历整棵树，在进入节点和离开节点时会回调 enterXXX 和 exitXXX 方法。visitor 则是你主动调用 visitXXX 方法，必须在每个方法里决定要不要继续往下走，以及返回什么值。

我做符号表填充时更喜欢 listener，因为你不关心树的遍历次序，只管在每个进入节点的地方做操作。比如进入 stat 节点的 assign 分支时，把左边变量的名字注册到当前作用域里。访问者模式则更适合表达式求值和代码生成这种需要把“子节点结果向上传递”的场景。

这里有个实操心得：如果你用 listener，一定要分清 enter 和 exit 的时机。enter 是节点还没访问子节点时触发，exit 是子节点全部访问完后触发。符号表的进入作用域和退出作用域就应该放在块节点的 enter 和 exit 里，保证嵌套块内部定义的变量在外边不可见。

4. 完整实战：实现一个带变量和表达式的脚本解释器

4.1 定义一个支持变量与打印语句的脚本语言

为了不让前面那些理论知识悬空，我们来做一个完整的解释器。这个脚本语言支持这么几种语句：

• let x = 10 + 5;
• print x;
• { let x = 1; print x; }，大括号代表一个块作用域。

文法文件我命名为 Script.g4：

antlr复制grammar Script;

program: statement+ ;

statement
    : 'let' ID '=' expr ';'  # letStat
    | 'print' expr ';'       # printStat
    | '{' statement+ '}'     # blockStat
    ;

expr
    : expr op=('*'|'/') expr # mulDiv
    | expr op=('+'|'-') expr # addSub
    | INT                    # int
    | ID                     # id
    | '(' expr ')'           # parens
    ;

LET : 'let' ;
PRINT : 'print' ;
ID : [a-zA-Z_][a-zA-Z_0-9]* ;
INT : [0-9]+ ;
WS : [ \t\r\n]+ -> skip ;

这里省略了分号处理细节，实际写的时候把 ';' 和 '{' '}' 作为字面量直接放在规则里没有问题，Antlr 会生成隐式 Token，而关键字 let、print 则显式声明成词法规则，避免被 ID 吃掉。

4.2 符号表联动：作用域进入退出和变量检查

遍历时我推荐用 listener。核心逻辑是：维护一个“当前作用域”的栈，碰到 let 语句时在当前作用域定义新变量，碰到普通表达式里的 id 节点时去符号表里查是否存在。

我定义一个 ScriptListener 来挂逻辑，继承 Antlr 生成的 ScriptBaseListener：

java复制public class DefPhase extends ScriptBaseListener {
    private Scope currentScope;

    public DefPhase(Scope globalScope) {
        this.currentScope = globalScope;
    }

    @Override
    public void enterBlockStat(ScriptParser.BlockStatContext ctx) {
        currentScope = new BaseScope(currentScope);
    }

    @Override
    public void exitBlockStat(ScriptParser.BlockStatContext ctx) {
        currentScope = currentScope.getEnclosingScope();
    }

    @Override
    public void enterLetStat(ScriptParser.LetStatContext ctx) {
        String name = ctx.ID().getText();
        Symbol sym = new Symbol(name, "int");
        currentScope.define(sym);
    }

    @Override
    public void exitId(ScriptParser.IdContext ctx) {
        if (currentScope.resolve(ctx.ID().getText()) == null) {
            System.err.println("undefined variable: " + ctx.ID().getText());
        }
    }
}

这个代码虽然简单，但已经能体现出符号表在语义分析中的职责。实际工程里，你还会遇到重复定义、类型不匹配、在初始化前使用变量等问题，核心思路都一样：解析期间维护一套上下文信息，然后做各种检查。编译原理里把这些统称为语义分析，是在 parser 之后的第四阶段，Antlr 把它留给了你。

4.3 表达式求值和逆波兰式：中缀转后缀那点事

表达式求值部分，我完全可以基于 ParseTree 直接递归算出来，但既然热搜词里出现了“逆波兰式”，顺便把它讲清楚，因为这个概念在课程里反复考，也在栈的应用里占着一席之地。

逆波兰式也叫后缀表达式，正常写法 1 + 2 的中缀表达式，转成后缀是 1 2 +。转换规则可以用操作符优先级做：遇到操作数直接输出，遇到操作符则弹出栈顶优先级不低于当前操作符的操作符，最后把当前操作符入栈。括号有一点特殊处理，左括号入栈，右括号弹栈直到左括号。计算出后缀之后，用栈求值非常无脑：遇到数字入栈，遇到运算符弹出两个数字计算结果再入栈。

但如果你已经用 Antlr 拿到了 ParseTree，其实没必要真的转后缀。树结构已经天然地把优先级和括号消除了，你只需要从叶子往上做后序遍历，每个节点的值等于左右子节点按照运算符计算：

java复制public class EvalVisitor extends ScriptBaseVisitor<Integer> {
    @Override
    public Integer visitInt(ScriptParser.IntContext ctx) {
        return Integer.valueOf(ctx.INT().getText());
    }

    @Override
    public Integer visitId(ScriptParser.IdContext ctx) {
        return symbols.get(ctx.ID().getText());
    }

    @Override
    public Integer visitAddSub(ScriptParser.AddSubContext ctx) {
        int left = visit(ctx.expr(0));
        int right = visit(ctx.expr(1));
        if (ctx.op.getType() == ScriptParser.ADD) return left + right;
        return left - right;
    }

    @Override
    public Integer visitMulDiv(ScriptParser.MulDivContext ctx) {
        int left = visit(ctx.expr(0));
        int right = visit(ctx.expr(1));
        if (ctx.op.getType() == ScriptParser.MUL) return left * right;
        return left / right;
    }
}

这个 visitor 的巧妙之处在于，它不需要显式管理栈，递归调用天然就是深度优先的“后序遍历”，和逆波兰式求值在本质上是一回事。理解这一点之后，你就知道编译原理里学逆波兰式不是白学的，它训练的正是“树遍历和栈求值”这门手艺。

4.4 语法错误处理：别让默认行为把你带沟里

真实程序不可能永远一次解析成功。Antlr 默认的错误恢复策略是异常兜底加 Token 删除/插入，也就是它会尝试从错误里恢复过来，继续解析后面的内容。这个行为在 IDE 场景里很好用，因为你想让编辑器尽可能多地标红，不想因为一个错误就停止整个文件分析。

但如果你是在做命令行编译器、数据转换工具，默认策略反而会坑你：它可能把一段本应报错的输入“恢复”成一个可以解析的树，导致后面求值时出现空指针或者奇怪结果。我在做脚本解释器时，直接换成了抛出异常的 BailErrorStrategy：

java复制parser.setErrorHandler(new BailErrorStrategy());

再配合自定义词法错误监听器，遇到第一个错误就立刻抛异常终止。这样行为最简单：要么完整解析成功，要么抛错，没有中间态。这一条对新手来说尤其重要，因为默认的错误恢复会让测试用例看起来“成功”但是结果错误，排查起来特别浪费时间。

5. 常见问题与排查技巧实录

5.1 歧义规则：为什么我的规则总是匹配错

Antlr 的词法分析遵循最大匹配原则。两个规则都能匹配同一段文本时，占字符更长的那条胜出；长度一样时，写在更前面的规则胜出。这解释了为什么很多人的 ID : [a-zA-Z]+ ; 会把关键字也匹配掉。要解决，就把关键字规则写在 ID 前面，或者干脆使用词法规则里的谓词做条件匹配。

语法层面也有歧义。比如你写了两个分支都能推导出同一段输入，Antlr4 在相同优先级的情况下默认选择先出现的分支。这通常不是你想依赖的行为，而是应该在文法层面消除歧义。我建议你遇到诡异匹配结果时，先打开 IDEA 插件看一下语法树，通常一眼就能看出节点挂错了地方。

5.2 左递归报错与解决方法

Antlr4 官方文档明确支持直接左递归，比如 expr: expr '+' expr。但它并不支持间接左递归，比如 a 规则调用 b 规则，b 规则又调用 a 规则。很多从旧版本迁移过来的文法会有这个问题，报错信息会提示 The following sets of rules are mutually left-recursive。

解决间接左递归的办法是把文法改写成直接左递归，或者引入一个优先级提升的结构。实际项目里，我遇到过部分嵌套表达式解析循环溢出的问题，原因是有个规则在不经意间形成了 a -> b -> a 的隐式递归。排查方法只有一个：把所有规则调用画出来找环。Antlr 的报错已经能定位到具体规则，照着改就行。

5.3 默认错误恢复过头导致结果看起来对

前文提过 BailErrorStrategy。我再补充一个点：错误监听器里的 reportAmbiguity、reportAttemptingFullContext 这些方法大多是信息性的。在调优阶段可以打印级别到控制台，但正式环境不要开全量日志，否则会把控制台刷爆。比较好的做法是只在 debug 开关下打印。

对于提供 API 服务的场景，我建议同时把 parser.removeErrorListeners() 和 lexer.removeErrorListeners() 调一下，去掉默认输出到 System.err 的监听器，然后注册自己的监听器收集错误信息。这样外部用户不会直接看到一堆难懂的堆栈或内部符号。

5.4 性能与内存：解析大文件时的那些事

Antlr 的内存占用大头在 Token 流和 ParseTree。如果你要解析一个几十万行的文件，默认的 BufferedTokenStream 会吃不少内存，解析树对象数量更多。在做一次性分析工具时通常无所谓，但在线服务里每请求都生成一棵大 ParseTree 就很有压力。

一个常规优化是把 Token 流或者 ParseTree 改成“按需加载”的自定义实现。另一个办法是用 SLL 模式先试一把，这个模式比默认的 LL 模式快不少，但因为不做完整上下文推断，遇到某些文法会误报失败。ParserInterpreter 也经常被拿来分析语法本身。如果你读到这里开始觉得陌生，没关系，大多数场景用不上这些深水区的优化。只要记住：性能出问题时，第一个排查点是不要解析完还留着整棵 ParseTree 不放，第二个尽量复用 Lexer 和 Parser 实例，避免频繁分配。

5.5 问题排查速查表

这张表基本涵盖了我用 Antlr 过程中遇到的高频问题。项目做到后期，真正让我节省时间的不再是翻文档找 API，而是对这套排查思路的熟悉程度。你只要坚持用 IDE 插件可视化语法树，配合 toStringTree 输出和符号表日志，大部分问题都能在十分钟内定位。

最后再分享一个小技巧：给 .g4 文件做版本管理时，把生成的代码加入 .gitignore，因为它们是构建产物，不应该进仓库。每次改文法后重新生成就好，团队协作时避免一堆无意义的 diff。Antlr 这套工具链一旦熟练，你会发现做语言类项目的速度能提升一个档次。