T工具箱
/a/b

JSON Pointer 查询

用 RFC 6901 路径取出 JSON 片段

关于此工具

JSON 指针(JSON Pointer,RFC 6901 国际互联网工程任务组标准)是在复杂深层嵌套 JSON 文档中通过紧凑的斜杠路径语法(如 `/users/0/address/city`)定位、提取与修改特定单一子节点或数组元素的核心规范。相比庞大繁琐、支持过滤通配的 JSONPath,RFC 6901 JSON Pointer 专为“单路径精准定位”而生,是 RFC 6902 JSON Patch 变更补丁、OpenAPI / Swagger 引用(`$ref: '#/components/schemas/User'`)以及微服务配置治理的底层标准。本工具提供纯前端本地 JSON Pointer 路径查询、转义校验与节点一键提取。

如何使用本工具(操作步骤)

1

输入或粘贴根 JSON 数据对象

在左侧编辑窗口中输入或粘贴包含多层嵌套对象或数组的完整 JSON 报文或微服务配置文件。

2

键入 RFC 6901 指针路径

在路径栏输入以斜杠开头的定位路径(如 `/data/items/2/title`,亦可使用 `~1` 转义斜杠,`~0` 转义波浪号)。

3

实时检出目标子树并一键复制

右侧即刻高亮呈现抽取的单值(字符串、数字)或局部子 JSON 树结构,点击复制按钮一键提取直接投入工程中使用。

严格遵循 IETF RFC 6901 官方转义规范

完整支持特殊键名中的波浪号转义:遇到包含斜杠的键名使用 `~1` 平替,遇到包含波浪号的键名使用 `~0` 平替,绝对无误读。

深度兼容 OpenAPI / Swagger $ref 引用片段

无缝支持 URI Fragment 模式(如 `#/definitions/User/properties/id`),方便接口架构师快速排查大型接口文档的组件引用关系。

纯本地离线解析,企业配置数据绝对私密

所有 AST 语法树遍历完全在浏览器本地内存中运行,企业核心生产环境配置 JSON、用户机密报文绝不外传。

JSON 指针规范常识与避坑指南

  • •指针字符串必须强制以斜杠(`/`)开头:在 RFC 6901 规范中,除了空字符串 `""`(代表整个根文档本身)以外,所有有效的指针路径**第一位字符必须是 `/`**!如果写出 `user/profile`,在标准解析器中会直接抛出非法路径语法错误。
  • •切勿与 XPath 或 JSONPath 混淆:JSONPath 支持通配符(如 `$.tools[*].id`)与过滤表达式;而 JSON Pointer **不支持任何通配符或条件筛选**,它追求的是确定性的单路径高速寻址,两者解决不同维度的问题。
  • •URI Fragment 形式必须携带井号(`#`):当用在 OpenAPI 文档或 URL 锚点中时,指针应以 `#/` 开头(如 `#/components/schemas/Pet`),此时指针内部的非 ASCII 字符必须经过标准的 URL 百分号编码(Percent-encoding)。
  • •数组索引只接受规范十进制:`01` 在 RFC 6901 里是**非法**的(前导零不被允许),必须写 `1`。某些宽松实现会接受 `01`,但换到严格解析器(如 Go 的 `encoding/json` 指针实现)就会失败,跨语言传输时会踩这个坑。
  • •`-` 只在 Patch 里有意义:`/items/-` 指向「数组末尾之后」这个虚构位置,用于 RFC 6902 的 `add` 操作追加元素。用它去**读取**值永远失败,因为那个位置不存在。
  • •指针区分大小写,且不做任何模糊匹配:`/Components/Schemas/User` 和 `/components/schemas/User` 是两个完全不同的路径。OpenAPI 的键名约定是小写,从别处复制指针时留意别混入大写。

代码与转换对比示例

典型嵌套 JSON 在 RFC 6901 指针路径下的定位对照表

原始输入 JSON 文档
{
  "name": "在线工具箱",
  "tools": [
    { "id": "json-format", "tags": ["dev", "fast"] },
    { "id": "base64", "tags": ["encode"] }
  ],
  "a/b": "特殊键名包含斜杠",
  "m~n": "特殊键名包含波浪号"
}
指针路径与对应提取值
• 空字符串 ""          : 指向整个根 JSON 文档本身
• /name                : "在线工具箱"
• /tools/0/id          : "json-format" (数组索引从 0 开始)
• /tools/0/tags/1      : "fast" (提取数组中第二个子元素)
• /a~1b                : "特殊键名包含斜杠" (用 ~1 转义斜杠)
• /m~0n                : "特殊键名包含波浪号" (用 ~0 转义波浪号)

* 指向数组末尾之后的新插入位置使用特殊符号 `/-`(常用于 JSON Patch 新增操作)。

JavaScript 原生极简实现 RFC 6901 解析核心代码

核心解析函数范式
function getByPointer(doc, pointer) {
  if (pointer === '') return doc;
  if (!pointer.startsWith('/')) throw new Error('指针必须以 / 开头');
  const tokens = pointer.slice(1).split('/').map(t => {
    // RFC 6901 解码: 先将 ~1 还原为 /,再将 ~0 还原为 ~
    return t.replace(/~1/g, '/').replace(/~0/g, '~');
  });
  return tokens.reduce((acc, k) => acc[k], doc);
}
调用实测
const data = { user: { profile: { age: 28 } } };
console.log(getByPointer(data, "/user/profile/age")); // 28

* 转义替换必须先替换 `~1` 再替换 `~0`,顺序颠倒会导致转义字符产生破坏性二义性!

在真实的 OpenAPI 文档里追踪一条 $ref 引用链

OpenAPI 3.0 片段(节选)
{
  "paths": {
    "/users/{id}": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id":    { "type": "integer" },
          "email": { "type": "string", "format": "email" },
          "tags":  { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}
指针求值结果
# 从 $ref 的值直接展开目标 schema(去掉开头的 #)
#/components/schemas/User
  → { "type": "object", "properties": { ... } }

# 继续下钻到具体字段的类型
#/components/schemas/User/properties/email/format
  → "email"

# 注意路径里 /users/{id} 这个键名本身含斜杠,必须转义
#/paths/~1users~1{id}/get/responses/200/content/application~1json/schema
  → { "$ref": "#/components/schemas/User" }

# 直接读到数组项的 schema
#/components/schemas/User/properties/tags/items/type
  → "string"

* 键名里的 `/` 一律写成 `~1`,这是指针在 OpenAPI 上最常踩的坑——路径键(`/users/{id}`)和媒体类型键(`application/json`)都含斜杠。

Kubernetes 与云配置:指针不只能读,还能写回

kubectl patch 与 JSON Patch 操作
# 用 JSON Patch 修改 Deployment 里容器镜像的 tag
kubectl patch deployment web --type='json' -p='[
  { "op": "replace",
    "path": "/spec/template/spec/containers/0/image",
    "value": "nginx:1.27-alpine" }
]'

# 追加一个环境变量(注意 /- 表示数组末尾之后)
kubectl patch deployment web --type='json' -p='[
  { "op": "add",
    "path": "/spec/template/spec/containers/0/env/-",
    "value": { "name": "LOG_LEVEL", "value": "debug" } }
]'
路径语义拆解
• /spec/template/spec/containers/0
    0 是数组下标,指向第一个容器(不是容器名)

• /image          → 该容器当前的镜像字符串

• /env/-          末尾追加语义,只有 RFC 6902 的 add 能用
                  换成读取会失败,因为那个位置不存在

• 若容器名含斜杠或特殊字符(少见但存在)
  仍需按 KEY 而非 NAME 定位,或改用 strategic merge patch

* Kubernetes 的 strategic merge patch 是另一套机制,不遵循 RFC 6901;只有 `--type='json'` 走的才是标准 JSON Patch,路径规则与本文一致。

常见问题解答

Q: 为什么 RFC 6901 要选用 `~1` 和 `~0` 作为转义符,而不是常见的反斜杠 `\`?

A: 因为 JSON 指针经常需要直接作为 URL 的 URI Fragment(锚点)或者通过查询字符串在 HTTP 协议中传输。反斜杠 `\` 在 URL 规范中是不安全保留字符,而波浪号 `~` 属于 URL 非保留安全字符,使用波浪号转义可避免产生多层嵌套转义地狱。

Q: 如果路径中的属性名在 JSON 中根本不存在,系统会返回什么?

A: 根据标准规范,解析器会中途终止遍历并返回 `undefined` 或抛出查找失败异常(Pointer Reference Error),本工具会在界面上即时红字提示具体在哪一级属性中断脱节。

Q: 数组索引支持负数(如 `-1` 代表最后一位)吗?

A: 在严格的 RFC 6901 规范中,**不支持类似 Python 的 `-1` 倒序索引**。数组索引必须是合法的非负整数字符串(`0`, `1`, `2`...)。特殊符号 `-`(如 `/-`)仅代表刚好超出数组当前最大长度的末尾附加位置。

Q: JSON Pointer 和 JSONPath 到底该用哪个?

A: 看你要的是「一个确定的位置」还是「一批符合条件的位置」。JSON Pointer 只能指向唯一一个节点,路径里没有任何通配符或条件,所以它是可预测、可回传、可存进配置文件的——OpenAPI 的 `$ref`、JSON Patch 的操作路径、Kubernetes 的字段路径都必须用它。JSONPath 相反,`$.store.book[*].author` 一次取出所有作者,适合查询和报表,但它不是标准(RFC 里没有 JSONPath),各家实现行为不一致,所以不适合当作持久化的引用格式。经验法则:**给机器读的引用用 Pointer,给人看的查询用 Path**。

Q: 为什么我的指针在浏览器里能用,在服务端却解析失败?

A: 最常见的原因是转义顺序。RFC 6901 要求先解 `~1`(还原成 `/`)再解 `~0`(还原成 `~`)。如果你写的实现顺序反了,键名 `a~1b` 会先被当成 `a/b` 再被继续拆分,结果完全错乱。第二个原因是前导零:浏览器里的宽松实现可能接受 `/items/01`,而 Go、Rust 等严格实现会直接报错。第三个是指针开头的 `#`——那是 URI Fragment 的写法,只在 URL 语境下有效,作为纯指针传给解析器时那个 `#` 是路径的一部分,会查不到。

Q: 指针能不能定位到 `null` 值,或者区分「值为 null」和「字段不存在」?

A: 能定位到 `null`,但**无法用返回值区分这两种情况**。按 RFC 6901,对一个不存在的路径求值属于错误;但对一个存在且值为 `null` 的路径求值,返回的就是 `null`。如果实现里把错误也返回成 `null`(很多 JavaScript 实现因为 `undefined` 与 `null` 混用会这样),两件事就糊在一起了。要在业务里区分,得先用不含指针的方式判断键是否存在——比如 `Object.prototype.hasOwnProperty`,或者让解析器在失败时抛异常而不是返回 `null`。

Q: 键名里出现 `~` 或 `/` 时,写出正确指针的步骤是什么?

A: **编码方向只有一个,且顺序固定:先把 `~` 换成 `~0`,再把 `/` 换成 `~1`。** 这个顺序不能反。举例:键名 `a/b` 编码后是 `/a~1b`;键名 `m~n` 编码后是 `/m~0n`;键名 `~/` 编码后是 `/m~0~1`(先处理波浪号变 `~0`,斜杠再变 `~1`,得到 `~0~1`)。注意你没有看错——键名是 `~/` 两个字符,编码结果是四个字符 `~0~1`。解码时严格反着来:先 `~1`→`/`,再 `~0`→`~`。

Q: 在 OpenAPI 文档里怎么用指针找到某个 schema 字段?

A: OpenAPI 文档本身就是一份 JSON,所以指针的写法完全一致,只是入口是 `#/` 而不是 `/`。看一个真实例子:定位 `Pet` schema 下 `name` 字段的类型,指针是 `#/components/schemas/Pet/properties/name/type`。要找到所有引用了 `Pet` 的地方没法用指针(那需要搜索,不是寻址),但反过来——从 `$ref` 的值跳过去——正是指针的标准用法:`$ref: '#/components/schemas/Pet'` 里的 `#/components/schemas/Pet` 就是指针,把 `#` 去掉直接喂给本工具就能展开看内容。OpenAPI 2.0(Swagger)的路径是 `#/definitions/Pet`,3.x 改成了 `#/components/schemas/Pet`,跨版本迁移时这是常见的不一致来源。

Q: JSON Patch 里的路径和普通指针有区别吗?

A: 路径语法完全相同,都是 RFC 6901 指针;区别在于 RFC 6902 额外赋予了 `-` 一个语义。在 JSON Patch 里,`/items/-` 表示「数组末尾之后的那个位置」,`{"op": "add", "path": "/items/-", "value": ...}` 会把元素追加到数组尾部。除 Patch 之外,`-` 没有任何意义——拿它做读取一定失败。另外一个和读取场景不同的点:Patch 的 `remove` 和 `replace` 针对的是**已存在**的位置,路径写错不会静默跳过,而是整个 Patch 操作失败并回滚。

Q: 指针很长时,怎么确认它到底指向哪里?

A: 沿路径逐段推进,每一段都确认一次,而不是一次性把整串贴进去看结果。例如 `#/paths/~1users~1{id}/get/responses/200/content/application~1json/schema`,看起来像乱码,但拆开就清楚:`paths` 是顶层键;`~1users~1{id}` 解码回 `/users/{id}`(这正是键名里带斜杠所以要转义的情形);`get`、`responses`、`200`、`content` 都是普通键;`application~1json` 解码回 `application/json`;最后 `schema` 是目标。本工具的界面会在每一级显示当前节点名称和类型,路径错了会明确停在断掉的那一段,比一次性看最终结果更容易定位问题。

Q: 这个工具会把我的 JSON 上传到服务器吗?

A: 不会。指针解析完全在浏览器内存里完成,没有网络请求,也没有任何数据落到外部。这一点对调试生产环境的接口响应或含密钥的配置文件尤其重要——你可以直接粘贴真实的 `kubeconfig`、云厂商凭证 JSON 或内部 API 报文,不必先手工打码。

相关推荐工具

所有处理都在你的浏览器本地完成,数据不会上传到服务器。
/