第四节:理解 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:创建并配置工作流

  1. 在 n8n 编辑器中,创建一个新工作流。

  2. 从节点面板拖入一个 "Schedule Trigger" 节点。保持其默认配置(每 1 分钟触发一次)。

  3. 从节点面板拖入一个 "Edit Fields" 节点,并将其连接到 Schedule 节点之后。

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

  1. 点击 Edit Fields 节点。在配置面板中,切换到 "Mode" 选项卡。

  2. 将模式从 "Define Fields Below" 改为 "Pass Through"。此模式下,节点不会修改数据,仅作透传,是我们理想的"观察窗口"。

  3. 点击右上角的 "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:修改并观察数据变化

  1. 将 Edit Fields 节点的模式改回 "Define Fields Below"。

  2. 在"Add Field"区域,点击"String"添加一个字段。

  3. 设置 Field Name 为 message,Field Value 为 "Hello n8n!"。

  4. 再次点击 "Execute Node"。观察 OUTPUT 面板:

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

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

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

避坑指南 / 高阶技巧

  1. "为什么我的循环节点运行了这么多次?":检查输入该节点的 Item 数组长度。如果数组有 100 个 Item,节点默认就会执行 100 次。控制 Item 数组的"体积"是性能优化的关键。

  2. 访问深层 JSON 字段 :在节点配置中引用数据时,使用点号 . 或方括号 [] 路径。例如,要引用上面数据中的时间戳,表达式应为 {``{ $json.timestamp }} 或 {``{ $json["timestamp"] }}。

  3. 处理空数组或空数据 :在 IF 分支、错误处理等逻辑中,务必考虑上游可能传来空数组 [] 的情况,使用"Split In Batches"或"IF"等节点进行判断,避免下游节点报错。

  4. 利用"Paired Item"调试 :当数据流复杂时,pairedItem 属性可以帮助你追溯某个 Item 是由上游哪个 Item 生成的,这在调试数据拆分、合并时非常有用。

本章小结

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

  • 核心单位是 Item ,它是一个包含 json、binary 等属性的结构化对象。

  • 数据以 Item 数组(Array of Items) 的形式在节点间传递。

  • 节点默认的 "按 Item 执行" 机制是自动化批处理能力的基石。

  • Edit Fields 节点 是观察和理解数据结构的瑞士军刀。

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

相关推荐
九英里路14 小时前
protobuf快速上手
网络·c++·中间件·json·谷歌·序列化·protobuf
wuyk5551 天前
Spider-第09讲-三格式落盘CSV-Excel-JSON
爬虫·python·json·excel
wuyk5552 天前
Spider-第07讲-JSON接口与正则提取
爬虫·python·json
VIP_CQCRE3 天前
WorkBuddy 接入 Maestro 后,如何把一句需求变成可验收的视频任务
工作流·ai视频·maestro·mcp·workbuddy
xbzb5 天前
镜像到底存在哪:/var/lib/docker 的四级映射与 daemon.json 配置
docker·容器·json·镜像·daemon.json·四级
坤坤子吖5 天前
Linux网络编程:自定义应用层协议与 JSON 序列化
linux·服务器·网络·c++·笔记·json
code2cat6 天前
【随笔】结构化输出:JSON格式过关,业务数据就能入库吗
json·大语言模型
VIP_CQCRE8 天前
视频任务显示‘已提交’之后:别让异步生成变成黑盒
异步任务·工作流·ai视频·mcp
Hello_Pyhx9 天前
NWinfo 导出 Windows 硬件信息:从 JSON 报告到缺项排查
windows·json
程序员大阳10 天前
副队长JavaScript教程(66)-本地存储实战:待办事项网页的开发
javascript·json·实战·待办事项·本地存储·案例