chore: import zh skill workflow-orchestration-patterns
This commit is contained in:
wehub-skill-sync
@@ -0,0 +1,9 @@
|
||||
# WeHub 来源说明
|
||||
|
||||
- Skill 名称：`workflow-orchestration-patterns`
|
||||
- 中文类目：分布式长事务工作流与 Saga 编排
|
||||
- 上游仓库：`wshobson__agents`
|
||||
- 上游路径：`plugins/backend-development/skills/workflow-orchestration-patterns/SKILL.md`
|
||||
- 上游链接：https://github.com/wshobson/agents/blob/HEAD/plugins/backend-development/skills/workflow-orchestration-patterns/SKILL.md
|
||||
- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理
|
||||
- 原作者、版权和许可证信息以上游仓库为准
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
|
||||
|
||||
---
|
||||
name: workflow-orchestration-patterns
|
||||
description: 使用 Temporal 为分布式系统设计持久化工作流。涵盖工作流与活动分离、Saga 模式、状态管理和确定性约束。在构建长时间运行的进程、分布式事务或微服务编排时使用。
|
||||
---
|
||||
|
||||
# 工作流编排模式
|
||||
|
||||
掌握基于 Temporal 的工作流编排架构，涵盖基础设计决策、弹性模式以及构建可靠分布式系统的最佳实践。
|
||||
|
||||
## 何时使用工作流编排
|
||||
|
||||
### 理想用例（来源：docs.temporal.io）
|
||||
|
||||
- **多步骤流程**：跨机器/服务/数据库执行
|
||||
- **分布式事务**：需要全有或全无语义
|
||||
- **长时间运行的工作流**（数小时到数年）：自动持久化状态
|
||||
- **故障恢复**：必须从上一步成功处恢复执行
|
||||
- **业务流程**：预订、订单、营销活动、审批
|
||||
- **实体生命周期管理**：库存追踪、账户管理、购物车工作流
|
||||
- **基础设施自动化**：CI/CD 流水线、资源调配、部署
|
||||
- **人工介入**系统：需要超时和升级机制
|
||||
|
||||
### 何时不应使用
|
||||
|
||||
- 简单的 CRUD 操作（使用直接 API 调用）
|
||||
- 纯数据处理流水线（使用 Airflow、批处理）
|
||||
- 无状态请求/响应（使用标准 API）
|
||||
- 实时流处理（使用 Kafka、事件处理器）
|
||||
|
||||
## 详细模式与工作示例
|
||||
|
||||
详细模式文档位于 `references/details.md`。当上述导航层级不够用时，请阅读该文件。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 工作流设计
|
||||
|
||||
1. **保持工作流聚焦**——每个工作流单一职责
|
||||
2. **小型工作流**——使用子工作流实现可扩展性
|
||||
3. **明确边界**——工作流负责编排，活动负责执行
|
||||
4. **本地测试**——使用时间跳跃测试环境
|
||||
|
||||
### 活动设计
|
||||
|
||||
1. **幂等操作**——可安全重试
|
||||
2. **短生命周期**——持续数秒到数分钟，而非数小时
|
||||
3. **超时配置**——始终设置超时
|
||||
4. **长时间任务发送心跳**——上报进度
|
||||
5. **错误处理**——区分可重试与不可重试错误
|
||||
|
||||
### 常见陷阱
|
||||
|
||||
**工作流违规**：
|
||||
|
||||
- 使用 `datetime.now()` 而非 `workflow.now()`
|
||||
- 在工作流代码中使用线程或异步操作
|
||||
- 从工作流中直接调用外部 API
|
||||
- 工作流中包含非确定性逻辑
|
||||
|
||||
**活动错误**：
|
||||
|
||||
- 非幂等操作（无法处理重试）
|
||||
- 缺少超时设置（活动永远运行）
|
||||
- 没有错误分类（重试验证错误）
|
||||
- 忽略负载大小限制（每个参数 2MB）
|
||||
|
||||
### 运维考量
|
||||
|
||||
**监控**：
|
||||
|
||||
- 工作流执行时长
|
||||
- 活动失败率
|
||||
- 重试次数与回退策略
|
||||
- 待处理工作流数量
|
||||
|
||||
**可扩展性**：
|
||||
|
||||
- 通过 Worker 水平扩展
|
||||
- 任务队列分区
|
||||
- 子工作流分解
|
||||
- 在适当情况下进行活动批处理
|
||||
|
||||
## 更多资源
|
||||
|
||||
**官方文档**：
|
||||
|
||||
- Temporal 核心概念：docs.temporal.io/workflows
|
||||
- 工作流模式：docs.temporal.io/evaluate/use-cases-design-patterns
|
||||
- 最佳实践：docs.temporal.io/develop/best-practices
|
||||
- Saga 模式：temporal.io/blog/saga-pattern-made-easy
|
||||
|
||||
**关键原则**：
|
||||
|
||||
1. 工作流 = 编排，活动 = 外部调用
|
||||
2. 确定性对工作流来说不可妥协
|
||||
3. 幂等性对活动来说至关重要
|
||||
4. 状态持久化是自动的
|
||||
5. 为故障和恢复而设计
|
||||
@@ -0,0 +1,229 @@
|
||||
---
|
||||
name: workflow-orchestration-patterns
|
||||
version: 1.0.0
|
||||
license: MIT
|
||||
---
|
||||
|
||||
# 工作流编排模式 —— 详细模式与实操示例
|
||||
|
||||
## 关键设计决策：工作流 vs 活动
|
||||
|
||||
**基本原则**（来源：temporal.io/blog/workflow-engine-principles）：
|
||||
|
||||
- **工作流** = 编排逻辑与决策
|
||||
- **活动** = 外部交互（API、数据库、网络调用）
|
||||
|
||||
### 工作流（编排）
|
||||
|
||||
**特征：**
|
||||
|
||||
- 包含业务逻辑与协调
|
||||
- **必须具有确定性**（相同输入 → 相同输出）
|
||||
- **不能**直接进行外部调用
|
||||
- 状态在故障时自动保留
|
||||
- 即使基础设施发生故障，也可运行数年
|
||||
|
||||
**工作流示例任务：**
|
||||
|
||||
- 决定执行哪些步骤
|
||||
- 处理补偿逻辑
|
||||
- 管理超时与重试
|
||||
- 协调子工作流
|
||||
|
||||
### 活动（外部交互）
|
||||
|
||||
**特征：**
|
||||
|
||||
- 处理所有外部系统交互
|
||||
- 可以是非确定性的（API 调用、数据库写入）
|
||||
- 内置超时与重试逻辑
|
||||
- **必须是幂等的**（调用 N 次 = 调用一次）
|
||||
- 生命周期短（通常数秒至数分钟）
|
||||
|
||||
**活动示例任务：**
|
||||
|
||||
- 调用支付网关 API
|
||||
- 写入数据库
|
||||
- 发送电子邮件或通知
|
||||
- 查询外部服务
|
||||
|
||||
### 设计决策框架
|
||||
|
||||
```
|
||||
是否涉及外部系统？→ 活动
|
||||
是否为编排/决策逻辑？→ 工作流
|
||||
```
|
||||
|
||||
## 核心工作流模式
|
||||
|
||||
### 1. Saga 模式与补偿
|
||||
|
||||
**目的**：实现分布式事务，具备回滚能力
|
||||
|
||||
**模式**（来源：temporal.io/blog/compensating-actions-part-of-a-complete-breakfast-with-sagas）：
|
||||
|
||||
```
|
||||
每个步骤：
|
||||
1. 在执行之前先注册补偿
|
||||
2. 执行该步骤（通过活动）
|
||||
3. 失败时，按相反顺序（后进先出）运行所有补偿
|
||||
```
|
||||
|
||||
**示例：支付工作流**
|
||||
|
||||
1. 预留库存（补偿：释放库存）
|
||||
2. 扣款（补偿：退款）
|
||||
3. 履约订单（补偿：取消履约）
|
||||
|
||||
**关键要求：**
|
||||
|
||||
- 补偿操作必须是幂等的
|
||||
- 在执行步骤之前先注册补偿
|
||||
- 按相反顺序运行补偿
|
||||
- 优雅处理部分失败
|
||||
|
||||
### 2. 实体工作流（Actor 模型）
|
||||
|
||||
**目的**：代表单个实体实例的长期运行工作流
|
||||
|
||||
**模式**（来源：docs.temporal.io/evaluate/use-cases-design-patterns）：
|
||||
|
||||
- 一个工作流执行 = 一个实体（购物车、账户、库存项）
|
||||
- 工作流在实体生命周期内持续存在
|
||||
- 通过信号接收状态变更
|
||||
- 支持通过查询获取当前状态
|
||||
|
||||
**使用场景示例：**
|
||||
|
||||
- 购物车（添加商品、结账、过期）
|
||||
- 银行账户（存款、取款、余额查询）
|
||||
- 产品库存（库存更新、预订）
|
||||
|
||||
**优势：**
|
||||
|
||||
- 封装实体行为
|
||||
- 保证每个实体的一致性
|
||||
- 天然的事件溯源
|
||||
|
||||
### 3. 扇出/扇入（并行执行）
|
||||
|
||||
**目的**：并行执行多个任务，汇总结果
|
||||
|
||||
**模式：**
|
||||
|
||||
- 启动子工作流或并行活动
|
||||
- 等待所有任务完成
|
||||
- 汇总结果
|
||||
- 处理部分失败
|
||||
|
||||
**扩缩规则**（来源：temporal.io/blog/workflow-engine-principles）：
|
||||
|
||||
- 不要扩缩单个工作流
|
||||
- 对于 100 万个任务：启动 1K 个子工作流 × 每个处理 1K 个任务
|
||||
- 使每个工作流的规模有界
|
||||
|
||||
### 4. 异步回调模式
|
||||
|
||||
**目的**：等待外部事件或人工审批
|
||||
|
||||
**模式：**
|
||||
|
||||
- 工作流发送请求并等待信号
|
||||
- 外部系统异步处理
|
||||
- 发送信号以恢复工作流
|
||||
- 工作流继续处理响应
|
||||
|
||||
**使用场景：**
|
||||
|
||||
- 人工审批工作流
|
||||
- Webhook 回调
|
||||
- 长时间运行的外部进程
|
||||
|
||||
## 状态管理与确定性
|
||||
|
||||
### 自动状态保留
|
||||
|
||||
**Temporal 的工作原理**（来源：docs.temporal.io/workflows）：
|
||||
|
||||
- 完整程序状态自动保留
|
||||
- 事件历史记录每个命令和事件
|
||||
- 从崩溃中无缝恢复
|
||||
- 应用程序恢复到故障前状态
|
||||
|
||||
### 确定性约束
|
||||
|
||||
**工作流作为状态机执行**：
|
||||
|
||||
- 重放行为必须一致
|
||||
- 相同输入 → 每次相同输出
|
||||
|
||||
**工作流中禁止的操作**（来源：docs.temporal.io/workflows）：
|
||||
|
||||
- ❌ 线程、锁、同步原语
|
||||
- ❌ 随机数生成（`random()`）
|
||||
- ❌ 全局状态或静态变量
|
||||
- ❌ 系统时间（`datetime.now()`）
|
||||
- ❌ 直接文件 I/O 或网络调用
|
||||
- ❌ 非确定性库
|
||||
|
||||
**工作流中允许的操作**：
|
||||
|
||||
- ✅ `workflow.now()`（确定性时间）
|
||||
- ✅ `workflow.random()`（确定性随机数）
|
||||
- ✅ 纯函数与计算
|
||||
- ✅ 调用活动（非确定性操作）
|
||||
|
||||
### 版本化策略
|
||||
|
||||
**挑战**：在旧执行仍在运行时修改工作流代码
|
||||
|
||||
**解决方案：**
|
||||
|
||||
1. **版本化 API**：使用 `workflow.get_version()` 进行安全变更
|
||||
2. **新的工作流类型**：创建新工作流，将新执行路由到它
|
||||
3. **向后兼容**：确保旧事件能正确重放
|
||||
|
||||
## 弹性与错误处理
|
||||
|
||||
### 重试策略
|
||||
|
||||
**默认行为**：Temporal 会无限重试活动
|
||||
|
||||
**配置重试：**
|
||||
|
||||
- 初始重试间隔
|
||||
- 退避系数（指数退避）
|
||||
- 最大间隔（重试延迟上限）
|
||||
- 最大尝试次数（最终失败）
|
||||
|
||||
**不可重试的错误：**
|
||||
|
||||
- 无效输入（校验失败）
|
||||
- 业务规则违反
|
||||
- 永久性失败（资源未找到）
|
||||
|
||||
### 幂等性要求
|
||||
|
||||
**为何至关重要**（来源：docs.temporal.io/activities）：
|
||||
|
||||
- 活动可能被执行多次
|
||||
- 网络故障会触发重试
|
||||
- 重复执行必须是安全的
|
||||
|
||||
**实现策略：**
|
||||
|
||||
- 幂等键（去重）
|
||||
- 先检查再执行 + 唯一约束
|
||||
- 使用更新插入操作替代插入
|
||||
- 跟踪已处理的请求 ID
|
||||
|
||||
### 活动心跳
|
||||
|
||||
**目的**：检测停滞的长时间运行活动
|
||||
|
||||
**模式：**
|
||||
|
||||
- 活动定期发送心跳
|
||||
- 包含进度信息
|
||||
- 若未收到心跳则超时
|
||||
- 支持基于进度的重试
|
||||
Reference in New Issue
Block a user