workflow-orchestration-patterns

ワークフローオーケストレーションのパターン

Temporal を使用したワークフローオーケストレーションのアーキテクチャを習得し、信頼性の高い分散システムを構築するための基本的な設計上の決定、レジリエンスパターン、ベストプラクティスについて学びます。

このスキルを使用する場合

• ワークフローオーケストレーションのパターンに関するタスクやワークフローに取り組む場合
• ワークフローオーケストレーションのパターンについて、ガイダンス、ベストプラクティス、チェックリストが必要な場合

このスキルを使用しない場合

• タスクがワークフローオーケストレーションのパターンに関係しない場合
• 対象範囲外の別の分野やツールが必要な場合

手順

• 目標、制約、必要な入力を明確にします。
• 関連するベストプラクティスを適用し、結果を検証します。
• 実行可能な手順と検証方法を提示します。

ワークフローオーケストレーションを使用する場面

最適なユースケース（出典：docs.temporal.io）

• 複数ステップのプロセス：マシン／サービス／データベースにまたがるプロセス
• 分散トランザクション：全成功か全失敗かのセマンティクスが必要な処理
• 長時間実行されるワークフロー：状態が自動的に永続化される、数時間から数年に及ぶ処理
• 障害復旧：最後に成功したステップから再開する必要がある処理
• ビジネスプロセス：予約、注文、キャンペーン、承認
• エンティティのライフサイクル管理：在庫追跡、アカウント管理、カートのワークフロー
• インフラストラクチャの自動化：CI/CD パイプライン、プロビジョニング、デプロイ
• 人間が介在するシステム：タイムアウトやエスカレーションが必要なシステム

使用しない場面

• 単純な CRUD 操作（直接 API 呼び出しを使用します）
• 純粋なデータ処理パイプライン（Airflow またはバッチ処理を使用します）
• ステートレスなリクエスト／レスポンス（標準 API を使用します）
• リアルタイムストリーミング（Kafka またはイベントプロセッサーを使用します）

重要な設計上の決定：ワークフローとアクティビティ

基本ルール（出典：temporal.io/blog/workflow-engine-principles）：

• ワークフロー＝オーケストレーションロジックと意思決定
• アクティビティ＝外部とのやり取り（API、データベース、ネットワーク呼び出し）

ワークフロー（オーケストレーション）

特性：

• ビジネスロジックと調整を含みます
• 決定論的でなければなりません（同じ入力 → 同じ出力）
• 外部システムを直接呼び出すことはできません
• 障害が発生しても状態は自動的に保持されます
• インフラストラクチャに障害が発生しても、何年にもわたって実行できます

ワークフロータスクの例：

• 実行するステップを決定する
• 補償ロジックを処理する
• タイムアウトと再試行を管理する
• 子ワークフローを調整する

アクティビティ（外部とのやり取り）

特性：

• 外部システムとのすべてのやり取りを処理します
• 非決定的でもかまいません（API 呼び出し、DB 書き込み）
• タイムアウトと再試行ロジックが組み込まれています
• 冪等でなければなりません（N 回呼び出しても 1 回呼び出した場合と同じ結果になります）
• 通常は短時間（数秒から数分）で完了します

アクティビティタスクの例：

• 決済ゲートウェイ API を呼び出す
• データベースに書き込む
• メールや通知を送信する
• 外部サービスにクエリを送信する

設計上の判断フレームワーク

Does it touch external systems? → Activity
Is it orchestration/decision logic? → Workflow

ワークフローの主要なパターン

1. 補償を伴う Saga パターン

目的：ロールバック機能を備えた分散トランザクションを実装します

パターン（出典：temporal.io/blog/compensating-actions-part-of-a-complete-breakfast-with-sagas）：

For each step:
  1. Register compensation BEFORE executing
  2. Execute the step (via activity)
  3. On failure, run all compensations in reverse order (LIFO)

例：決済ワークフロー

1. 在庫を確保する（補償：在庫を解放する）
2. 決済を請求する（補償：返金する）
3. 注文を履行する（補償：履行を取り消す）

重要な要件：

• 補償処理は冪等でなければなりません
• ステップを実行する前に補償処理を登録します
• 補償処理は逆順で実行します
• 部分的な障害を適切に処理します

2. エンティティワークフロー（アクターモデル）

目的：単一のエンティティインスタンスを表す、長期間実行されるワークフローです。

パターン（出典：docs.temporal.io/evaluate/use-cases-design-patterns）：

• 1つのワークフロー実行が1つのエンティティ（カート、アカウント、在庫品目）に対応します
• ワークフローはエンティティの存続期間中、実行され続けます
• 状態変更のシグナルを受け取ります
• 現在の状態を照会できます

ユースケースの例：

• ショッピングカート（商品の追加、購入手続き、有効期限切れ）
• 銀行口座（入金、出金、残高照会）
• 商品在庫（在庫数の更新、取り置き）

利点：

• エンティティの振る舞いをカプセル化します
• エンティティごとの一貫性を保証します
• イベントソーシングに自然に対応します

3. ファンアウト／ファンイン（並列実行）

目的：複数のタスクを並列実行し、結果を集約します。

パターン：

• 子ワークフローまたは並列アクティビティを起動します
• すべての完了を待ちます
• 結果を集約します
• 部分的な失敗に対処します

スケーリングルール（出典：temporal.io/blog/workflow-engine-principles）：

• 個々のワークフローをスケールさせないでください
• 100万件のタスクには、1,000個の子ワークフローを起動し、それぞれで1,000件のタスクを処理します
• 各ワークフローの処理範囲を限定します

4. 非同期コールバックパターン

目的：外部イベントまたは人による承認を待ちます。

パターン：

• ワークフローがリクエストを送信して、シグナルを待ちます
• 外部システムが非同期で処理します
• ワークフローを再開するシグナルを送信します
• ワークフローが応答を受けて処理を続行します

ユースケース：

• 人による承認ワークフロー
• Webhook コールバック
• 長時間実行される外部プロセス

状態管理と決定性

状態の自動保持

Temporal の仕組み（出典：docs.temporal.io/workflows）：

• プログラムの状態全体が自動的に保持されます
• イベント履歴にすべてのコマンドとイベントが記録されます
• クラッシュからシームレスに復旧します
• アプリケーションは障害発生前の状態を復元します

決定性の制約

ワークフローはステートマシンとして実行されます：

• リプレイ時の動作は一貫している必要があります
• 同じ入力からは、毎回同一の出力が得られます

ワークフローで禁止されている操作（出典：docs.temporal.io/workflows）：

• ❌ スレッド処理、ロック、同期プリミティブ
• ❌ 乱数生成（random()）
• ❌ グローバル状態または静的変数
• ❌ システム時刻（datetime.now()）
• ❌ 直接のファイル I/O またはネットワーク呼び出し
• ❌ 非決定的なライブラリ

ワークフローで許可されている操作：

• ✅ workflow.now()（決定的な時刻）
• ✅ workflow.random()（決定的な乱数）
• ✅ 純粋関数と計算
• ✅ アクティビティの呼び出し（非決定的な操作）

バージョニング戦略

課題：古い実行が継続中にワークフローコードを変更すること

解決策：

1. バージョニング API：プロシージャを実際の SDK 言語とインストール済みのバージョンに合わせてください。Python では workflow.patched／workflow.deprecate_patch を使用します。他の SDK では API が異なります。デプロイ前に既存の履歴をリプレイし、Python の公式バージョニングガイダンスに従ってください。
2. 新しいワークフロータイプ：新しいワークフローを作成し、新しい実行をそちらに振り分けます
3. 後方互換性：古いイベントを正しくリプレイできるようにします

レジリエンスとエラー処理

リトライポリシー

デフォルトの動作：Temporal はアクティビティを無期限にリトライします。

リトライの設定：

• 初回リトライまでの間隔
• バックオフ係数（指数バックオフ）
• 最大間隔（リトライ間隔の上限）
• 最大試行回数（最終的に失敗します）

リトライ対象外のエラー：

• 無効な入力（検証エラー）
• ビジネスルール違反
• 恒久的な障害（リソースが見つからない）

冪等性の要件

重要な理由（出典：docs.temporal.io/activities）：

• アクティビティは複数回実行される場合があります
• ネットワーク障害によってリトライが発生します
• 重複実行が安全でなければなりません

実装方法：

• 冪等性キー（重複排除）
• 一意制約を使用した確認後の処理
• INSERT の代わりに UPSERT 操作を使用
• 処理済みのリクエスト ID を追跡

アクティビティのハートビート

目的：長時間実行されるアクティビティの停滞を検出します。

パターン：

• アクティビティが定期的にハートビートを送信します
• 進捗情報を含めます
• ハートビートを受信できない場合はタイムアウトします
• 進捗に基づく再試行を可能にします

ベストプラクティス

ワークフローの設計

1. ワークフローの役割を絞る - 各ワークフローの責任を1つにします
2. ワークフローを小さく保つ - スケーラビリティのために子ワークフローを使用します
3. 境界を明確にする - ワークフローがオーケストレーションを行い、アクティビティが実行します
4. ローカルでテストする - 時間をスキップできるテスト環境を使用します

アクティビティの設計

1. 冪等な操作 - 安全に再試行できます
2. 短時間で完了する - 数秒から数分程度とし、数時間かかる処理は避けます
3. タイムアウトを設定する - 必ずタイムアウトを設定します
4. 長時間のタスクにはハートビートを使用する - 進捗を報告します
5. エラーを処理する - 再試行可能なエラーと再試行不可能なエラーを区別します

よくある落とし穴

ワークフローでの違反：

• workflow.now() ではなく datetime.now() を使用する
• ワークフローコード内でスレッド処理や非同期処理を行う
• ワークフローから外部 API を直接呼び出す
• ワークフロー内で非決定的なロジックを使用する

アクティビティでの誤り：

• 冪等でない操作（再試行に対応できない）
• タイムアウトの設定漏れ（アクティビティが無期限に実行される）
• エラー分類がない（検証エラーを再試行してしまう）
• ペイロードの上限を無視する（引数ごとに 2MB）

運用上の考慮事項

モニタリング：

• ワークフローの実行時間
• アクティビティの失敗率
• 再試行回数とバックオフ
• 保留中のワークフロー数

スケーラビリティ：

• ワーカーによる水平スケーリング
• タスクキューの分割
• 子ワークフローへの分解
• 適切にアクティビティをバッチ処理する

追加リソース

公式ドキュメント：

• 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. 障害と復旧を想定して設計します

制限事項

• このスキルは、タスクが上記の説明範囲に明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。