关于此工具
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 路径查询、转义校验与节点一键提取。
如何使用本工具(操作步骤)
输入或粘贴根 JSON 数据对象
在左侧编辑窗口中输入或粘贴包含多层嵌套对象或数组的完整 JSON 报文或微服务配置文件。
键入 RFC 6901 指针路径
在路径栏输入以斜杠开头的定位路径(如 `/data/items/2/title`,亦可使用 `~1` 转义斜杠,`~0` 转义波浪号)。
实时检出目标子树并一键复制
右侧即刻高亮呈现抽取的单值(字符串、数字)或局部子 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 指针路径下的定位对照表
{
"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 引用链
{
"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 与云配置:指针不只能读,还能写回
# 用 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 报文,不必先手工打码。