n8n-workflow-patterns

n8n 工作流模式

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

适用场景

• 构建工作流之前，需要为 n8n 工作流选择架构模式。
• 任务涉及 Webhook 处理、API 集成、定时任务、数据库同步或 AI Agent 工作流设计。
• 你想了解高层次的工作流结构，而非逐节点排查问题。

---

5 种核心模式

常见设计模式：

1. Webhook 处理

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

2. [HTTP API 集成]

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

3. 数据库操作

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

4. AI Agent 工作流

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

5. 定时任务

   • 定期运行的自动化工作流
   • 模式：计划任务 → 获取 → 处理 → 发送 → 记录

---

模式选择指南

各模式的适用场景：

Webhook 处理 - 适用于：

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

HTTP API 集成 - 适用于：

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

数据库操作 - 适用于：

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

AI Agent 工作流 - 适用于：

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

定时任务 - 适用于：

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

---

常见工作流组件

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

1. 触发器

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

2. 数据源

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

3. 转换

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

4. 输出

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

5. 错误处理

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

激活前，请确认凭据权限范围、目标收件人以及付费/API 调用的影响。对 Webhook 进行身份验证，验证负载，去重投递 ID，并使用幂等写入。重试时应限制次数并采用退避策略；超时可能发生在副作用已成功之后。限制 AI 工具的权限，并将检索到的内容视为不可信数据。Error Trigger 应用于单独配置的错误工作流，而非主工作流中的普通分支。顺序分支不一定会并发执行。

工作流创建检查清单

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

规划阶段

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

实施阶段

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

验证阶段

• 验证每个节点的配置（validate_node）
• 验证完整工作流（validate_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]

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

---

常见注意事项

1. Webhook 数据结构

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

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

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

参见：n8n Expression Syntax 技能

2. 多个输入项

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

解决方案：使用“Execute Once”模式，或仅处理第一个项

{{$input.first().json.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）
• 使用 ai_agents_guide 获取 AI 模式指导

n8n Expression Syntax——用于：

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

n8n Node Configuration——用于：

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

n8n Validation Expert——用于：

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

---

证据与版本范围

这些模式是设计启发式方法，并非经测量得出的使用统计数据。此处未附带用于确定普及程度、百分比或平均编辑时间的数据集或方法。节点名称和可用操作因安装的 n8n 和 MCP 版本而异。此处未附带后文列出的详细模式文件；请使用已安装的文档或 n8n 官方文档，不要声称已阅读这些文件。

---

快速入门示例

示例 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 - 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 查找示例！

---

最佳实践

✅ 应做事项

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

❌ 不应做事项

• 一次性构建工作流（应迭代并检查每项更改）
• 激活前跳过验证
• 忽略错误场景
• 在简单模式足以满足需求时使用复杂模式
• 在参数中硬编码凭据
• 忘记处理空数据情况
• 在没有明确界限的情况下混用多种模式
• 未经测试就部署

---

总结

要点：

1. 5 种核心模式提供起步结构
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 - 配置特定操作

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 请勿将输出视为环境专属验证、测试或专家审查的替代方案。
• 如果缺少必要输入、权限、安全边界或成功标准，请停止并请求澄清。