n8n-workflow-patterns

n8n 工作流模式

用于构建 n8n 工作流的经过验证的架构模式。

---

6 种核心模式

基于对真实工作流使用情况的分析：

1. Webhook 处理（最常见）

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

2. HTTP API 集成

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

3. 数据库操作

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

4. AI 智能体工作流

   • 带工具和记忆的 AI 智能体
   • 模式：触发器 → AI 智能体（模型 + 工具 + 记忆）→ 输出

5. 定时任务

   • 重复执行的自动化工作流
   • 模式：定时 → 获取 → 处理 → 交付 → 日志

6. 批处理（见下文）

   • 分块处理大数据集，遵守 API 速率限制
   • 模式：准备 → 分批处理 → 逐批处理 → 累积 → 聚合

---

模式选择指南

何时使用每种模式：

Webhook 处理 - 在以下情况使用：

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

HTTP API 集成 - 在以下情况使用：

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

数据库操作 - 在以下情况使用：

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

AI 智能体工作流 - 在以下情况使用：

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

定时任务 - 在以下情况使用：

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

批处理 - 在以下情况使用：

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

---

常见工作流组件

所有模式共享以下构建块：

1. 触发器

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

2. 数据源

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

3. 转换

• 设置 - 映射/转换字段
• 代码 - 复杂逻辑
• IF/开关 - 条件路由
• 合并 - 合并数据流

4. 输出

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

5. 错误处理

• 错误触发器 - 捕获工作流错误
• IF - 检查错误条件
• 停止并报错 - 显式失败
• 失败时继续 - 每个节点的设置

---

工作流创建清单

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

规划阶段

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

实施阶段

• [ ] 使用适当的触发器创建工作流
• [ ] 添加数据源节点
• [ ] 配置认证/凭据
• [ ] 添加转换节点（设置、代码、IF）
• [ ] 添加输出/操作节点
• [ ] 配置错误处理

验证阶段

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

部署阶段

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

---

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

构建节点只是开始，不是结束。在工作流上线之前，需要通过四道关卡——并记住首要规则：验证通过是必要条件，但不是充分条件。 一个工作流可以验证通过但仍然丢失项目、选择错误的合并输入、或以纯文本形式发布 Slack 消息。干净的验证意味着形状正确，而不是逻辑正确。

1. 验证。 在构建期间对完整 JSON 运行 validate_workflow，或者在工作流存在于实例上后运行 n8n_validate_workflow({ id })。修复每个错误并重新验证。这可以捕获模式、节点配置、表达式和引用错误——结构层。
2. 核实连接。 使用 n8n_get_workflow({ id }) 拉取工作流并直接读取 connections 对象。验证确认连接没有断开；它不确认连接正确。这是捕获有效但错误接线的地方：useDataOfInput 与连接槽不匹配的合并、连接到空处的开关回退、从未向前接线的扇出分支、无处可去的错误输出。（参见 n8n 节点配置技能的 NODE_FAMILY_GOTCHAS.md 了解静默问题。）
3. 测试。 运行 n8n_test_workflow 并通过 n8n_executions 检查输出。确认输出形状符合消费者预期，扇出分支都产生了数据，并且（对于 Webhook API）状态/主体/标头正确。测试期间真实的副作用会触发——写入提交、消息发送、外部 API 被调用。如果任何节点有用户可见的副作用，请在运行前与用户确认，或先针对安全数据进行测试。
4. 仅在前三步通过后激活——使用带有 activateWorkflow 操作的 n8n_update_partial_workflow。不要在仅通过干净验证后直接激活；一个活跃但丢失数据或重复发送的工作流比从未启动的更糟糕。

跳过任何一道关卡，都是用现在的几分钟换取以后调试一个可能状态化、可能承载流量的工作流。这种交换永远不值得。

---

数据流模式

线性流

触发器 → 转换 → 操作 → 结束

使用场景：具有单一路径的简单工作流

分支流

触发器 → IF → [真路径]
             └→ [假路径]

使用场景：基于条件执行不同操作

并行处理

触发器 → [分支 1] → 合并
       └→ [分支 2] ↗

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

循环模式

触发器 → 分批处理 → 处理 → 循环（直到完成）

使用场景：分块处理大数据集

错误处理器模式

主流程 → [成功路径]
         └→ [错误触发器 → 错误处理器]

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

---

批处理模式

SplitInBatches 循环

SplitInBatches 节点将大数据集拆分为更小的块进行处理。理解其输出至关重要：

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

准备项目 → SplitInBatches → [main[1]: 处理批次] →（循环回）
                              [main[0]: 完成] → 限制 1 → 聚合

始终在完成输出后添加一个限制 1 节点。

选择 batchSize（成本杠杆）

SplitInBatches 循环每次迭代都会重新运行整个循环体——约 0.8 毫秒/迭代的引擎开销加上循环体自身的成本——因此总计 ≈ ⌈items / batchSize⌉ × (overhead + body)。batchSize 是一个直接的速度调节器：

• 选择实际约束允许的最大批次（API 页面大小、速率限制、内存）。更大的批次 = 更少的迭代 = 更少的开销；循环体仍然处理每个项目。
• batchSize: 1 是昂贵的极端——每个项目一次完整的引擎传递。仅当必须一次处理一个项目时使用（嵌套循环控制，或一次只接受一个 ID 的 API）。
• 如果循环只是为了“遍历项目”而没有外部约束，通常不需要循环——一个处理所有项目的代码节点成本更低。

跨迭代数据

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

嵌套循环

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

定义类别（N 个项目）
  → 外层循环（SplitInBatches，batchSize=1）
    → 准备类别数据
    → 内层循环（SplitInBatches，batchSize=1000）
      → API 调用 → 验证 →（通过 main[1] 循环回内层循环）
    → 内层完成[0] → 速率限制延迟 → 返回外层循环
  → 外层完成[0] → 限制 1 → 最终聚合

接线陷阱：内层完成[0]必须连接回外层循环输入，而不是聚合。外层完成[0]馈送到最终聚合。

API 分页

对于没有多 ID 过滤的 API，使用 id_from + 日期窗口进行高效分页：

定时 → 设置日期窗口 → 获取页面 → 处理
  → IF 还有更多？ → [true] 更新 id_from → 获取页面（循环）
                  → [false] → 聚合 → 输出

试运行/验证容错

当测试时 API 写入节点被禁用（用于试运行），下游验证节点会收到请求体而不是响应。使验证具有容错性：

// 在验证代码节点中
const body = $input.first().json;
const looksLikeRequest = body.method && body.parameters && !body.status;
if (looksLikeRequest) {
  return [{ json: { status: 'SKIPPED', message: '上游已禁用用于测试' }}];
}
// 下面进行正常响应验证...

---

热路径上的性能

当工作流处理数千个项目且 I/O 很少时，其速度由 n8n 跨越每个项目/每次迭代边界的次数决定——每次跨越都会设置执行上下文并复制项目。四个架构选择占主导地位：

1. 优先选择更少、更胖的处理所有项目的节点，而不是长的转换链。 每次节点→节点跳转都会重新复制所有项目（约 0.05 毫秒/项目/跳转），因此六个链式代码/设置节点的成本约为一个执行相同步骤的处理所有项目的代码节点的 7 倍。整合热路径。
2. 使用代码“对所有项目运行一次”，而不是“每个项目”——约 0.02 毫秒/项目对比约 0.6 毫秒/项目（约 25–30 倍）。每个项目代码节点的链是最坏情况；每个项目的开销乘以节点数量。
3. 最大化 SplitInBatches 循环中的 batchSize（参见上面的批处理模式）——迭代是成本所在。
4. 不要微优化表达式——复杂度是免费的；节点和迭代次数才是你付出的代价。

但先做性能分析。 大多数生产工作流是 I/O 密集型的——顺序的 HTTP/数据库/Sheets 调用（每个数百毫秒）使上述所有因素相形见绌。这些规则在转换工作是瓶颈时，或者当反模式（每个项目代码、batchSize 1、长的每个项目链）将廉价操作变成慢速操作时才重要。在几百个项目以下，这些都不重要。n8n Code JavaScript 技能有完整的测量模型。

---

集成特定陷阱

Google Sheets

• 永远不要对包含公式列的表格使用 append——它会破坏公式。使用 Google Sheets API values.update（PUT）通过 HTTP 请求节点和 googleApi 凭据
• 为依赖公式的列写入数字，而不是字符串——字符串 "4.98" 会破坏 ADD() 公式。在代码节点中使用 parseFloat()
• 每个项目执行陷阱：Google Sheets 节点每个输入项目执行一次。如果需要一次批量写入，先在代码节点中将项目聚合为一个
• UNFORMATTED_VALUE 返回数字，而不是像 "N/A" 这样的文本——在代码节点中显式过滤

Google Drive

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

双向阈值检查

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

// ❌ 仅捕获增加
if (diff > threshold) { flag(); }

// ✅ 同时捕获峰值和崩溃——两者都是数据质量信号
if (Math.abs(diff) > threshold) { flag(); }

---

常见陷阱

1. Webhook 数据结构

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

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

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

参见：n8n 表达式语法技能

2. 多个输入项目

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

解决方案：使用“执行一次”模式或仅处理第一个项目

{{$json[0].field}}  // 仅第一个项目

3. 认证问题

问题：API 调用返回 401/403

解决方案：

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

4. 节点执行顺序

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

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

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

5. 表达式错误

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

解决方案：在表达式周围使用 {{}}

• 参见 n8n 表达式语法技能了解详情

---

与其他技能的集成

这些技能与工作流模式协同工作：

n8n MCP 工具专家 - 用于：

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

n8n 表达式语法 - 用于：

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

n8n 节点配置 - 用于：

• 配置模式节点的特定操作
• 理解节点特定要求

n8n 验证专家 - 用于：

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

---

模式统计

常见工作流模式：

最常见的触发器：

1. Webhook - 35%
2. 定时（周期性任务） - 28%
3. 手动（测试/管理） - 22%
4. 服务触发器（Slack、邮件等） - 15%

最常见的转换：

1. 设置（字段映射） - 68%
2. 代码（自定义逻辑） - 42%
3. IF（条件路由） - 38%
4. 开关（多条件） - 18%

最常见的输出：

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

平均工作流复杂度：

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

---

快速入门示例

示例 1：简单 Webhook → Slack

1. Webhook（路径："form-submit"，POST）
2. 设置（映射表单字段）
3. Slack（向 #notifications 频道发布消息）

示例 2：定时报告

1. 定时（每天上午 9 点）
2. HTTP 请求（获取分析数据）
3. 代码（聚合数据）
4. 邮件（发送格式化报告）
5. 错误触发器 → Slack（失败时通知）

示例 3：数据库同步

1. 定时（每 15 分钟）
2. Postgres（查询新记录）
3. IF（检查记录是否存在）
4. MySQL（插入记录）
5. Postgres（更新同步时间戳）

示例 4：AI 助手

1. Webhook（接收聊天消息）
2. AI 智能体
   ├─ OpenAI 聊天模型（ai_languageModel）
   ├─ HTTP 请求工具（ai_tool）
   ├─ 数据库工具（ai_tool）
   └─ 窗口缓冲记忆（ai_memory）
3. Webhook 响应（发送 AI 回复）

示例 5：API 集成

1. 手动触发器（用于测试）
2. HTTP 请求（GET /api/users）
3. 分批处理（每次处理 100 个）
4. 设置（转换用户数据）
5. Postgres（upsert 用户）
6. 循环（返回步骤 3 直到完成）

---

详细模式文件

有关每种模式的全面指导：

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

---

真实模板示例

来自 n8n 模板库：

模板 #2947：天气到 Slack

• 模式：定时任务
• 节点：定时 → HTTP 请求（天气 API）→ 设置 → Slack
• 复杂度：简单（4 个节点）

Webhook 处理：最常见的模式

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

HTTP API：常见模式

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

数据库操作：常见模式

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

AI 智能体：使用量增长

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

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

---

最佳实践

✅ 要做

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

❌ 不要做

• 一次性构建工作流（迭代！编辑间平均 56 秒）
• 在激活前跳过验证
• 忽略错误场景
• 在简单模式足够时使用复杂模式
• 在参数中硬编码凭据
• 忘记处理空数据情况
• 混合多种模式而没有明确边界
• 未经测试就部署

---

总结

关键点：

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

下一步：

1. 确定你的用例模式
2. 阅读详细的模式文件
3. 使用 n8n MCP 工具专家查找节点
4. 遵循工作流创建清单
5. 使用 n8n 验证专家进行验证

相关技能：

• n8n MCP 工具专家 - 查找和配置节点
• n8n 表达式语法 - 正确编写表达式
• n8n 验证专家 - 验证和修复错误
• n8n 节点配置 - 配置特定操作