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，因为只是收集字段信息，