n8n-workflow-patterns

n8n 工作流模式

构建 n8n 工作流的成熟架构模式。

---

6 种核心模式

基于对实际工作流用法的分析：

1. Webhook 处理（最常见）

   • 接收 HTTP 请求 → 处理 → 输出
   • 模式：Webhook → 验证 → 转换 → 响应/通知

2. HTTP API 集成

   • 从 REST API 获取数据 → 转换 → 存储/使用
   • 模式：触发器 → HTTP Request → 转换 → 操作 → 错误处理器

3. 数据库操作

   • 读取/写入/同步数据库数据
   • 模式：计划 → 查询 → 转换 → 写入 → 验证

4. AI Agent 工作流

   • 配备工具和记忆的 AI Agent
   • 模式：触发器 → AI Agent（模型 + 工具 + 记忆）→ 输出

5. 计划任务

   • 定期运行的自动化工作流
   • 模式：计划 → 获取 → 处理 → 交付 → 记录日志

6. 批处理（下文）

   • 在 API 速率限制下分块处理大型数据集
   • 模式：准备 → SplitInBatches → 逐批处理 → 累积 → 聚合

---

模式选择指南

各模式的适用场景：

Webhook 处理 - 适用于：

• 接收来自外部系统的数据
• 构建集成（Slack 命令、表单提交、GitHub Webhook）
• 需要即时响应事件
• 示例：“接收 Stripe 支付 Webhook → 更新数据库 → 发送确认信息”

HTTP API 集成 - 适用于：

• 从外部 API 获取数据
• 与第三方服务同步
• 构建数据管道
• 示例：“获取 GitHub issues → 转换 → 创建 Jira 工单”

数据库操作 - 适用于：

• 在数据库之间同步
• 按计划运行数据库查询
• ETL 工作流
• 示例：“读取 Postgres 记录 → 转换 → 写入 MySQL”

AI Agent 工作流 - 适用于：

• 构建对话式 AI
• 需要具备工具访问能力的 AI
• 多步骤推理任务
• 示例：“与 AI 对话，该 AI 能搜索文档、查询数据库、发送电子邮件”

计划任务 - 适用于：

• 定期生成报告或摘要
• 定期获取数据
• 维护任务
• 示例：“每日：获取分析数据 → 生成报告 → 通过电子邮件发送给团队”

批处理 - 适用于：

• 处理超出 API 批次限制的大型数据集
• 需要累积多次 API 调用的结果
• 嵌套循环（例如，多个类别 × 每个类别分页调用 API）
• 示例：“获取 4 个市场的产品，每次 API 调用获取 1000 条 → 聚合所有结果”

---

常见工作流组件

所有模式都使用以下构建模块：

1. 触发器

• Webhook - HTTP 端点（即时）
• 计划 - 基于 Cron 的定时（周期性）
• 手动 - 点击执行（测试）
• 轮询 - 检查变更（按间隔）

2. 数据源

• HTTP Request - REST API
• 数据库节点 - Postgres、MySQL、MongoDB
• 服务节点 - Slack、Google Sheets 等
• 从文件提取 - 从下载或上传的文件中提取 CSV / XLSX / PDF

3. 转换（优先使用原生节点）

• Filter / IF / Switch - 删除条目、路由
• Edit Fields (Set) - 命名步骤：常量条目、负载对象、错误和返回条目
• Summarize / Aggregate / Split Out - 分组并求总计、收集到数组中、展开数组
• Merge / Compare Datasets - 合并两个列表，比较差异以进行同步
• Remove Duplicates / Sort / Limit - 去重（也可跨运行去重）、取前 N 项
• Date & Time、XML、HTML、Crypto - 日期、标记语言、哈希和签名
• Code - 仅用于限定范围内的情况（没有节点能够实现的循环或递归、跨运行状态、没有节点能够处理的解析），并附上 Why Code: 说明

using-n8n-mcp-skills 中的任务到节点映射表将任务对应到这些节点；配置见 n8n-node-configuration → NATIVE_NODES.md。要读取嵌套 API 响应中某个字段的筛选结果？只需在该字段中使用单个 {{ $jmespath($json, "…") }}，无需额外节点（引号规则见 n8n-expression-syntax）。

4. 输出

• HTTP Request - 调用 API
• Database - 写入数据
• Communication - 电子邮件、Slack、Discord
• Storage - 文件、云存储

5. 错误处理

• Error Trigger - 捕获工作流错误
• IF - 检查错误条件
• Stop and Error - 显式失败
• Continue On Fail - 按节点设置

---

工作流创建清单

构建任何工作流时，请遵循此清单：

规划阶段

• 确定模式（webhook、API、数据库、AI、定时）
• 列出所需节点（使用 search_nodes）
• 理解数据流（输入 → 转换 → 输出）
• 规划错误处理策略

实施阶段

• 使用合适的触发器创建工作流
• 添加数据源节点
• 配置身份验证/凭据
• 添加转换节点（优先使用原生节点：Filter、IF、Summarize、Merge…；只有在注明 Why Code: 的情况下才使用 Code）
• 添加输出/操作节点
• 配置错误处理

验证阶段

• 验证每个节点的配置（validate_node）
• 验证完整工作流（validate_workflow）
• 使用示例数据进行测试
• 处理边缘情况（空数据、错误）

部署阶段

• 检查工作流设置（执行顺序、超时、错误处理）
• 使用 activateWorkflow 操作激活工作流
• 监控首次执行
• 记录工作流用途和数据流

---

工作流生命周期：激活前先验证、核实和测试

构建节点只是开始，而非终点。工作流上线前，请依次通过以下四道关卡，并牢记核心原则：验证通过是必要条件，但不是充分条件。 工作流可能顺利通过验证，但仍会丢失条目、选错 Merge 输入，或将 Slack 消息作为纯文本发布。验证通过只说明结构正确，不代表逻辑正确。

1. 验证。 在构建期间，对完整 JSON 运行 validate_workflow；或者在实例上创建工作流后运行 n8n_validate_workflow({ id })。修复所有错误并重新验证。这会检查架构、节点配置、表达式和引用错误，即结构层面的问题。
2. 核实连接。 使用 n8n_get_workflow({ id }) 获取工作流，并直接查看 connections 对象。验证可以确认连接没有断开，但不能确认连接正确。此时要检查那些有效但错误的连线：useDataOfInput 与连接槽不匹配的 Merge、连接不到任何节点的 Switch 回退分支、后续未连接的扇出分支，以及无处可去的错误输出。（有关不易察觉的问题，请参阅 n8n Node Configuration 技能中的 NODE_FAMILY_GOTCHAS.md。）
3. 测试。 运行 n8n_test_workflow，并通过 n8n_executions 检查输出。确认输出结构符合使用方的预期、所有扇出分支都产生了数据，并且（对于 webhook API）状态码/正文/标头正确。测试期间会触发真实的副作用——写入会提交，消息会发送，也会调用外部 API。如果任何节点有用户可见的副作用，运行前请先征得用户确认，或先使用安全数据进行测试。
4. 只有前三道关卡都通过后，才使用 n8n_update_partial_workflow 和 activateWorkflow 操作激活工作流。不要仅凭验证通过就直接激活；会丢失数据或重复发送内容的活动工作流，比从未启动的工作流更糟糕。

跳过任何一道关卡，都是为了现在节省几分钟，却把调试留到之后；届时工作流可能已经上线、带有状态，甚至正在承载流量。这笔账怎么算都不划算。

---

数据流模式

线性流程

Trigger → Transform → Action → End

适用场景：只有一条路径的简单工作流

分支流程

Trigger → IF → [True Path]
             └→ [False Path]

适用场景：根据条件执行不同操作

并行处理

Trigger → [Branch 1] → Merge
       └→ [Branch 2] ↗

适用场景：可同时运行的独立操作

循环模式

Trigger → Split in Batches → Process → Loop (until done)

适用场景：分批处理大型数据集

错误处理模式

Main Flow → [Success Path]
         └→ [Error Trigger → Error Handler]

适用场景：需要单独的错误处理工作流

---

批处理模式

SplitInBatches 循环

SplitInBatches 节点会将大型数据集拆分成较小的批次进行处理。了解其输出至关重要：

• main[0] = 完成 — 所有批次处理完毕后触发一次
• main[1] = 每个批次 — 每个批次触发一次（这是循环体）

Prepare Items → SplitInBatches → [main[1]: Process Batch] → (loops back)
                                  [main[0]: Done] → Limit 1 → Aggregate

请务必在完成输出之后添加一个 Limit 1 节点。

选择 batchSize（成本调节杆）

SplitInBatches 循环每次迭代都会重新运行整个循环体——每次迭代约产生 0.8 ms 的引擎开销，另加循环体自身的成本——因此总成本 ≈ ⌈items / batchSize⌉ × (overhead + body)。batchSize 可以直接调节速度：

• 选择实际约束所允许的最大批次大小（API 页大小、速率限制、内存）。批次越大 = 迭代越少 = 开销越低；循环体仍会处理每个项目。
• batchSize: 1 是成本最高的极端情况——每个项目都要完整运行一遍引擎。只有在必须一次处理一个项目时才使用（嵌套循环控制，或 API 一次只能接收一个 id）。
• 如果你只是为了“遍历项目”而循环，且没有外部约束，就不需要循环：将源连接到使用方即可。逐项目执行会自动处理，而原生转换节点会在一次调用中处理所有项目。

跨迭代数据

循环结束后，$('Node Inside Loop').all() 只会返回最后一个批次的项目。要累积所有迭代中的数据，请在循环内的 Code 节点中使用 $getWorkflowStaticData('global')。完整模式请参阅 n8n Code JavaScript 技能。

嵌套循环

处理 N 个类别 × 每个类别 M 个项目（API 有批次限制）时：

Define Categories (N items)
  → Outer Loop (SplitInBatches, batchSize=1)
    → Prepare category data
    → Inner Loop (SplitInBatches, batchSize=1000)
      → API Call → Verify → (loops back to Inner Loop via main[1])
    → Inner done[0] → Rate Limit Delay → back to Outer Loop
  → Outer done[0] → Limit 1 → Final Aggregate

连线注意事项：内部的 done[0] 必须连接回外层循环输入，而不是连接到聚合节点。外层的 done[0] 连接到最终聚合节点。

API 分页

遍历单个端点的分页应使用 HTTP Request 的分页选项，而不是循环（页码、偏移量、游标和 next-URL API，并且有页数上限——参见 n8n-node-configuration → NATIVE_NODES.md）。下方的循环适用于分页选项无法表达的遍历场景，例如 API 不支持多 ID 筛选，需要使用 id_from 和日期窗口遍历，每个窗口单独查询：

Schedule → Set Date Window → Fetch Page → Process
  → IF has more? → [true] Update id_from → Fetch Page (loop)
                  → [false] → Aggregate → Output

Dry-Run / 验证容错

为进行 dry run 而禁用 API 写入节点时，下游验证节点收到的是请求正文，而不是响应。请让验证逻辑具备容错能力：

// In verification Code node
const body = $input.first().json;
const looksLikeRequest = body.method && body.parameters && !body.status;
if (looksLikeRequest) {
  return [{ json: { status: 'SKIPPED', message: 'Upstream disabled for testing' }}];
}
// Normal response verification below...

---

热路径上的性能

当工作流处理数千个项目且 I/O 很少时，其速度取决于 n8n 跨越逐项目／逐迭代边界的次数——每次跨越都会建立执行上下文并复制项目。

1. 将热链整合到一个 Code 节点中是例外，而非默认做法。 每次节点之间的连接都会重新复制所有项目，因此，在实测的热路径中——每次运行数千个项目，转换工作而非 I/O 占主导——一个 All-Items Code 节点可能比长链更快。这属于闭合列表中的“繁重的全项目处理”情况：请将其记录在节点的 Why Code: 备注中。低于这个规模时，原生节点在可读性上更胜一筹。
2. 如果保留 Code，请使用 “Run Once for All Items”，而不是 “Each Item”。 Each Item 会为每个项目付出完整的沙箱开销；一串 Each-Item Code 节点是最糟糕的情况，因为逐项目开销会随着节点数累积。
3. 在 SplitInBatches 循环中尽可能增大 batchSize（参见上面的批处理模式）——迭代就是成本。
4. 不要微优化表达式——复杂度没有成本；需要付费的是节点数和迭代次数。

但请先进行性能分析。 大多数生产工作流受 I/O 限制——顺序执行的 HTTP／DB／Sheets 调用（每次耗时数百 ms）远比以上因素影响更大。这些规则适用于转换工作已是性能下限的情况，或反模式（Each-Item Code、batchSize 1、较长的逐项目链）将廉价操作拖慢的情况。项目数少于几百时，这些都无关紧要。n8n Code JavaScript 技能中提供了完整的实测模型。

---

特定集成的注意事项

Google Sheets

• 切勿在包含公式列的工作表上使用 append——这会破坏公式。请通过带有 googleApi 凭据的 HTTP Request 节点，使用 Google Sheets API values.update（PUT）
• 公式依赖的列要写入数字，而不是字符串——字符串 "4.98" 会导致 ADD() 公式失效。在列的表达式中进行转换：{{ $json.price.toNumber() }} 或 {{ parseFloat($json.price) }}
• 逐项执行陷阱：Google Sheets 节点会针对每个输入项执行一次。如果需要一次性批量写入，请先用 Aggregate 节点将各行汇总到一个项中
• UNFORMATTED_VALUE 返回的是数字，不是 "N/A" 之类的文本——请使用 Filter 节点明确筛选

Google Drive

• convertToGoogleDocument: true 会创建 Google Doc（文本），而不是 Google Sheet——要上传供下载的 CSV，请完全省略此选项
• CSV 下载链接格式：https://drive.google.com/uc?id={fileId}&export=download——请使用此链接，而不是 /view 链接

双向阈值检查

比较数值（价格、数量、指标）时，始终检查两个方向：

// ❌ Only catches increases
if (diff > threshold) { flag(); }

// ✅ Catches both spikes AND crashes — both are data-quality signals
if (Math.abs(diff) > threshold) { flag(); }

---

常见陷阱

1. Webhook 数据结构

问题：无法访问 webhook 负载数据

解决方案：数据嵌套在 $json.body 下

❌ {{$json.email}}
✅ {{$json.body.email}}

参见：n8n Expression Syntax 技能

2. 多个输入项

问题：节点会处理所有输入项，但我只想处理一个

解决方案：使用 "Execute Once" 模式，或只处理第一个项

{{$json[0].field}}  // First item only

3. 身份验证问题

问题：API 调用失败，返回 401/403

解决方案：

• 正确配置凭据
• 使用 "Credentials" 部分，而不是参数
• 在激活工作流之前测试凭据

4. 节点执行顺序

问题：节点以意料之外的顺序执行

解决方案：检查工作流设置 → Execution Order

• v0：从上到下（旧版）
• v1：基于连接（推荐）

5. 表达式错误

问题：表达式显示为字面文本

解决方案：使用 {{}} 包裹表达式

• 详情请参见 n8n Expression Syntax 技能

---

与其他技能集成

这些技能与 Workflow Patterns 配合使用：

n8n MCP Tools Expert——用于：

• 查找适用于你的模式的节点（search_nodes）
• 了解节点操作（get_node）
• 创建工作流（n8n_create_workflow）
• 部署模板（n8n_deploy_template）
• 使用 tools_documentation({topic: "ai_agents_guide", depth: "full"}) 获取 AI 模式指导
• 使用 n8n_manage_datatable 管理数据表
• 使用 n8n_manage_folders 将工作流整理到文件夹中

n8n Expression Syntax——用于：

• 在转换节点中编写表达式
• 正确访问 webhook 数据（{{$json.body.field}}）
• 引用先前的节点（{{$node["Node Name"].json.field}}）

n8n Node Configuration——用于：

• 为模式节点配置特定操作
• 了解节点专属要求

n8n Validation Expert——用于：

• 验证工作流结构
• 修复验证错误
• 确保工作流在部署前正确无误

---

模式统计

常见工作流模式：

最常见的触发器：

1. Webhook - 35%
2. Schedule（定期任务）- 28%
3. Manual（测试/管理）- 22%
4. 服务触发器（Slack、电子邮件等）- 15%

最常见的转换：

1. Set（字段映射）- 68%
2. Code（自定义逻辑）- 42%
3. IF（条件路由）- 38%
4. Switch（多条件）- 18%

最常见的输出：

1. HTTP Request（API）- 45%
2. Slack - 32%
3. 数据库写入 - 28%
4. 电子邮件 - 24%

工作流平均复杂度：

• 简单（3-5 个节点）：42%
• 中等（6-10 个节点）：38%
• 复杂（11 个以上节点）：20%

---

快速入门示例

示例 1：简单的 Webhook → Slack

1. Webhook (path: "form-submit", POST)
2. Slack (post message to #notifications; the text maps $json.body fields with expressions)

示例 2：定时报表

1. Schedule (daily at 9 AM)
2. HTTP Request (fetch analytics)
3. Summarize (totals per group)
4. Email (send formatted report)
5. Error Trigger → Slack (notify on failure)

示例 3：数据库同步

1. Schedule (every 15 minutes)
2. Postgres (query new records)
3. IF (check if records exist)
4. MySQL (insert records)
5. Postgres (update sync timestamp)

示例 4：AI 助手

1. Webhook (receive chat message)
2. AI Agent
   ├─ OpenAI Chat Model (ai_languageModel)
   ├─ HTTP Request Tool (ai_tool)
   ├─ Database Tool (ai_tool)
   └─ Window Buffer Memory (ai_memory)
3. Webhook Response (send AI reply)

示例 5：API 集成

1. Manual Trigger (for testing)
2. HTTP Request (GET /api/users; pagination option if the API pages)
3. Postgres (upsert users; map the fields in the node's column slots)

不需要循环，也不需要 Set：Postgres 会处理每个项，列槽位会接收映射表达式。

---

详细模式文件

有关各个模式的全面指南：

• webhook_processing.md - Webhook 模式、数据结构、响应处理
• http_api_integration.md - REST API、身份验证、分页、重试
• database_operations.md - 查询、同步、事务、批处理
• ai_agent_workflow.md - AI Agent、工具、记忆、langchain 节点
• scheduled_tasks.md - Cron 计划、报告、维护任务

---

真实模板示例

来自 n8n 模板库：

模板 #2947：天气信息发送到 Slack

• 模式：定时任务
• 节点：Schedule → HTTP Request（天气 API）→ Set → Slack
• 复杂度：简单（4 个节点）

Webhook 处理：最常见的模式

• 最常见的用途：表单提交、支付 Webhook、聊天集成

HTTP API：常见模式

• 最常见的用途：数据获取、第三方集成

数据库操作：常见模式

• 最常见的用途：ETL、数据同步、备份工作流

AI Agent：使用量持续增长

• 最常见的用途：聊天机器人、内容生成、数据分析

使用 n8n-mcp 工具中的 search_templates 和 get_template 查找示例！

---

最佳实践

✅ 应该做

• 从能解决问题的最简单模式开始
• 在构建前规划工作流结构
• 为所有工作流添加错误处理
• 激活前使用示例数据进行测试
• 遵循工作流创建检查清单
• 使用描述性节点名称
• 记录复杂工作流（备注字段）
• 部署后监控工作流执行情况

❌ 不应该做

• 一次性构建完整工作流（要迭代！平均每次编辑间隔 56 秒）
• 激活前跳过验证
• 忽略错误场景
• 明明简单模式就够用，却使用复杂模式
• 在参数中硬编码凭据
• 忘记处理空数据情况
• 在缺少明确边界的情况下混用多个模式
• 未经测试就部署

---

总结

要点：

1. 6 种核心模式覆盖 90% 以上的工作流使用场景
2. Webhook 处理是最常见的模式
3. 每个工作流都要使用工作流创建检查清单
4. 规划模式 → 选择节点 → 构建 → 验证 → 部署
5. 与其他技能集成，完成完整的工作流开发

后续步骤：

1. 确定适用场景的模式
2. 阅读详细的模式文件
3. 使用 n8n MCP Tools Expert 查找节点
4. 遵循工作流创建检查清单
5. 使用 n8n Validation Expert 进行验证

相关技能：

• n8n MCP Tools Expert - 查找和配置节点
• n8n Expression Syntax - 正确编写表达式
• n8n Validation Expert - 验证并修复错误
• n8n Node Configuration - 配置特定操作