设计与评审 n8n 工作流的工程规范：输入输出契约、节点选型、四层错误处理、幂等去重、限流批量、凭据与 Webhook 安全、调试方法，以及可分享的导出规范。适用于从零搭一个自动化流程，或把「能跑」的流程改造成「敢上线」的流程。
下载这个 Skill 需要先登录（免费注册，只需用户名和密码）。去登录 →
按元信息、示例、可执行性、完整性等 13 项自动检查，供作者自查改进；不影响用户评分。
# n8n 工作流设计
n8n 里拖几个节点跑通一次很容易，难的是**数据重复时不出错、上游超时时能自愈、别人拿到你的 JSON 也能跑**。这个技能给出上线前的工程检查项。
## 何时启用
- 从零设计一个 Webhook / 定时 / 表单触发的自动化流程
- 评审别人分享的工作流 JSON，判断能不能直接用
- 线上流程偶发失败、数据重复、限流被封，需要定位原因
- 把内部流程整理成可分享的模板
## 一、先定契约，再连节点
动手前用三句话写清楚：
1. **触发**：谁在什么时机触发（Webhook / Schedule / Form / 邮件 / 其他系统事件）
2. **输入**：字段名、类型、是否必填、示例值
3. **输出**：写到哪（数据库 / 表格 / 消息 / 第三方 API），失败怎么让人知道
字段没定清楚就开始连节点，最后一定在 Code 节点里堆一堆 `if (!item.json.xxx)`。
## 二、节点选型速查
| 需求 | 首选 | 说明 |
| --- | --- | --- |
| 改动/新增字段 | Edit Fields (Set) | 优先于 Code，可读性最好 |
| 简单映射与拼接 | Edit Fields 表达式 | `{{ $json.user.name }}` 就够，不用写代码 |
| 多分支判断 | Switch | 不要用 IF 串联三层 |
| 逐条处理且要限速 | Loop Over Items（Split In Batches） | 配 Wait 节点控制节奏 |
| 聚合多条为一条 | Aggregate / Code | 汇总成数组再发一次请求 |
| 去重 | Remove Duplicates | 按业务主键，不要按整条 JSON |
| 失败可重试的外部调用 | HTTP Request + Retry On Fail | 指数退避，别无限重试 |
| 长任务等待外部回调 | Wait（Webhook 模式） | 不要用 Sleep 占着执行 |
## 三、四层错误处理（缺一层就不算上线）
1. **节点级**：给 HTTP / 数据库节点开 `Retry On Fail`，重试 3 次、间隔递增（如 2s / 8s / 30s）。只对幂等操作开重试。
2. **分支级**：非关键步骤用 `On Error → Continue`，把错误信息塞进字段继续走，最后统一汇总（不要整条流程挂掉）。
3. **流程级**：单独建一个 **Error Trigger 工作流**，接收所有失败事件，统一发通知（邮件 / 群消息），带上执行 ID、节点名、错误摘要、原始输入。
4. **业务级**：死信兜底——重试仍失败的记录写入一张「待人工处理」表，附上失败原因，不要静默丢弃。
> 判断标准：**如果这个流程半夜挂了，第二天早上你能不能知道是哪条数据没处理？** 答不上来就是第 3、4 层没做。
## 四、幂等与去重
Webhook 重投、定时任务重叠、人工重复点击，都会造成重复写入。
- **幂等键**：用业务唯一标识（订单号、消息 ID、`hash(用户+日期+类型)`），不要用时间戳。
- **先查后写**：写入前按幂等键查一次；或用数据库唯一索引兜底（`INSERT ... ON DUPLICATE KEY`）。
- **去重窗口**：Remove Duplicates 按幂等键保留首次出现，注意它对内存的占用，条数大时先分批。
- **重跑安全**：任何一步都能从头重跑而不产生脏数据，这条比"跑得快"重要。
## 五、限流与批量
- 第三方 API 有速率限制时：批量接口优先（一次 50 条 > 50 次单条），并用 Loop + Wait 控制 QPS。
- 大批量数据分页拉取：用 `limit` + 游标，不要一次拉全量。
- 单次执行数据量超过几千条时，考虑拆成「调度工作流 + 处理工作流」，避免单次执行超时。
## 六、凭据与安全
- **密钥一律放 Credentials**，不要写进节点参数、Code 节点或导出的 JSON。
- Webhook 对外暴露时至少加一层校验：Header Auth（`X-Webhook-Token`）、签名校验（HMAC + 时间戳防重放）或 IP 白名单。
- 生产环境的 Webhook 用 POST，GET 容易被爬虫和预取触发。
- 分享 JSON 前检查：Credential 引用、内部域名、测试用邮箱、真实用户数据。
## 七、调试方法
1. **Pin Data**：把上游节点输出固定住，只调后面的节点，避免每次重跑外部请求。
2. **单步执行**：从出错节点往前看输入，八成问题在输入数据结构，不在节点本身。
3. **看执行记录**：Executions 里对比成功与失败的输入差异，比读日志快。
4. **打印结构**：不确定结构时，先用 Edit Fields 输出 `{{ JSON.stringify($json) }}`，看清楚字段再写表达式。
5. **常见坑**：上游返回空数组时后续节点不执行；`$json` 与 `$node["X"].json` 混用导致取到错误条目的数据；Item linking 断裂后 Code 节点只拿到第一条。
## 八、导出与分享规范
给别人用的工作流 JSON，要做到「导入即懂」：
- 节点命名用业务语言：`校验订单` 而不是 `IF1`、`HTTP Request3`。
- 每个逻辑段加一个 **Sticky Note**，一句话说明这段在干什么。
- 顶部留一个说明节点：用途、触发方式、需要哪些凭据、预期输出。
- 依赖外部接口的，标注接口文档链接和字段含义。
- 需要用户自己填的地方用显眼的占位符：`YOUR_API_KEY`、`https://example.com/webhook`。
- 附一段最小示例输入，方便对方 Pin Data 调试。
## 九、上线前检查清单
- [ ] 触发方式、输入字段、输出位置写清楚了吗
- [ ] 外部调用是否开了重试，是否只对幂等操作开
- [ ] 有没有 Error Trigger 工作流，失败会通知到人吗
- [ ] 失败数据有没有兜底表，会不会静默丢失
- [ ] 重复投递会不会写重复数据，幂等键是什么
- [ ] 批量场景有没有限流，会不会被第三方封
- [ ] 密钥是否都在 Credentials 里
- [ ] Webhook 是否有鉴权，是否用 POST
- [ ] 节点命名、注释是否让人看得懂
- [ ] 空数据、异常字段、超时三种情况各跑过一次了吗
## 反模式清单
- ❌ 一个 Code 节点干完所有事（不可读、不可调试）
- ❌ 用 `Sleep` / 长 Wait 占住执行等外部回调
- ❌ 重试失败也不告警，靠用户投诉发现问题
- ❌ 把 API Key 直接写在 HTTP 节点的 Header 里
- ❌ 用时间戳当幂等键（重试必然重复）
- ❌ 分享的 JSON 里带着自己的凭据和测试数据