工具指南2026-07-13JSONJSON扁平化JSON Pointer数据转换API开发工具

JSON 扁平化怎么做？点路径、JSON Pointer、数组与类型还原指南

介绍嵌套 JSON 展开为路径键值表的方法，对比点路径和 JSON Pointer，并说明数组、空容器、数据类型和冲突还原。

API 返回的 JSON 经常同时包含嵌套对象和数组，直接放进表格、环境变量或简单键值存储并不方便。扁平化会把每个叶子值转换成一条“路径 → 值”记录，还原则根据路径重新构造对象和数组。

可以使用 JSON 扁平化与还原工具在浏览器本地展开或还原数据，支持人类更易读的点路径和标准化程度更高的 JSON Pointer，并保留数字、布尔值、null、空对象和空数组。

JSON 扁平化是什么

RFC 8259 定义 JSON 值可以是对象、数组、数字、字符串、布尔值或 null。扁平化并不是 JSON 标准中的唯一格式，而是应用根据需要建立的路径表示。

原始数据：

json已剪下 ✓

{
  "order": {
    "id": "SO-1001",
    "items": [
      {"sku": "A", "qty": 2}
    ],
    "paid": true
  }
}

点路径展开后可能是：

json已剪下 ✓

{
  "$.order.id": "SO-1001",
  "$.order.items[0].sku": "A",
  "$.order.items[0].qty": 2,
  "$.order.paid": true
}

这种结构适合字段映射、日志检索、差异对比和 CSV 导出。

点路径常写成 $.order.items[0].sku，直观接近 JavaScript 属性访问，但它不是一个全球统一的交换标准。属性名本身包含点号、空格或方括号时，需要转义或改用引号括号，例如 $["odd.key"]。

JSON Pointer 使用斜杠分段，例如 /order/items/0/sku。属性名中的 ~ 编码为 ~0，/ 编码为 ~1。它在 JSON Patch、OpenAPI 和部分配置系统中更常见，但数组索引和纯数字对象键仍要结合上下文理解。

选择哪种语法取决于接收系统。不能把工具生成的点路径直接假定为数据库、表格导入器或日志平台都能理解的格式。

对象属性 "0" 和数组索引 0 在 JSON 中不是同一种结构。下面两个值外观看起来接近：

json已剪下 ✓

{"items": {"0": "A"}}
{"items": ["A"]}

还原工具需要从路径语法判断该创建对象还是数组。点路径用 [0] 明确数组；JSON Pointer 的 /items/0 则通常需要根据整个路径集合推断。

稀疏数组也要谨慎。如果只提供索引 5，JavaScript 数组前面会形成空槽，序列化时可能显示为 null。把数据库主键误当成数组索引，可能制造巨大稀疏数组。

递归展开时，非空容器最终都有叶子值；空对象 {} 和空数组 [] 没有子节点。如果不专门保存它们，扁平结果中就没有任何路径可以证明容器存在，还原时自然会丢失。

需要可逆转换时，应开启“保留空对象和空数组”。如果只是为搜索索引提取实际值，也可以有意忽略空容器，但要接受无法完全还原。

JSON 键值映射可以继续保存原始类型：数字仍是数字，true 仍是布尔值，null 仍是 null。CSV 单元格只有文本外观，导出再导入时可能把数字、布尔和空字符串混淆。

例如字符串 "00123" 不能自动变成数字 123，否则会丢失前导零；字符串 "false" 也不等于布尔值 false。需要完整往返时，优先保存 JSON 格式，或在表格里增加明确的 type 列。

以下路径不能同时成立：

text已剪下 ✓

$.user = "Alice"
$.user.name = "Alice"

第一条要求 user 是字符串，第二条要求它是对象。还原工具应报告冲突，而不是悄悄覆盖其中一条。对象和数组容器冲突、重复路径、根路径与子路径同时存在，也应被拒绝。

把外部提供的路径直接写入普通 JavaScript 对象时，需要注意 __proto__、constructor 等特殊属性可能造成原型污染。稳妥实现可以使用无原型对象、显式自有属性检查，并限制节点数量和嵌套深度。

本地工具还应避免把用户 JSON 上传到服务器。接口响应里可能包含客户资料、访问令牌和内部配置，即使只是临时转换，也不适合交给来源不明的网站。

JSON 扁平化适合：

它不适合无损表达循环引用、Date、Map、BigInt 或函数，因为这些本来就不属于标准 JSON 值。先确认输入是真正的 JSON，再讨论扁平化规则。

处理生产数据时，建议保留原始文件，记录路径语法、空容器策略和工具版本；展开后抽样核对数组、特殊属性名和 null；再执行一次还原，把结果与原始 JSON 做结构比较。