Workflow Orchestration Patterns

Temporal を使用したワークフロー オーケストレーション アーキテクチャをマスターし、基本的な設計判断、レジリエンス パターン、および信頼性の高い分散システム構築のベストプラクティスをカバーします。

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

理想的なユースケース (出典: docs.temporal.io)

• マルチステップ プロセス がマシン/サービス/データベースにまたがる場合
• 分散トランザクション がすべてが実行されるか何も実行されないかのセマンティクスを必要とする場合
• 長時間実行ワークフロー (数時間から数年) で自動的な状態永続化が必要な場合
• 障害復旧 が最後に成功したステップから再開する必要がある場合
• ビジネス プロセス: 予約、注文、キャンペーン、承認
• エンティティ ライフサイクル管理: 在庫追跡、アカウント管理、カート ワークフロー
• インフラストラクチャ自動化: CI/CD パイプライン、プロビジョニング、デプロイメント
• 人間参加システム がタイムアウトとエスカレーションを必要とする場合

使用しない場合

• シンプルな CRUD 操作 (直接 API 呼び出しを使用)
• 純粋なデータ処理パイプライン (Airflow やバッチ処理を使用)
• ステートレスな要求/応答 (標準 API を使用)
• リアルタイム ストリーミング (Kafka やイベント プロセッサを使用)

重要な設計判断: ワークフロー vs アクティビティ

基本ルール (出典: temporal.io/blog/workflow-engine-principles):

• ワークフロー = オーケストレーション ロジックと意思決定
• アクティビティ = 外部インタラクション (API、データベース、ネットワーク呼び出し)

ワークフロー (オーケストレーション)

特性:

• ビジネス ロジックと調整を含む
• 決定論的である必要があります (同じ入力 → 同じ出力)
• 直接外部呼び出しを実行できません
• 状態は障害全体で自動的に保持される
• インフラストラクチャ障害にもかかわらず数年実行できる

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

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

アクティビティ (外部インタラクション)

特性:

• すべての外部システム インタラクションを処理する
• 非決定論的にできる (API 呼び出し、DB 書き込み)
• 組み込みのタイムアウトと再試行ロジック
• べき等である必要があります (N 回呼び出す = 1 回呼び出す)
• 短命 (通常は秒から分)

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

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

設計判断フレームワーク

外部システムに接触するか? → アクティビティ
オーケストレーション/意思決定ロジックか? → ワークフロー

コア ワークフロー パターン

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

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

パターン (出典: temporal.io/blog/compensating-actions-part-of-a-complete-breakfast-with-sagas):

各ステップに対して:
  1. 実行する前に補償を登録する
  2. ステップを実行する (アクティビティ経由)
  3. 障害時に、すべての補償を逆順 (LIFO) で実行する

例: 支払いワークフロー

1. インベントリを予約 (補償: インベントリを解放)
2. 支払いを請求 (補償: 支払いを払い戻し)
3. 注文を履行 (補償: 履行をキャンセル)

重要な要件:

• 補償はべき等である必要がある
• ステップを実行する前に補償を登録する
• 補償を逆順で実行する
• 部分的な障害を適切に処理する

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

目的: 単一のエンティティ インスタンスを表す長時間実行ワークフロー

パターン (出典: docs.temporal.io/evaluate/use-cases-design-patterns):

• 1 つのワークフロー実行 = 1 つのエンティティ (カート、アカウント、在庫品)
• ワークフローはエンティティの存続期間中実行される
• 状態変化のシグナルを受信する
• 現在の状態をクエリできる

ユースケース例:

• ショッピング カート (アイテム追加、チェックアウト、有効期限)
• 銀行口座 (預金、出金、残高確認)
• 製品在庫 (在庫更新、予約)

メリット:

• エンティティ動作をカプセル化する
• エンティティごとの一貫性を保証する
• 自然なイベント ソーシング

3. Fan-Out/Fan-In (並列実行)

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

パターン:

• 子ワークフローまたは並列アクティビティをスポーンする
• すべての完了を待つ
• 結果を集約する
• 部分的な障害を処理する

スケーリング ルール (出典: temporal.io/blog/workflow-engine-principles):

• 個別のワークフローをスケーリングしない
• 100 万タスク用: 1000 個の子ワークフロー × 各 1000 タスク
• 各ワークフローをバウンドに保つ

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 を追跡する

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

目的: 失速した長時間実行アクティビティを検出する

パターン:

• アクティビティが定期的にハートビートを送信する
• 進捗情報を含める
• ハートビートを受信しない場合タイムアウト
• 進捗ベースの再試行を有効にする

ベストプラクティス

ワークフロー設計

1. ワークフローに焦点を当てる - ワークフローごとに単一の責任
2. 小さなワークフロー - スケーラビリティのために子ワークフローを使用する
3. 明確な境界 - ワークフロー はオーケストレーション、アクティビティは実行
4. ローカルでテストする - 時間スキップ テスト環境を使用する

アクティビティ設計

1. べき等操作 - 再試行しても安全
2. 短命 - 秒から分、時間ではない
3. タイムアウト構成 - 常にタイムアウトを設定する
4. 長いタスクのハートビート - 進捗を報告する
5. エラー処理 - 再試行可能と再試行不可を区別する

よくある落とし穴

ワークフロー違反:

• workflow.now() の代わりに datetime.now() を使用
• ワークフロー コードでのスレッドまたは非同期操作
• ワークフローから直接外部 API を呼び出す
• ワークフローでの非決定論的ロジック

アクティビティの間違い:

• べき等でない操作 (再試行を処理できない)
• タイムアウトを欠く (アクティビティが無期限に実行)
• エラー分類を欠く (検証エラーを再試行)
• ペイロード制限を無視 (引数あたり 2MB)

運用上の考慮事項

監視:

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

スケーラビリティ:

• ワーカーを使用した水平スケーリング
• タスク キュー パーティショニング
• 子ワークフロー分解
• 適切な場合のアクティビティ バッチ処理

追加リソース

公式ドキュメント:

• Temporal Core Concepts: docs.temporal.io/workflows
• Workflow Patterns: docs.temporal.io/evaluate/use-cases-design-patterns
• Best Practices: docs.temporal.io/develop/best-practices
• Saga Pattern: temporal.io/blog/saga-pattern-made-easy

主要原則:

1. ワークフロー = オーケストレーション、アクティビティ = 外部呼び出し
2. 決定論性はワークフローでは譲歩の余地がない
3. べき等性はアクティビティに不可欠
4. 状態保持は自動的
5. 障害と復旧を見据えた設計