本文详解在 Ubuntu 环境下使用 Antlr4 正确生成 PL/SQL Python 解析器的完整流程，重点解决因误下载 GitHub HTML 页面导致的 error(50) 语法错误，并提供可复现的命令序列、关键注意事项及验证方法。
本文详解在 ubuntu 环境下使用 antlr4 正确生成 pl/sql python 解析器的完整流程，重点解决因误下载 github html 页面导致的 `error(50)` 语法错误，并提供可复现的命令序列、关键注意事项及验证方法。
Antlr4 是构建自定义语言解析器的强大工具，而 Oracle PL/SQL 语法复杂，其官方语法支持依赖社区维护的 grammars-v4 项目。许多开发者在首次尝试时会遇到类似 error(50): ... 'payload': {...} came as a complete surprise 的报错——这并非语法问题，而是误将 GitHub 的 HTML 页面源码当作 .g4 文件下载所致。GitHub 上以 https://github.com/.../blob/... 结尾的链接默认返回渲染后的 HTML，而非原始文本文件；直接 wget 该 URL 将下载一个包含 JSON 元数据和网页结构的 HTML 文档，Antlr4 解析器自然无法识别，从而抛出令人困惑的 syntax error。
✅ 正确做法是：始终使用原始文件（Raw）URL 下载 .g4 和 .py 基类文件。GitHub 提供了「Raw」按钮（位于文件浏览页右上角），点击后浏览器地址栏会变为 https://raw.githubusercontent.com/... 格式，这才是纯文本资源的真实地址。
以下是在 Ubuntu 22.04 上可稳定执行的完整步骤（无需额外 Python 包，避免 antlr-plsql 等非官方封装引入兼容性风险）：
1. 准备环境
# 创建工作目录
mkdir -p plsql-parser/{lib,grammars,src}
cd plsql-parser
# 下载 Antlr4 运行时（推荐 4.9.3，与 grammar-v4 兼容性最佳）
curl -o lib/antlr-4.9.3-complete.jar https://www.antlr.org/download/antlr-4.9.3-complete.jar
# 设置 CLASSPATH（后续 Java 命令需引用）
export CLASSPATH="$PWD/lib/antlr-4.9.3-complete.jar:$CLASSPATH"2. 下载正确的语法文件（关键！）
⚠️ 务必使用 raw.githubusercontent.com 链接：
cd grammars # 下载原始 .g4 文件（注意：URL 中 blob → raw，且域名变更） wget https://raw.githubusercontent.com/antlr/grammars-v4/master/sql/plsql/PlSqlLexer.g4 wget https://raw.githubusercontent.com/antlr/grammars-v4/master/sql/plsql/PlSqlParser.g4 # 下载 Python 基类（非必需但推荐，用于自定义错误处理/遍历逻辑） cd .. wget https://raw.githubusercontent.com/antlr/grammars-v4/master/sql/plsql/Python3/PlSqlLexerBase.py wget https://raw.githubusercontent.com/antlr/grammars-v4/master/sql/plsql/Python3/PlSqlParserBase.py
3. 生成 Python 解析器代码
# 在项目根目录执行（确保当前路径含 grammars/ 子目录） java org.antlr.v4.Tool -Dlanguage=Python3 -o ./src grammars/*.g4
✅ 成功输出示例：PlSqlLexer.py, PlSqlParser.py, PlSqlLexer.tokens, PlSqlParser.tokens 等文件将生成在 src/ 目录下。若仍报错，请检查 grammars/ 内是否混入了 HTML 文件（可用 file PlSql*.g4 验证是否为 ASCII text）。
4. 验证生成结果（可选）
创建简易测试脚本 test_parse.py：
from antlr4 import *
from src.PlSqlLexer import PlSqlLexer
from src.PlSqlParser import PlSqlParser
def parse_sql(text):
input_stream = InputStream(text)
lexer = PlSqlLexer(input_stream)
token_stream = CommonTokenStream(lexer)
parser = PlSqlParser(token_stream)
tree = parser.sql_script() # 根规则名，依据 grammar 调整
print(tree.toStringTree(recog=parser))
if __name__ == '__main__':
parse_sql("BEGIN NULL; END;")运行前安装运行时：
pip install antlr4-python3-runtime==4.9.3 python test_parse.py
⚠️ 重要注意事项
- 不要用 apt install python3-antlr4 或 pip install antlr-plsql：前者版本陈旧（通常为 4.7），后者非官方维护，易与 grammar-v4 不匹配；
- 避免混合使用不同 Antlr4 版本：.g4 文件由 4.9.3 生成，则运行时必须严格使用 antlr4-python3-runtime==4.9.3；
- PlSqlLexerBase.py/PlSqlParserBase.py 是可选增强：它们提供预定义的异常处理和上下文管理，不生成也能解析，但建议保留以提升健壮性；
- 若需支持 PL/SQL 块（如 DECLARE ... BEGIN ... END;），请确认调用的是 parser.sql_script() 或 parser.plsql_unit() 等顶层规则（参考 PlSqlParser.g4 中的 grammar PlSqlParser; 后的 @header 和起始规则定义）。
通过以上标准化流程，你将获得一套可稳定工作的 PL/SQL Python 解析器，为 SQL 静态分析、代码格式化、权限扫描等场景奠定坚实基础。
