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 问题 → 转换 → 创建 Jira 工单”

数据库操作 - 适用于：

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

AI Agent 工作流 - 适用于：

• 构建对话式 AI
• 需要具备工具访问权限的 AI
• 多步骤推理任务
• 示例：“与 AI 聊天，让它搜索文档、查询数据库并发送邮件”

定时任务 - 适用于：

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

批处理 - 适用于：

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

---

常见工作流组件

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

1. 触发器

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

2. 数据源

• HTTP Request - REST API
• 数据库节点 - Postgres、MySQL、MongoDB
• 服务节点 - Slack、Google Sheets 等
• Code - 自定义 JavaScript/Python

3. 转换

• Set - 映射/转换字段
• Code - 复杂逻辑
• IF/Switch - 条件路由
• Merge - 合并数据流

4. 输出

• HTTP Request - 调用 API
• 数据库 - 写入数据
• 通信 - Email、Slack、Discord
• 存储 - 文件、云存储

5. 错误处理

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

---

工作流创建检查清单

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

规划阶段

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

实现阶段

• 使用适当的触发器创建工作流
• 添加数据源节点
• 配置身份验证/凭据
• 添加转换节点（Set、Code、IF）
• 添加输出/操作节点
• 配置错误处理

验证阶段

• 验证每个节点的配置（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 skill 的 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）。
• 如果循环只是为了“遍历项目”，且没有外部约束，通常不需要循环——单个 All Items Code 节点处理整个集合，成本要低得多。

跨迭代数据

循环结束后，$('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 分页

对于不支持多 ID 过滤的 API，使用 id_from 和日期窗口进行高效分页：

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

Dry-Run / 验证容错

使用 API 写入节点禁用的方式进行测试（即 dry run）时，下游验证节点收到的是请求正文，而不是响应。应让验证逻辑能够处理这两种情况：

// 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. 优先使用更少、更集中的 All-Items 节点，而不是冗长的转换链。 每次节点→节点的传递都会重新复制所有项目（每次传递每个项目约 0.05 ms），因此，串联六个 Code/Set 节点的成本约为一个 All-Items Code 节点完成相同步骤的 7 倍。精简热路径。
2. 使用 Code 的 “Run Once for All Items”，而不是 “Each Item”——每个项目约 0.02 ms，而非约 0.6 ms（约 25–30 倍）。串联多个 Each-Item Code 节点是最糟糕的情况；单项目开销会随节点数量倍增。
3. 尽可能增大 SplitInBatches 循环中的 batchSize（参见上面的批处理模式）——迭代次数就是成本。
4. 不要对表达式做微优化——复杂度无需付费；需要付费的是节点数和迭代次数。

但要先进行性能分析。 大多数生产工作流受 I/O 限制——顺序执行的 HTTP / DB / Sheets 调用（每次耗时数百毫秒）远比以上所有因素影响更大。当转换工作成为瓶颈，或某种反模式（Each-Item Code、batchSize 1、冗长的逐项目处理链）让廉价操作变慢时，这些规则才重要。项目数量少于几百时，这些因素都无关紧要。n8n Code JavaScript 技能提供了完整的实测模型。

---

特定集成注意事项

Google Sheets

• 含有公式列的工作表绝对不要使用 append——这会破坏公式。请通过带有 googleApi 凭据的 HTTP Request 节点使用 Google Sheets API values.update（PUT）
• 公式依赖的列应写入数字，而非字符串——字符串 "4.98" 会导致 ADD() 公式失效。请在 Code 节点中使用 parseFloat()
• 逐项目执行陷阱：Google Sheets 节点会针对每个输入项目执行一次。如果需要单次批量写入，请先在 Code 节点中将项目聚合起来
• UNFORMATTED_VALUE 返回的是数字，而不是 "N/A" 之类的文本——请在 Code 节点中显式过滤

Google Drive

• convertToGoogleDocument: true 会创建 Google 文档（文本），而不是 Google 表格——若要上传 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. 节点执行顺序

问题：节点执行顺序与预期不符

解决方案：检查工作流设置 → 执行顺序

• 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. Set (map form fields)
3. Slack (post message to #notifications)

示例 2：定时报表

1. Schedule (daily at 9 AM)
2. HTTP Request (fetch analytics)
3. Code (aggregate data)
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)
3. Split In Batches (process 100 at a time)
4. Set (transform user data)
5. Postgres (upsert users)
6. Loop (back to step 3 until done)

---

详细模式文件

如需了解每种模式的全面指导：

• 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 Agents：使用量持续增长

• 最常见场景：聊天机器人、内容生成、数据分析

使用 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 - 配置特定操作