企业官网建设流程全解析

uBlock Origin 的本地 JSONPath 工具怎么启动并验证 uBO 语法表达式

【免费下载链接】uBlockuBlock Origin - An efficient blocker for Chromium and Firefox. Fast and lean.项目地址: https://gitcode.com/GitHub_Trending/ub/uBlock

如果你在编写或调试 uBlock Origin 的过滤器，需要用到 uBO 风格的 JSONPath 查询表达式（例如用于json:/jsonl:替换类型的过滤器），又不想为每次改动都完整构建扩展，可以直接使用仓库自带的本地调试工具 tools/jsonpath-tool.html。这个页面标题就是 "uBO-flavored JSONPath tool"，它直接加载仓库源码 src/js/jsonpath.js 中的JSONPath类，让你在浏览器里对样本数据实时编译、求值一个表达式，并查看表达式非法、求值结果、以及赋值/删除操作对 JSON 的作用效果。本文给出启动该工具的完整步骤和验证方法。

工具包含什么

tools/jsonpath-tool.html 页面提供以下能力，全部来自页面自身的实现：

• 一个预填的表达式输入框（占位提示为 "JSON path expression"），默认值是$..book[?@.price<10]；
• 一份内置的示例 JSON 数据（store.book数组加一个bicycle对象），可以在左侧编辑区直接修改，粘贴内容会被自动格式化；
• 输入表达式后自动重新计算（页面在input事件上触发process()），结果区显示求值（evaluate）得到的路径列表，右侧合并视图显示apply()之后的 JSON——即表达式带=[value]赋值时各节点被写入的值，不带赋值时各节点被删除后的结构；
• 表达式非法时，结果区显示bad expression。

启动前准备

1. 在 uBlock 仓库根目录下启动本地静态服务器。页面文件头部注释明确写了运行方式：

   python3 -m http.server

   服务器必须运行在仓库根目录（因为页面以 ES module 方式导入../src/js/jsonpath.js），之后在浏览器中打开：

   http://localhost:8000/tools/jsonpath-tool.html

2. 确认 codemirror-ubol 子模块已检出。页面通过<script src="../platform/mv3/extension/lib/codemirror/codemirror-ubol/dist/cm6.bundle.ubol.min.js">加载编辑器 bundle，而 ​.gitmodules 显示该路径是一个 git submodule。如果克隆仓库时没有初始化子模块，这个 bundle 文件缺失，页面脚本无法运行。执行以下命令补全（仅把子模块仓库拉取到本地对应目录，不修改仓库其他内容）：

   git submodule update --init

   Makefile 中对该文件的引用（platform/mv3/extension/lib/codemirror/codemirror-ubol/dist/cm6.bundle.ubol.min.js）也印证了这个 bundle 的依赖位置。

用默认表达式验证页面是否工作

打开页面后立即执行一次默认计算（页面加载结束时会调用一次process()）。默认表达式$..book[?@.price<10]作用于内置的 store 数据。根据仓库中 tools/jsonpath-tests.js 记录的同一份数据（文档示例，供比对，不是必须完全一致的终端输出），price 小于 10 的条目是store.book[0]（price 8.95）和store.book[2]（price 8.99），即结果区应列出这两条路径。看到路径列表而非bad expression，说明本地服务、模块导入和JSONPath引擎都已正常工作。

验证你自己的 uBO 风格表达式

在输入框中键入表达式即可，每改一次都会自动重新计算。判断下一步的依据是结果区的状态：

• 出现路径列表：表达式合法且匹配到节点；
• 出现bad expression：表达式没通过jsonp.compile()的合法性检查（对应 src/js/jsonpath.js 中valid属性为 false）；
• 表达式合法但没有匹配节点时，结果为空。

带赋值后缀的表达式会同时触发第二块视图。src/js/jsonpath.js 文件头注释给出了文档化的示例与规则：

• 赋值示例：.store..price=0、.store.book[*].author="redacted"（追加=[value]后，apply()会把各解析到的节点写为该 JSON 值，右侧视图显示写入后的 JSON）；
• 不带赋值的查询，apply()会把解析到的属性删除，右侧视图显示删除后的结构；
• 被赋值的操作数必须是合法 JSON。

uBO 风格与标准 JSONPath 的差异也记录在同一文件头注释中，验证表达式时应以这些规则为准：

• 不支持数组切片（array slice）操作符；
• 选择器可以是/分隔的正则，如$./pattern/；
• 过滤选择器只支持单个，且运算符限定为==、!=、<、<=、>、>=、^=（字符串化后开头匹配）、$=（结尾匹配）、*=（包含）、=/.../（正则匹配）；
• 另支持=repl(...)与=call(...)两种赋值操作。

文件头注释还列出了一批可直接试用的查询示例（引自 RFC 9535 的 JSONPath examples）：.store.book[*].author、..author、.store.*、.store..price、..book[2]、..book[?(.isbn)]、..book[?(.price<10)]、..*。

用 rfc9535 一致性页面交叉核对引擎行为

同一服务器下还有一个配套页面 tools/jsonpath-tests.html，地址为http://localhost:8000/tools/jsonpath-tests.html。tools/jsonpath-tests.js 会用v2:前缀编译一组 rfc9535 语法查询（v2 是 src/js/jsonpath.js 中识别的官方语法分支），把每条查询的期望结果与实际结果并排渲染在页面上，不一致的条目以红色高亮（.fail样式）。当你怀疑本地src/js/jsonpath.js的行为有异常，或者想确认标准 JSONPath 语义（负索引、切片、通配符、null 处理等）在本地副本上是否符合预期时，打开这个页面即可，无需任何额外操作。注意它验证的是v2:前缀的标准语法路径，与主工具默认的 uBO 风格语法不是同一条分支。

与过滤器的关系

这个本地工具验证的正是过滤器解析时所用的同一套引擎：src/js/static-filtering-parser.js 中的parseReplaceValue()在遇到json:/jsonl:类型的替换值时，调用JSONPath.create(query)编译查询，若jsonp.valid === false则该过滤器解析失败。因此，把准备写进过滤器的表达式先在本地工具中确认能编译、且对目标数据结构求值出预期路径，是上线前最低成本的验证手段。

局限

• 本地工具只在浏览器 + 本地服务器环境下运行，不能脱离仓库目录独立使用；
• 它只暴露compile()/evaluate()/apply()三个入口的行为，=repl(...)、=call(...)等高级赋值操作的文档在源码注释中仍标注 "to be documented"，使用时以 src/js/jsonpath.js 的实现为准；
• 页面默认示例数据是 store/book 结构，要针对自己的过滤目标验证时，需在左侧编辑区粘贴自己的 JSON（合法对象或数组），否则解析失败会按空对象处理。

【免费下载链接】uBlockuBlock Origin - An efficient blocker for Chromium and Firefox. Fast and lean.项目地址: https://gitcode.com/GitHub_Trending/ub/uBlock