Antlr实战：从文法定义到JSON解析器的完整指南

1. 从一个折腾了很久的配置文件说起

我最早接触语法分析，是因为一个特别实际的需求：当时要做一个内部用的配置系统，格式比 JSON 灵活得多，用户能写条件表达式、能引用变量、能写简单的函数调用。一开始我用正则表达式加手写状态机硬扛，结果维护到第三个月就扛不住了——表达式嵌套一深就出错，报错位置还不准确，用户根本不知道到底是哪里写错了。

后来跟几个做编译器后端的朋友聊，他们几乎异口同声地问我："你为什么不直接用 Antlr？" 这就是我第一次听说这个工具。当时我连"语法分析"具体在编译原理里是干什么的都没完全搞清楚，满脑子都是词法分析、LL(1)、LR(1) 这些课本上的名词。但朋友说了一句话打动了我："Antlr 能让你从手写解析器的泥潭里解放出来，你只要定义规则，代码它帮你生成。"

后来我花了整整一个周末把文档啃了一遍，又花了一周把那个配置系统重写完成。从那以后，Antlr 就成了我工具箱里离不开的利器。如果你正在做 DSL 设计、配置解析、代码生成、SQL 校验、日志结构化，甚至只是想把某个老系统的文本协议解析干净，这篇文章应该能帮你省下大量试错时间。

2. Antlr 到底是什么、能解决什么问题

2.1 从编译原理视角理解 Antlr 的位置

编译原理里，一个编译前端基本可以拆成几个阶段：词法分析、语法分析、语义分析、中间代码生成。词法分析就是把字符流切成 token（比如关键字、标识符、数字、运算符），语法分析就是把 token 流按照一定的文法规则组织成语法树。

Antlr 全称是 ANother Tool for Language Recognition，它做的是词法分析加语法分析这两件事，而且做得很彻底——你给它一份文法文件，它直接生成一个能识别这种语言的解析器代码，Java、C++、Python、JavaScript、Go、Swift 等主流语言都有运行时支持。

之所以说它是"开源语法分析工具"里的首选，是因为它默认使用 ALL(*) 算法，这个算法有一个特别实用的特性：不需要你手动消除左递归。传统 LL(1) 解析器遇到直接左递归会死循环，你得费劲地改写文法。Antlr 把这件事替你干了，你直接写 expr : expr '+' term | term; 这种自然直观的规则，它内部通过动态规划的方式处理好递归问题。这对从业务转过来的开发者特别友好，因为你的思维方式不用被文法改写规则绑架。

2.2 历史版本与新特性对比

Antlr 目前用的主流版本是第 4 代，和 3.x 时代相比，变化几乎是颠覆性的。第 3 代需要你手工指定 lookahead 深度，做预测分析时要时刻想着 LL(*) 的边界，写文法的时候心理负担很重。

第 4 代引入了自适应预测机制，解析器会基于运行时信息动态决定怎么匹配规则。实际效果就是：你的文法可以写得几乎和 BNF 范式一样自然，表达力接近上下文无关语法理论极限，同时解析性能在绝大多数场景下是足够用的。而且 New BSD License 协议非常宽松，你可以放心地在商业项目里集成，不需要担心开源协议的传染性问题。

还有一个常常被低估的能力：Antlr 自带一个名叫 TestRig 的调试工具（在新版本里叫 grun），它能把解析过程和生成的语法树可视化。调试复杂文法的时候，你能直观看到 token 是怎么流动的、哪条规则匹配失败，比纯粹靠堆日志高效太多了。

2.3 它帮你省掉的核心工作量

手写一个解析器，你需要处理的事情包括但不限于：字符流管理、token 状态切换、匹配失败的回溯策略、错误位置的记录、上下文相关性的处理。这些工作杂且碎，最难受的是解析错误的信息质量——手写的解析器出错时经常只能告诉你"第 34 行有语法错误"，用户根本不知道该怎么改。

Antlr 的默认错误处理器会给出比较明确的错误位置和期望的 token 集合，你还可以覆盖 BaseErrorListener 接口做二次加工，把错误信息包装成业务可读的形式。比如解析 SQL 的时候，用户写错了字段名，你可以定位到具体的 token，甚至提示"你是否想写 created_at？"这种级别的体验，手写解析器要做到需要付出极大的成本。

3. 核心概念拆解：文法文件、规则、监听器与访问者

3.1 一个最简单的文法长什么样

我们不谈空泛的理论，直接看一个例子。假设你想解析一个简单的"变量赋值"语言，它支持整数、字符串、布尔值：

antlr复制grammar Config;

// 语法规则
config : assignment+ EOF ;
assignment : IDENT '=' value ';' ;
value : INT | STRING | BOOL ;

// 词法规则
IDENT : [a-zA-Z_] [a-zA-Z_0-9]* ;
INT : [0-9]+ ;
STRING : '"' ~["\r\n]* '"' ;
BOOL : 'true' | 'false' ;
WS : [ \t\r\n]+ -> skip ;

这个文件同时包含语法规则和词法规则，且单词法规则用大写开头命名的约定是有原因的——Antlr 根据规则名的首字母大小写判断它是语法规则还是词法规则。

-> skip 是词法指令，意思是跳过空白字符，不让它们进入 token 流。有人会问为什么不直接 匹配后丢弃，这里的关键点是：如果不去掉这些空白 token，语法规则里每个 IDENT 后面都要显式允许空白的存在，会非常啰嗦。

3.2 解析树、监听器与访问者：两种遍历方式的选择困境

Antlr 生成解析器之后，虽然默认给你一棵解析树（ParseTree），但你真正要做的事是遍历这棵树并执行操作。它提供了两种遍历机制：

• 监听器模式（Listener）：走了类似事件驱动的路子。你只需要实现 enterConfig、exitConfig、enterAssignment 这类方法，Antlr 会深度优先遍历整棵树，到某个节点时自动回调。你不需要自己写遍历逻辑，适合对解析树做整体处理后产生副作用的场景。
• 访问者模式（Visitor）：你需要显式调用访问方法，想访问哪个子节点就访问哪个，对遍历过程有完全的控制权。适合需要精确控制求值顺序，或者只处理部分子树的场景。

以我个人的实际经验，如果你在做代码生成、AST 变换这类需要"按需处理"的任务，用 Visitor；如果你在做校验、统计、建立符号表这类"旁路处理"的任务，用 Listener 就够了。最开始的配置系统我用的 Visitor，因为要对表达式做短路求值和类型推断，需要控制子节点的访问顺序。后来做日志格式解析器时，我用的是 Listener，因为只是收集字段信息，不关心遍历顺序。

3.3 词法规则里的坑：最长匹配与优先级

写词法规则最经典的坑是：Antlr 对同一输入，优先选择能匹配最长文本的词法规则；如果多个规则匹配相同长度的文本，则选择定义在文法文件中更靠前的那一条。

这个特性能解释很多奇怪现象。比如你的标识符规则是 IDENT : [a-zA-Z_] [a-zA-Z_0-9]*;，而关键字规则是 IF : 'if';。输入 ifValue 时，最长匹配原则会让 IDENT 获胜，因为 ifValue 比 if 长，所以 ifValue 会被解析为标识符而非关键字 if + 标识符 Value。这个行为是符合直觉的，但如果你反过来，先把 IF 定义在前面，输入 if 时 IF 会优先匹配，而 ifValue 依然会走 IDENT——因为长度优先大于顺序优先。

在实际设计文法时，关键字词法规则必须定义在标识符规则之前，这个顺序问题值得反复强调。我就是在这上面吃过亏的——第一版脚本语言里，关键字规则写在标识符后面，结果所有关键字都被当成了标识符，程序里到处都是"意外的 token"报错。排查了半个多小时才发现是这个顺序问题。

4. 实操过程：从零写一个可运行的 JSON 解析器

理论说了不少，我们现在进入正题，动手写一个完整的 JSON 解析器。选 JSON 做例子是因为它的语法足够简单，但又覆盖了词法规则、嵌套结构、多类型处理这些典型场景，对初学者来说是一个完整而不过载的实战项目。

4.1 环境准备与项目初始化

首先安装 Antlr 工具，官方推荐的做法是下载完整 jar 包，我用的是通过包管理器安装的方式，以 macOS 为例：

bash复制brew install antlr4

然后确认版本：

bash复制antlr4 -version

我们这次用 Python 运行时做示例，因为 Python 的代码最短，最容易看得清楚全貌。准备依赖：

bash复制pip install antlr4-python3-runtime

我用的是 Antlr 4.13+ 版本，不同小版本的生成代码略有差异，运行时和工具版本尽量保持一致，避免奇怪的二进制兼容问题。

4.2 设计 JSON 文法

一个符合 ECMA-404 标准的 JSON 文法，实际写出来比想象的简单：

antlr复制grammar JSON;

json : value EOF ;

obj : '{' pair (',' pair)* '}' | '{' '}' ;
pair : STRING ':' value ;

array : '[' value (',' value)* ']' | '[' ']' ;

value : STRING
      | NUMBER
      | obj
      | array
      | 'true'
      | 'false'
      | 'null'
      ;

STRING : '"' (ESC | SAFECODEPOINT)* '"' ;
fragment ESC : '\\' (["\\/bfnrt] | UNICODE) ;
fragment UNICODE : 'u' HEX HEX HEX HEX ;
fragment HEX : [0-9a-fA-F] ;
fragment SAFECODEPOINT : ~ ["\\\u0000-\u001F] ;

NUMBER : '-'? INT ('.' [0-9]+)? EXP? ;
fragment INT : '0' | [1-9] [0-9]* ;
fragment EXP : [Ee] [+\-]? INT ;

WS : [ \t\n\r]+ -> skip ;

这里有几个值得注意的设计决策。一是用 fragment 关键字定义不能单独成 token 的片段规则，它们只能被其他词法规则引用，这有助于减少重复书写。二是 value 规则里直接内联了 'true'、'false'、'null' 三个字面量，而不是定义成独立的词法规则，这样语法规则更简洁，解析时字面量 token 会与原生气字符串区分开。

三是 obj 和 array 规则都写了两种可选分支——空对象/空数组的情况特殊处理，而不是让 pair (',' pair)* 这个模式去匹配零次。这是可读性上的取舍，在复杂文法和简洁文法之间的平衡。

4.3 生成解析器并运行

在项目目录下执行：

bash复制antlr4 -Dlanguage=Python3 -visitor JSON.g4

-visitor 参数会额外生成访问器接口。生成的代码里，核心的是 JSONLexer.py、JSONParser.py、JSONVisitor.py。

然后写一个最简单的入口程序，直接打印解析树：

python复制from antlr4 import *
from JSONLexer import JSONLexer
from JSONParser import JSONParser

input_stream = FileStream("test.json")
lexer = JSONLexer(input_stream)
token_stream = CommonTokenStream(lexer)
parser = JSONParser(token_stream)
tree = parser.json()
print(tree.toStringTree(recog=parser))

这一步跑通了，说明你已经具备了解析 JSON 的基础能力。但只有打印树是没用的，我们要能拿到实际的值。

4.4 用 Visitor 把 JSON 文本转换成 Python 对象

这里我直接用 Visitor 模式实现一个转换器：

python复制from JSONParser import JSONParser
from JSONVisitor import JSONVisitor

class JSONConvertVisitor(JSONVisitor):
    def visitJson(self, ctx):
        return self.visit(ctx.value())

    def visitObj(self, ctx):
        obj = {}
        for pair in ctx.pair():
            key = self.visit(pair.STRING())
            obj[key] = self.visit(pair.value())
        return obj

    def visitArray(self, ctx):
        return [self.visit(value) for value in ctx.value()]

    def visitValue(self, ctx):
        if ctx.STRING():
            # 解析转义字符
            raw = ctx.STRING().getText()[1:-1]
            return raw.replace('\\"', '"').replace('\\\\', '\\')
        if ctx.NUMBER():
            text = ctx.NUMBER().getText()
            if '.' in text or 'e' in text or 'E' in text:
                return float(text)
            return int(text)
        if ctx.obj():
            return self.visit(ctx.obj())
        if ctx.array():
            return self.visit(ctx.array())
        if ctx.getText() == 'true':
            return True
        if ctx.getText() == 'false':
            return False
        return None

这里要特别提醒一个细节：在 visitObj 里，我通过 ctx.pair() 拿到所有 pair 节点，再用 assign(pair.STRING()) 的方式取 key 文本，这里的 STRING() 返回的是一个终端节点，getText() 拿到的是带引号的原始文本，所以要去掉首尾引号。转义字符的处理我在 visitValue 里做了个极简版本，生产环境建议用 Python 的 json.loads 去解析字符串值，既安全又省事。

4.5 处理解析错误：覆盖默认错误监听器

一个解析器如果不报告友好的错误，等于没写完。默认情况下，Antlr 的错误信息是英文且偏底层，比如 mismatched input 'x' expecting {NUMBER, STRING, ...}，对终端用户来说不够直观。

更好的做法是实现自定义错误监听器：

python复制from antlr4.error.ErrorListener import ErrorListener

class JSONErrorListener(ErrorListener):
    def syntaxError(self, recognizer, offendingSymbol,
                    line, column, msg, e):
        raise SyntaxError(
            f"第 {line} 行第 {column} 列附近有语法错误: {msg}"
        )

然后在创建解析器后挂上：

python复制parser.removeErrorListeners()
parser.addErrorListener(JSONErrorListener())

你还可以做更细粒度的错误恢复，比如在 obj 规则里遇到缺少冒号的情况时，自动跳过一个 token 继续解析，尝试收集更多错误。Antlr 的默认错误恢复策略是"单 token 删除 + 单 token 插入"，在多数场景这个配置是合理的，尽量不要过度自定义恢复策略，容易出现"错误级联"导致大量误报。我见过有些项目因为自定义错误恢复太激进，在几十万行输入上产生了几百条错误，最后发现只有两个实际错误。

5. Antlr 与其他解析方案、工具的对比

5.1 正则表达式与手写递归下降：什么场景还够用

很多做过一段时间开发的人，遇到"解析格式"需求，第一反应是写正则表达式。正则适合处理"行内的、扁平的、结构固定"的文本，比如提取时间戳、匹配邮箱、抽取 URL。可一旦文本有嵌套结构，比如 if 语句里套 for 循环，正则就会迅速失控。经典的说法是"正则不能解析任意深度嵌套结构"，这背后是形式语言理论的分层：正则表达式对应正则语言，而嵌套结构需要上下文无关语言，这在计算能力上是不可逾越的层级差距。

手写递归下降解析器是一种可行的替代方案，很多老牌语言就是这么实现的。它的好处是没有额外依赖、性能可控、出错逻辑完全由你掌控，坏处是代码量的提升非常明显，一个中等复杂度的表达式语言，手写解析器轻松就到上千行。而且这些代码还不直观，后面维护的人要理解你的递归思路需要花时间。如果你的目标是"做一个能用的语言工具"而不是"体验手写解析器的过程"，Antlr 是性价比更高的选择。

5.2 与 Yacc/Bison、JavaCC 的对照

Yacc/Bison 是经典的 LALR 解析器生成器，在 Unix 世界治理了几十年。它有强大的表驱动解析能力，解析效率高，但有一个学习曲线陡峭的问题：冲突处理需要你理解 LALR 文法的细节，很多新手会在 shift/reduce 冲突上卡住，被迫去改写文法或者添加优先级声明。

JavaCC 是 Java 生态里的老牌工具，语法接近 LL(k)，但 3.x 时代一直没有解决左递归问题，你要手写消除左递归，对直觉不友好。

Antlr 相对它们的主要优势：

需要澄清的是，这个表格不是说 Antlr 全面碾压其他工具，而是强调在现代语言工具开发场景下，Antlr 的"开发效率"和"可维护性"优势更突出。Yacc/Bison 在处理巨型文法时的性能表现仍然一流，很多编译器后端仍在使用；JavaCC 在代码生成策略上更贴近 Java 开发者的传统习惯。选择工具要结合你的目标和团队背景。

5.3 什么时候不要用 Antlr

这个判断值得单列一节。Antlr 虽然强大，但不是银弹。如果你只需要解析一个固定格式的报文头，比如长度字段加若干字节数据，手写代码比引入一个运行时依赖简单得多。

如果输入量极大，对性能要求极度苛刻（比如企业级查询引擎要处理每秒几十万次请求），Antlr 的自适应预测会有额外开销，这时手写预测效率更高，甚至可以考虑手写增量解析器。我见过有团队为了实现一套大数据场景下的查询 DSL，最终选择了手写解析器，因为性能指标卡得很死。

另外，如果你的团队里没人有语法分析基础，也没有意愿学，只想快速"用一把"，那我建议你慎重评估。Antlr 的文法文件看着简单，真正写复杂文法时，理解递归、理解歧义、理解消解规则仍然需要投入时间。

6. 实战经验：复杂文法设计中的关键取舍与避坑

6.1 优先级设计的惯例

表达式优先级是文法设计里最容易出问题的地方。一种直观但错误的方式是：

antlr复制expr : expr '+' expr | expr '*' expr | INT ;

这段文法在理论上存在严重的二义性，输入 1 + 2 * 3 会产生多棵解析树，Antlr 会警告"decision can match input such as ... using multiple alternatives"，然后选择与决策顺序相关的某个结果，可能不是你要的那个。

正确做法是用分层的方式表达优先级：

antlr复制expr : addExpr ;
addExpr : mulExpr ('+' mulExpr)* ;
mulExpr : primary ('*' primary)* ;
primary : INT | '(' expr ')' ;

这种结构的力量在于：它把一个二维的优先级关系拆成了单维的嵌套层级，优先级最高的表达式在树里位置越深，最终生成的 AST 天然呈现"乘法先于加法"的结构。类似地，比较运算、逻辑运算、一元运算都可以逐层加进去。

6.2 二义性与 Antlr 的歧义消解策略

即使你已经尽量用分层表达优先级，文法仍然可能出现二义性。一个典型例子是 if-else 的悬挂问题：

antlr复制stmt : 'if' '(' expr ')' stmt ('else' stmt)? ;

输入 if (a) if (b) c++; else d++; 时，else 应该和哪个 if 配对？C 语言的惯例是就近配对。Antlr 处理二义性时，默认情况下预测决策会按照分支顺序选择先匹配的那个分支。在这个例子里，把 else 分支作为可选项放在内层，Antlr 会选择最近的那个 if 进行配对。如果你的规则写的顺序不同，结果可能变成就近配对的实现不同——所以遇到不确定行为时，先看警告，再手动调整分支顺序或者用语法谓词（predicate）约束。

6.3 语义谓词：什么时候用、什么时候避开

语义谓词是 { ... }? 这种写法，用来在匹配过程中检查运行时条件。举一个实际场景：有些 DSL 要求 foo 和 foo_bar 不能同时出现，你需要回溯前面的上下文。用语义谓词可以做到，但它会让文法变得难以预测，也影响解析性能。

我的经验是：能通过文法结构解决的，不写谓词；必须写谓词时，把谓词的作用范围控制在符 token 级别，尽量不做跨规则的全局状态依赖。因为谓词本质上是"运行时后门"，一旦使用，文法文件的可测试性就下降了。

6.4 大文法的模块化管理：拆分与组合

当你做一个完整的编程语言时，文法文件很容易超过 1000 行。这时候应该拆分：

• 一个 Lexer.g4 专门放词法规则
• 基础表达式放 Expression.g4
• 语句、模块结构放单独文件
• 用 import 指令引用它们

Antlr 的 import 机制与编程语言不同，它会把所有 import 的规则和自家规则合并到一个语法空间，同名规则会产生处理规则，规则名的冲突容易产生微妙问题。我倾向于把"词法规则"和"语法规则"分开文件，很少用多层 import 嵌套。

6.5 性能调优：实测数据与经验数值

Antlr 4 的解析性能受几个因素影响：

• 词法规则是否容易产生长回溯。比如大量使用"排除集合"的规则可能让词法分析器在错误匹配时走很长一段距离才发现问题。实测中典型的 JSON 解析器吞吐量在每秒几十万 token 级别，对绝大多数业务场景绰绰有余。
• 语法规则的歧义程度。歧义越高，自适应预测的决策树就越复杂。如果你发现解析器在某个特定输入上卡顿严重，优先检查文法的歧义。
• 是否使用了语义谓词。谓词会打断预测缓存，每次决策都可能重新执行谓词代码，开销不能忽略。
• 是否生成了无损的 token 流。如果不需要 token 级信息，可以使用 channel 特性把某些 token 丢弃到隐藏通道。

我实测过一个包含复杂表达式的查询 DSL，初始版本解析 1000 条语句耗时约 40ms，优化文法、减少可选项、删除无用词法规则后，降到 8ms。这里的优化没有改算法，只是让文法更"确定"。

6.6 测试策略：快照测试与模糊测试的配合

Antlr 生成解析器后，最重要的测试手段有两类：一类是基于 golden file 的解析树快照测试，把解析树的文本输出存成基线，修改文法后对比差异，这是最省心也最有效的回归测试；另一类是模糊测试，用随机生成的输入去喂解析器，观察崩溃和超时，可以用 Python 的 hypothesis 或者直接写一个随机字符串生成器。

我特别推荐把"反例测试"也纳入常规测试流程——不仅测合法输入，还要测非法输入，验证错误恢复逻辑不会产生无限循环。Antlr 在部分错误恢复场景下可能出现"跳过一个 token 后继续解析，又因为相同的错误跳过一个 token"的死循环，虽然罕见，但一旦出现，线上问题就是灾难。

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

7.1 词法规则优先级导致的"莫名失败"

症状：规则的语法没有问题，但某些输入永远解析不了，或者某个关键字永远匹配不到。

排查思路：先用 grun 打印 token 流，确认 token 类型是否符合预期。然后回到 .g4 文件里检查词法规则的顺序和 fragment 的使用。我遇到的最经典案例是：定义了一个 ID 规则，然后又定义了一个 MULTILINE_COMMENT 规则，前者的排除集合 ~[] 没有排除注释字符，导致注释被吞成 ID 的一部分。

7.2 隐式 token 定义的问题

在语法规则里直接写字符串字面量，比如 value : 'true' | 'false' ;，Antlr 会自动生成无名的 token 类型。这在简单场景下没什么问题，但如果同一个字符串字面量在不同位置出现，且你想统一控制它的 token 类型（比如设置优先级、加入 channel），就建议显式定义词法规则。

我踩过一次的坑是：在语法规则里写了 op : '+' | '-' ;，后来想对 - 做特殊语义处理，结果发现隐式 token 名称是 T__1 这种难以识别的名字，调试时非常痛苦。显式声明成 PLUS : '+'; MINUS : '-'; 之后，代码可读性和可维护性一下子提高了。

7.3 解析树节点"太多/太少"的困惑

新人常问：为什么我的解析树里，visitValue 没被调用？或者调用了很多次，但打印的参数不对？

这个问题的根源是对 ctx.value() 这种属性访问方法的理解偏差。ctx.value() 返回的是一个上下文对象列表，不是文本；要拿文本需要遍历并调用 .getText()。如果你写的是 self.visit(ctx.value())，传入的参数是整个列表，Visitor 就会找不到对应的 visit 方法，此时会走默认的 visitChildren 或者报错。

建议：第一次写 Visitor 时，先在每个方法里打印 ctx.getText() 与 ctx 的类型，把整个解析树结构摸清楚再写逻辑。磨刀不误砍柴工。

7.4 版本不匹配导致的运行时错误

Antlr 工具生成的代码版本和运行时库版本不一致，会出现 NoSuchMethodError 或者 AttributeError 这类问题。

解决思路：锁定版本。在 requirements.txt 里写明 antlr4-python3-runtime==4.13.1，同时确保你调用的 antlr4 命令对应同一个版本。如果你用 IDE 插件的时候，插件内嵌的 Antlr 版本可能是旧的，最好用命令行单独生成一次。

7.5 调试解析树的利器：grun 与图形化输出

内置的 grun 工具拯救了无数个调试之夜。用它可以先看 token 序列，再看解析树结构，还能以图形格式导出：

bash复制antlr4 -Dlanguage=Java JSON.g4
javac JSON*.java
grun JSON json -tree test.json

如果想看到图形化的树，用 -gui 参数。第一次看到图形化的解析树时，那种"原来程序是这么理解我的输入的"感觉，比读多少篇文章都直观。

8. 在实际工程中的扩展应用

8.1 从 DSL 到配置系统

Antlr 在 DSL 领域是事实标准级别的工具。我曾用它在公司内部搭建过一个"报表计算 DSL"，业务人员能够用类似 Excel 公式的语法定义指标计算逻辑，后端解析成执行计划。相比以前运维团队人工写 SQL，这个 DSL 大幅降低了沟通成本和出错概率。

关键点在于：Antlr 解析只是第一步，真正有价值的是解析后的 AST 设计与执行引擎的对接。AST 节点的设计要尽量脱离 Contexte 对象的约束，把解析层和后端执行层解耦。我在实践中用一个简单的中间表示（IR）来存放 AST 信息，整棵树的节点就是普通的 Python 类，不依赖 Antlr 的任何结构，这样后端可以自由演进。

8.2 代码生成与格式化工具

代码生成场景里，Antlr 的目标通常是：将某种 DSL 转换为主流语言代码。比如我写过一个将内部 API 定义文件转换成 Java、Python、TypeScript 三种客户端代码的工具。这里的核心流程是解析输入、构建 AST、遍历 AST 生成输出，整个过程完全可以由 Antlr 的语法规则和 Visitor 机制承载。

另外一类有趣的应用是代码格式化。用 Antlr 对源码做完整解析，然后重新打印 token 序列，并加上统一的缩进和换行规则。做这件事的难点不在于格式逻辑，而在于要保留注释和空行的位置——它们往往被词法规则跳过或者放到隐藏通道了。解决方案是把注释保留到 <EOF> 之前的隐藏通道里，在打印时按位置重新注入。

8.3 透明SQL校验与安全审计

很多企业内部系统都要接收用户输入的 SQL 片段，直接拿去执行有安全风险。用 Antlr 做一次语法级校验和黑名单检查是一个稳健的方案。你可以解析 SQL，遍历 AST 找出不允许出现的表名、字段名或者危险语句模式，在进入数据库之前就拦截下来。

这种思路的优势是：规则可以持续补充，而且完全基于语法结构，不容易被正则绕过。对安全要求高的系统，解析层拦截是整个链路里非常可靠的一道防线。

9. 踩坑清单与最后的经验分享

9.1 我的快速参考速查表

9.2 个人心路与建议

Antlr 学习过程中的最大难点其实不在于工具本身，而在于从"字符思考模式"切换到"语法树思考模式"。刚开始你会不自觉地想写正则去处理所有事情，一旦适应了"先定义规则、再遍历树"的思维方式，你就打开了一扇大门：你会开始用语法分析的视角看待配置文件、模板语言、日志格式，甚至你日常开发时的代码结构。

如果你想系统深入学习，我的建议是两本书配合文档：一本是 The Definitive ANTLR 4 Reference，作者就是 Antlr 的作者 Parr 本人，案例丰富务实；另一本是编译原理经典教材龙书，用来补齐形式语言与自动机的基础知识。遇到具体函数不会写，直接查官方文档和 GitHub 上的示例代码，比搜博客效率高很多。

9.3 送给读者的一句话式总结

Antlr 最厉害的地方不是帮你写了一个解析器，而是它逼着你去思考"这门语言到底是什么样的结构"。这份思考能力，比任何具体工具都值钱。如果你正被某个复杂的文本解析问题困扰，花一个周末把 Antlr 4 装起来，写一个像上面那样的 JSON 解析器，让解析树在眼前动起来——这个体验会改变你之后写代码的方式。