如何用OCaml实现一个JSON查询语言？query-json架构解析：从词法分析到解释执行

如何用OCaml实现一个JSON查询语言？query-json架构解析：从词法分析到解释执行

【免费下载链接】query-jsonFaster, simpler and more portable implementation of jq-inspired language in OCaml项目地址: https://gitcode.com/gh_mirrors/qu/query-json

query-json是用 OCaml 实现的一款快速、简洁且可移植的JSON 查询语言，可以理解为「更快更好用的 jq」：它把一条 JSON 查询语句经过词法分析 → 语法解析 → 抽象语法树（AST）→ 解释执行四个阶段，最终输出查询结果。本文面向新手，不堆砌代码，带你完整拆解这套 JSON 查询引擎的架构设计。

🗂️ 总体架构：一条查询的旅程

当你输入query-json '.store.books[0].title' bookstore.json时，项目内部的Core.ml模块会编排一次完整流水线：

整条链路非常清晰：文本 → token → AST → 执行结果，这也是所有脚本语言（如 jq、grep 方言）的标准做法。

🔤 词法分析：把文本切成"单词"

词法器source/Lexer.ml基于 OCaml 的sedlex库编写，它把查询字符串逐个字符扫描，产出带类型的 token。核心 token 类型定义在source/Lexer.mli中，大致分为几类：

• 字面量：INT、STRING、BOOL、NULL
• 标识符：IDENTIFIER（键名）、FUNCTION（函数名）、VARIABLE（$var）
• 运算符：PIPE（管道|）、DOT（.）、ALTERNATIVE（??）
• 关键字：IF、THEN、ELSE、FN、TRY、CATCH等控制流词

值得一提的是，token 类型里对数字做了精细区分：INT、INT64、BIG_INT（大整数）三种，这让 JSON 查询能无损处理超大整数，避免精度丢失。

词法器还有一个巧妙设计——字符串插值：模板字符串会被切成INTERP（插值片段）和TEMPLATEtoken，支持在查询中动态拼接表达式。

🌳 语法分析：构建抽象语法树

source/Parser.mli只暴露一个入口函数program，它消费 token 流，产出Ast.expression。AST 的定义全部在source/Ast.ml中，值得关注的几组结构：

• 表达式：Identity（.）、Pipe（管道）、Operation（二元运算）、If_then_else、Try（异常处理）
• 访问模式：Key（.foo）、Index（.[1]）、Slice（.[0:3]）、Dynamic_access（.[$expr]动态取键）
• 函数节点：Fn0/Fn1/Fn2分别对应 0 参、1 参、2 参函数——这是整个语言函数体系的骨架
• 构造函数：List（数组字面量）、Object（对象字面量）

这种"函数按参数个数分型"的做法，让类型检查器可以提前约束每个函数能接几个参数，是比纯字符串匹配更稳健的设计。

📚 函数库：200+ 内置函数的注册中心

source/Language.ml是内置函数的"注册中心"。它为每个函数记录元信息：函数名、别名（兼容 jq 旧名）、描述、示例、适用类型（字符串/数组/对象…）和参数个数。这套元数据被多处复用：

• CLI 的query-json --functions分类列出全部函数
• REPL 的自动补全提示
• 解析期的参数数量校验与报错

语言层面它做了一次"现代化改造"：全部函数统一snake_case命名（如to_uppercase取代 jq 的ascii_upcase），null 访问默认报错而非静默传播，需要宽松行为时显式写.foo?。完整对照见 docs/JQ_COMPATIBILITY.md 文档。

⚙️ 解释执行：树遍历求值

source/Interpreter.ml是引擎心脏。它采用经典的树遍历解释器：execute函数接收 AST 与 JSON 数据，递归地对每个表达式节点求值，最终返回Ok of Json.t list | Error of string | Halt of int三种结果——查询可能产出多个结果、失败、或以状态码中止。

解释器直接操作source/jotason/中的 JSON 值类型，省去了中间转换开销。jotason 模块内置了Json.ml（值模型）、Read.mll（手写词法器读取 JSON）、Write.ml（美化输出），是整个项目里性能优化最集中的地方。

🎯 错误系统：告诉你"为什么错、怎么改"

source/Error.ml让报错信息带上源代码位置。相比 jq 直接输出null，query-json 会指出哪个 token 出了问题、给出可用键名、甚至附上修复建议：

这类"可操作的错误信息"对新手极其友好，也说明错误处理被当作核心功能而非附属品来设计。

🖥️ 一份代码，三端运行

OCaml 的多后端能力是 query-json 最大的架构红利：

• 原生二进制：编译为 macOS / Linux / Windows 可执行文件，基准测试显示比 jq 快 2~4 倍
• 浏览器：通过 js 编译目标输出 JavaScript，驱动在线 playground（website/目录）
• Node.js 库：js/Js.ml提供 JS 绑定，可npm install使用

交互式 REPL 支持上下文感知补全：输入.提示键名，输入|提示函数：

更高级的过滤、分组、聚合用法可以参考cli/test/下的集成测试脚本，它们就是可执行的查询用例集：

📌 小结

query-json 展示了一个教科书级的查询语言实现路径：

1. sedlex 词法分析→ token 流（数字类型精细分级）
2. 递归下降解析→ 类型化的 AST（函数按元数分型）
3. 元数据驱动的函数库→ 解析校验、补全、文档同源
4. 树遍历解释器→ 直接操作 JSON 值，零中间层
5. 位置感知的错误系统→ 新手友好的排错体验
6. OCaml 多后端→ 一份源码覆盖 CLI / 浏览器 / Node.js

如果你想动手研究，可以从source/Core.ml的parse与run两个函数读起——50 行代码内就能看懂整条流水线的全貌。

【免费下载链接】query-jsonFaster, simpler and more portable implementation of jq-inspired language in OCaml项目地址: https://gitcode.com/gh_mirrors/qu/query-json