第四节：理解 JSON 结构与 Item 概念

引言

上一章我们成功让工作流"动"了起来，体验了节点间数据传递的魔力。但你是否好奇，数据在节点间的"血管"里究竟以何种形态流动？理解这一点，是摆脱"连线魔法师"、成为真正架构师的关键。本章，我们将深入 n8n 的数据血液------JSON 与 Item。

核心理论：理解 JSON 与 Item

在 n8n 中，数据并非以单一"值"的形式传递，而是被精心组织成一种名为 "Item" 的结构。你可以将整个工作流想象成一个精密的流水线：

核心概念：标准集装箱

Item 是标准集装箱 ：每个 Item 就是一个独立的、结构化的数据包裹，其本质是一个JSON 对象。例如，一个来自 HTTP 节点的 API 响应，其主体（Body）会被包装成一个 Item。

核心架构：集装箱阵列

工作流处理的是集装箱阵列 ：数据在节点间并非单个 Item 传递，而是以 "Array of Items"（Item 数组） 的形式流转。即使上游节点只产生了一个 Item，它也会被放入一个数组中（即 [item]）传给下游。

运行机制：按 Item 执行

节点的"按 Item 执行"机制 ：这是 n8n 最独特且强大的设计。当一个节点接收到一个包含多个 Items 的数组时，默认情况下，它会为数组中的每一个 Item 都执行一次操作。例如，一个"HTTP Request"节点收到一个包含 10 个用户 ID 的 Item 数组，它就会自动发起 10 次 HTTP 请求（每个请求使用一个 Item 中的数据）。

底层流转原理：每个节点都有输入和输出。输入是上一个节点传来的 Item 数组，节点内部逻辑会处理这个数组（可能遍历每个 Item），处理完成后，再输出一个新的 Item 数组给下游。这个过程中，数据的 JSON 结构可以被增删改查。

实战演练：观察数据的"真面目"

让我们通过一个简单工作流，亲眼看看数据的真实形态。

步骤 1：创建并配置工作流

在 n8n 编辑器中，创建一个新工作流。
从节点面板拖入一个 "Schedule Trigger" 节点。保持其默认配置（每 1 分钟触发一次）。
从节点面板拖入一个 "Edit Fields" 节点，并将其连接到 Schedule 节点之后。

步骤 2：使用 Edit Fields 节点观察输入数据

点击 Edit Fields 节点。在配置面板中，切换到 "Mode" 选项卡。
将模式从 "Define Fields Below" 改为 "Pass Through"。此模式下，节点不会修改数据，仅作透传，是我们理想的"观察窗口"。
点击右上角的 "Execute Node" 按钮，单独运行这个 Edit Fields 节点。

步骤 3：分析输入/输出面板

运行后，节点下方会展开输入（INPUT）和输出（OUTPUT）面板。

INPUT 面板显示的数据结构示例：

复制代码

[
  {
    "json": {
      "timestamp": 1715589123456,
      "_cron": "* * * * *"
    },
    "binary": {},
    "pairedItem": {
      "item": 0
    }
  }
]

关键解读：

最外层的 [ ... ] 表明这是一个 Item 数组，即使只有一个 Item。
数组内的每个对象就是一个 Item。
Item 内部包含几个主要属性：
- json: 核心数据区 。所有你需要操作和传递的业务数据都在这里。本例中，Schedule 节点产生了 timestamp 和 _cron 两个字段。
- binary: 存放二进制数据，如图片、文件。当前为空。
- pairedItem: n8n 用于追踪数据血缘的内部信息。

步骤 4：修改并观察数据变化

将 Edit Fields 节点的模式改回 "Define Fields Below"。
在"Add Field"区域，点击"String"添加一个字段。
设置 Field Name 为 message，Field Value 为 "Hello n8n!"。
再次点击 "Execute Node"。观察 OUTPUT 面板：

OUTPUT 面板显示的数据结构示例：

复制代码

[
  {
    "json": {
      "timestamp": 1715589123456,
      "_cron": "* * * * *",
      "message": "Hello n8n!" 
    },
    "binary": {},
    "pairedItem": {
      "item": 0
    }
  }
]

可以看到，输出的 Item 中，json 对象里新增了我们定义的 message 字段。这就是节点修改数据的基本方式。

避坑指南 / 高阶技巧

"为什么我的循环节点运行了这么多次？"：检查输入该节点的 Item 数组长度。如果数组有 100 个 Item，节点默认就会执行 100 次。控制 Item 数组的"体积"是性能优化的关键。
访问深层 JSON 字段 ：在节点配置中引用数据时，使用点号 . 或方括号 [] 路径。例如，要引用上面数据中的时间戳，表达式应为 {``{ $json.timestamp }} 或 {``{ $json["timestamp"] }}。
处理空数组或空数据 ：在 IF 分支、错误处理等逻辑中，务必考虑上游可能传来空数组 [] 的情况，使用"Split In Batches"或"IF"等节点进行判断，避免下游节点报错。
利用"Paired Item"调试 ：当数据流复杂时，pairedItem 属性可以帮助你追溯某个 Item 是由上游哪个 Item 生成的，这在调试数据拆分、合并时非常有用。

本章小结

本章我们揭开了 n8n 数据流转的神秘面纱：

核心单位是 Item ，它是一个包含 json、binary 等属性的结构化对象。
数据以 Item 数组（Array of Items） 的形式在节点间传递。
节点默认的 "按 Item 执行" 机制是自动化批处理能力的基石。
Edit Fields 节点 是观察和理解数据结构的瑞士军刀。

牢牢掌握"Item 视角"，你就能精准预测和控制工作流中每一份数据的命运，为后续构建复杂逻辑打下坚实基础。