# JSONPath查询使用教程：一条表达式精准提取JSON数据

> 来源：工具派（https://gjupai.com） 原文页面：https://gjupai.com/tutorial/jsonpath-query-guide

## 工具简介

**JSONPath 查询**是工具派提供的在线 JSON 数据提取工具。JSONPath 之于 JSON，就像 XPath 之于 XML——用一条简洁的「路径表达式」，就能从层级复杂、动辄上百行的 JSON 里精准定位并取出你想要的数据，而无需写任何代码。

工具的用法很直观：左侧粘贴 JSON、输入表达式，右侧实时显示查询结果。它还内置了 **JSON 树形结构**（点击任意节点即可自动生成对应路径）、**常用语法** 速查面板，以及多组开箱即用的 **示例数据**。无论是调试接口返回值，还是系统学习 JSONPath 语法，都非常顺手。整个解析与查询过程都在浏览器本地完成，你的数据不会上传到服务器。

支持的语法包括：根对象 `$`、属性访问 `$.name`、数组索引 `$[0]`、通配符 `$[*]`、递归下降 `$..`、条件过滤 `$[?(@.age>18)]`、数组切片 `$[0:3]`、多选 `$[name,price]` 等，足以应对绝大多数 JSON 取值需求。

## 适用场景

- **调试 API 返回值**：接口返回一大坨 JSON，只想看其中某几个字段，一条表达式立刻搞定。
- **数据清洗与提取**：从日志、配置文件、爬虫结果里批量挑出符合条件的元素，例如「所有价格低于 10 的商品」。
- **学习 JSONPath 语法**：配合示例数据和语法面板，边点边看结果，快速上手这套通用查询语言。
- **定位嵌套字段路径**：面对陌生的 JSON 结构，点一下树形节点就能得到它的完整访问路径。

## 使用步骤

### 第 1 步：准备 JSON 数据

在左侧「**JSON 数据**」文本框中粘贴你的 JSON。如果手头没有现成数据，可以点击上方的「**示例数据**」按钮，工具内置了三组演示数据：

- **示例数据**：经典的「书店」结构（`store.book` 数组 + `bicycle` 对象）；
- **用户信息**：一组用户数组（含 `id`、`name`、`age`、`active`、`roles` 字段）；
- **嵌套结构**：公司 → 部门 → 员工的多层嵌套结构。

点击任意一个示例按钮，会自动填入对应的 JSON 和一条示范表达式，方便直接体验。

> 小提示：文本框右上有「**格式化**」「**压缩**」「**清空**」三个小按钮。粘贴进来的单行 JSON 可以先点「格式化」，美化成带缩进的结构，阅读起来更轻松。

![工具整体界面：顶部三个示例数据按钮，左侧为 JSON 数据输入框（含格式化/压缩/清空按钮），下方是 JSONPath ](article/202607/1783945223220_5999.png)

### 第 2 步：编写 JSONPath 表达式

在「**JSONPath 表达式**」输入框里写下查询路径。所有表达式都以 `$`（代表根对象）开头，例如：

- `$.store.book[0].title` —— 取第一本书的标题；
- `$.store.book[*].author` —— 取所有书的作者；
- `$.users[?(@.age>25)].name` —— 取年龄大于 25 岁的用户姓名。

表达式框上方还提供了 4 个**快捷查询**按钮（如 `$.store.book[*].author`、`$.store.book[?(@.price<10)]` 等），点一下即可填入常用写法，非常适合参考格式。

### 第 3 步：执行查询并查看结果

点击蓝色的「**查询**」按钮执行；实际上你每次修改 JSON 或表达式后，工具也会**自动重新查询**，结果实时刷新。

右侧「**查询结果**」区域会列出所有匹配项，标题旁标注了结果条数，例如「查询结果 (4 条)」。每条结果用单独的卡片展示：对象和数组会自动格式化缩进，字符串、数字、布尔等基本值则直接显示。没有匹配项时显示「暂无结果」；如果 JSON 本身写错了，输入框下方会出现红色的「JSON 错误：……」提示，帮你快速定位格式问题。

![输入表达式 $.store.book * .author 并点击查询后，右侧查询结果区显示 4 条匹配结果，每条以编号卡](article/202607/1783945223448_2691.png)

### 第 4 步：用树形结构定位路径（强烈推荐）

不熟悉 JSON 结构、不知道字段藏在哪一层？看左下角的「**JSON 树形结构**」。它把整份 JSON 渲染成一棵可折叠的树：

- 点击节点前的 ▼ / ▶ 可以展开或折叠；
- **直接用鼠标点击任意字段名（key），工具会自动把该节点的完整 JSONPath 填进表达式框**——这是生成路径最省事的方式，再也不用手数层级、不用担心写错。

暂时不需要树可以点「折叠」收起，需要时再点「展开」。

![左下角 JSON 树形结构面板，展示可折叠的 JSON 树，鼠标正点击某个字段名，表达式框自动填入该节点的完整路径。](article/202607/1783945223677_6784.png)

### 第 5 步：复制结果

确认结果无误后，点击结果区右上角的「**复制结果**」，会把全部匹配项以 JSON 数组的形式复制到剪贴板（复制成功会短暂显示「已复制」），方便直接粘贴到代码或文档中使用。

## 参数与选项说明

下面是工具支持的 JSONPath 语法速查（示例均以内置「书店」数据为准）：

| 语法 | 说明 | 示例 |
| --- | --- | --- |
| `$` | 根对象，所有表达式的起点 | `$` |
| `$.属性名` | 访问对象的某个属性 | `$.store.bicycle` |
| `$[索引]` | 按位置取数组元素（从 0 开始） | `$.store.book[0]` |
| `$[*]` | 取数组所有元素，或对象的所有值 | `$.store.book[*]` |
| `$..` | 递归下降，展开整棵树的所有节点 | `$..employees[*].name` |
| `$[?(@.字段 操作符 值)]` | 按条件过滤数组元素 | `$.store.book[?(@.price<10)]` |
| `$[起始:结束]` | 数组切片（含起始、不含结束） | `$.store.book[0:2]` |
| `$[名1,名2]` / `$[0,2]` | 多选：一次取多个属性或多个索引 | `$.store.book[0,2]` |
| `$['属性名']` | 用方括号加引号访问属性（属性名含特殊字符时用） | `$['store']['bicycle']` |

条件过滤支持以下操作符（`@` 代表当前被遍历的数组元素）：

| 操作符 | 含义 | 示例 |
| --- | --- | --- |
| `==` | 等于（可比较数字、布尔、带引号的字符串） | `?(@.category=='fiction')`、`?(@.active==true)` |
| `!=` | 不等于 | `?(@.id!=2)` |
| `>` / `<` | 大于 / 小于（数字比较） | `?(@.age>25)` |
| `~=` | 字符串包含（左侧是字符串且包含右侧内容） | `?(@.name~=张)` |
| `?(@.字段)` | 存在性判断：该字段存在即匹配 | `?(@.isbn)` |

## 实用技巧

1. **优先点击树形节点生成路径**：这是零出错的方式，尤其适合层级很深的 JSON。
2. **善用快捷入口**：表达式框上方的快捷查询按钮，以及右下角「常用语法」面板里的每一条语法，都可以**点击直接填入表达式框**，照着改即可。
3. **先格式化再查询**：结构清晰的 JSON 更便于对照结果。
4. **过滤值要区分类型**：字符串必须带引号（`?(@.category=='fiction')`），数字和布尔值不带引号（`?(@.price<10)`、`?(@.active==true)`）。
5. **批量映射字段**：用 `$.数组[*].字段名` 可以一次性取出数组里每个元素的某个字段，例如 `$.users[*].name`。
6. **属性名含特殊字符**：当字段名里有点号、空格或中文等，改用方括号加引号的写法 `$['属性名']`。

## 常见问题

**Q1：为什么 `$..price` 返回了一大堆结果，而不只是价格？**
`$..` 是递归下降语法，它会把整棵树的所有节点都展开返回，`..` 后面紧跟的属性名在本工具中不参与过滤。如果只想取特定位置的价格，建议使用完整点路径，例如 `$.store.book[*].price`；也可以用组合写法 `$..book[*].price` 取出树中所有名为 `price` 的字段值。

**Q2：`>=` 和 `<=` 为什么查不出结果？**
这是工具当前的一个已知限制：`>=`、`<=` 会被解析器误判，导致恒不匹配、返回空。请改用 `>` 或 `<` 变通，例如把 `?(@.age>=28)` 换成 `?(@.age>27)`，效果相同。

**Q3：表达式看着没错，却显示「暂无结果」？**
请逐项排查：① JSON 是否合法（输入框下方有无红色「JSON 错误」提示）；② 属性名大小写是否完全一致（区分大小写）；③ 数组索引是否越界；④ 过滤条件里的字符串是否加了引号。

**Q4：支持用负数索引（如 `$[-1]`）取最后一个元素吗？**
不支持。索引只能是非负整数，切片也只接受非负数字。需要定位末尾元素时，可以结合数组长度使用切片，或直接在「JSON 树形结构」里点击该节点获取路径。

**Q5：我粘贴的 JSON 会上传到服务器吗？**
不会。解析与查询全部在你的浏览器本地完成，数据不会离开浏览器，可放心用于敏感数据。