§

测试 JSONPath 表达式

输出格式:
JSONPath 快速参考
Token Meaning
$文档的根元素
@当前元素（用于过滤表达式内部）
.子成员运算符：选择命名的子节点
..递归下降：搜索所有后代
*通配符：匹配任意元素或属性
[*]数组的所有项
[n]索引为 n 的数组元素（从零开始）
[start:end]从 start 到 end（不含）的数组切片
[?(@.x)]过滤：属性 x 存在的项
[?(@.x==1)]过滤：属性 x 等于 1 的项
[(@.length-1)]脚本表达式：数组的最后一个元素

JSONPath 常见于需要针对真实载荷检验 API 契约的场景。国内后端团队在 Postman 回归测试套件的 Tests 标签页中用 JSONPath 断言响应字段，k6 压测脚本使用 jsonpath() 从 API 响应中提取值以在 check() 块内把守 SLA 阈值，运维值班手册借助 [?(@.status=="error")] 等过滤表达式切片 JSON 日志。在浏览器标签页中运行这些表达式，可使专有载荷、用户 PII 和预发布 API 响应不必上传到任何托管查询服务。

// 相关工具

./json-formatter
JSON 格式化工具
在浏览器中格式化、验证并压缩 JSON。
→
./json-minifier
JSON 压缩器
在浏览器中压缩 JSON 并报告节省的字节数。
→
./json-to-typescript
JSON 转 TypeScript
从 JSON 样本生成 TypeScript 接口。
→
./
全部工具
浏览 Ultim8Soft 在线工具的完整合集。
→

什么是 JSONPath？

JSONPath 是一种用于 JSON 文档的查询语言，是 JSON 版本的 XML XPath。Stefan Goessner 于 2007 年提出它，作为一种简短易读的方式，无需编写解析器即可指向 JSON 树中的节点。表达式以根选择器 $ 开头，链接属性访问器、数组下标、通配符、递归下降和过滤条件，直到选出所需节点。2024 年，IETF 发布了 RFC 9535 以规范化此前各实现中分化的语法；本测试器基于 jsonpath-plus 运行，这是一个广泛使用的 JavaScript 实现，涵盖了 Goessner 草案、RFC 9535 的大部分内容，以及若干扩展运算符。

JSONPath 的工作原理

JSONPath 表达式从左到右读取，逐步遍历 JSON 文档。每一步以上一步存活的节点集合为输入，进一步缩小范围。完整的求值流程：

  1. 用根选择器 $ 定锚。每个表达式都从这里开始，指向顶层值，无论是对象还是数组。没有前导 $ 的裸属性名不是合法的 JSONPath。
  2. 用点号表示法（$.store.book）或括号表示法（$['store']['book']）进入子成员。当键包含空格、连字符或任何不是合法标识符的字符时，必须使用括号表示法。
  3. 用递归下降运算符 .. 一次搜索所有层级。表达式 $..author 收集树中任意深度的所有 author 值。这是 JMESPath 所没有的运算符。
  4. 按索引（[0]，在 jsonpath-plus 中 [-1] 表示最后一项）选取数组元素，用 [start:end] 表示法切片（[0:3] 返回前三项），或用通配符 [*] 获取所有元素。
  5. 用 [?(...)] 内的谓词过滤元素。谓词内 @ 指当前元素，因此 [?(@.price<10)] 只保留 price 字段小于 10 的项。过滤器可与路径的其余部分组合，先过滤再下降，或先下降再过滤均可。
  6. 选择输出格式。值返回匹配到的数据本身。路径返回每个匹配的 JSONPath，便于查看引擎解析的结果。指针为每个匹配返回等价的 RFC 6901 JSON 指针，在下游消费者是 JSON Patch 或 JSON Schema 验证器时非常有用。

为什么使用此 JSONPath 测试器？

  • 您的 JSON 不会离开浏览器。查询在页面内运行，生产数据、用户 PII 和预发布 API 响应都留在您的设备上。
  • 引擎是 jsonpath-plus 9.x，与许多生产测试套件和 CI 断言所用的是同一个库。您在这里看到的结果与您的构建流水线所见的结果一致。
  • 三种输出模式覆盖常见的下游消费场景：用于复制粘贴的原始值、用于调试引擎解析的路径，以及用于 JSON Patch 和 JSON Schema 工作流的 RFC 6901 指针。
  • 过滤表达式以 preventEval: true 运行，因此粘贴的查询不能对宿主页面执行任意 JavaScript。这在表达式来自 Slack 消息、Jira 工单或同事剪贴板时尤为重要。

JSONPath 的常见应用场景

JSONPath 广泛出现在需要从 JSON 载荷中提取字段而无需手写递归下降的场景中：

  • Postman 测试：Postman 的 Tests 标签页提供 pm.response.json() 以及 JSONPath 风格的访问方式用于断言。团队编写一个表达式如 $.data.user.email，从响应中提取字段并在 CI 中进行断言。
  • k6 压测：k6 脚本在 check() 块内调用 jsonpath() 从响应体中提取值并断言 SLA 阈值。在 Postman 中验证过契约的同一表达式，可直接用于 k6 压测中的门控。
  • JSON DSL 数据转换：AWS Step Functions 在 InputPath、ResultPath 和 Parameters 中使用 JSONPath 对状态间的事件载荷进行整形。Argo Workflows 在 withParam 中使用 JSONPath 对数组进行任务扇出。Kubernetes 的 kubectl -o jsonpath 使用相同语法从集群对象中提取字段。

实际示例

Goessner 的经典样例是一个包含四本书的书店文档，每本书有 category、author、title 和 price 字段。针对该样例，表达式 $.store.book[?(@.price<10)].title 分三步运行。首先，$.store.book 解析为所有四本书的数组。接着，过滤器 [?(@.price<10)] 只保留定价低于 10 的那本书（8.95 的那本）。最后，.title 提取该书的标题。结果为 ["Sayings of the Century"]。切换到路径模式返回 ["$['store']['book'][0]['title']"]，指针模式返回 ["/store/book/0/title"]。

在这里原型化您的表达式，然后直接放入 Postman、k6、kubectl 或 Step Functions 状态机中。粘贴、查询、复制。任何内容都不经过网络传输。

什么是 JSONPath？

JSONPath 是一种用于 JSON 文档的查询语言，类似于 XML 的 XPath。由 Stefan Goessner 于 2007 年提出，并于 2024 年由 IETF 标准化为 RFC 9535，它使用以 $（文档根）开头的紧凑表达式语法，支持点号表示法、数组下标、通配符、切片、递归下降（..）和过滤表达式（[?(...)]），以在 JSON 树中选取节点。

JSONPath 与 JMESPath 或 jq 有何不同？

三者都查询 JSON，但语法和目标各异。JMESPath 是 AWS CLI/SDK 标准：比 JSONPath 更严格，不支持递归下降，为可预测的无副作用投影而设计。jq 是一门图灵完备的脚本语言，不仅能查询 JSON，还能转换、归约和流式处理。JSONPath 介于两者之间：比 JMESPath 表达能力更强（得益于递归下降和过滤器），比 jq 更轻量，且在通用测试工具（Postman、Playwright、REST Assured、kubectl、Step Functions）中支持最广泛。本测试器实现的是 JSONPath。

本测试器使用哪种方言？

本测试器运行 jsonpath-plus 9.x。该库实现了 Goessner 2007 规范，涵盖 RFC 9535 的大部分内容，并添加了类型检查（@.string()、@.number()、@.boolean()）和父节点导航（^）等扩展运算符。始终设置 preventEval: true，因此过滤谓词通过安全解释器而非 JavaScript 的 eval() 内置函数运行。粘贴的查询不能对本页执行任意代码。

我可以复制单个匹配值吗？

可以。复制到剪贴板按钮将完整结果块复制为 JSON 数组。若要获取单个值，请将输出模式切换为值，然后在结果文本框中选择所需行，并使用浏览器的普通复制快捷键（Ctrl/Cmd + C）。输出是纯 JSON 文本，可干净地粘贴到代码编辑器、终端、Postman 测试或 Slack 消息中。