camunda-job-workers

Camunda ジョブワーカー

Java、Camunda Spring Boot、または TypeScript で Camunda 8.8+ 向けのジョブワーカーを実装します。ジョブワーカーとは、Zeebe エンジンがアクティブ化したジョブを渡すハンドラーです。業務ロジックを実行し、その後、成功、失敗、または BPMN エラーをエンジンに通知します。

前提条件

• ワーカープロセスからアクセスできる Camunda 8.8+ クラスター（ローカルの c8run、SaaS、または Self-Managed。camunda-c8ctl を参照）
• ワーカーのジョブタイプに一致する <zeebe:taskDefinition type="..."/> を持つ要素が少なくとも 1 つある BPMN プロセス（camunda-bpmn を参照）
• 選択した SDK 用のツールチェーン — Java および Spring では OpenJDK 17+ と Maven/Gradle、TypeScript では Node.js 18+。SDK 固有のバージョン要件（Spring Boot 4 と 3 の違い、ブラウザーのサポートなど）は、各 SDK のリファレンスに記載されています。ローカル環境へのインストールについては camunda-development を参照してください。

相互参照

• camunda-development：まず参照し、そもそもワーカーが適切な形式かどうか（OOTB コネクター、JSON のみのプロトコルコネクターのテンプレート、または SDK を使用したカスタム Java コネクターと比較して）判断します
• camunda-connectors-development：統合がアプリケーションに結び付いたワーカーコードより再利用可能な Java コネクターに近い場合、または統合に受信トリガーが必要な場合に使用します（ワーカーは送信専用です）
• camunda-bpmn：サービス タスク／受信タスク要素とその zeebe:taskDefinition、およびワーカーの BPMN エラーを捕捉する境界イベントについて参照します
• camunda-feel：zeebe:taskHeaders 内の FEEL、およびワーカーの出力変数を使用するゲートウェイ条件について参照します
• camunda-process-mgmt：プロセスのデプロイ、実行中のワーカーに対するインスタンスの開始、クラスター側からのジョブ／インシデントの調査に使用します
• camunda-process-test：埋め込み Zeebe エンジンを介してワーカーハンドラーを実行するエンドツーエンドテストに使用します

ジョブワーカーを作成する場合

まず camunda-development を確認してください。ここでの選択肢を簡潔にまとめると、次のとおりです。

• Java 以外のスタック（TypeScript、および今後のリリースで対象となるその他の公式 SDK）：ワーカーを使用します。コネクターは Java 専用です。
• Java スタックで、ロジックがすでにアプリに存在する場合：ワーカーを使うことで、そのロジックを所有するコードベースに保持できます。
• Java スタックで、複数のプロセス／プロジェクト／クラスター間で再利用する場合：camunda-connectors-development を使用したカスタムコネクターを推奨します。
• 受信トリガー（外部システムからプロセスにイベントを送信する場合）：必ずコネクターを使用します。ワーカーはエンジンからアクティブ化されたジョブをプルする専用の仕組みです。

ジョブのライフサイクル

ワーカーとエンジン間の契約には、次の 4 つの状態があります。

1. アクティブ化 — ワーカーは指定した type のジョブを要求する（ポーリング）か、ストリーミング接続でジョブを受け取ります。各アクティブ化には タイムアウト（最初のワーカーが応答しない場合に、エンジンが同じジョブを別のワーカーに渡すまでの猶予期間）と、フェッチする変数のリスト（エンジンがジョブとともに送信するプロセス変数）が設定されます。
2. 処理 — ワーカーは、アクティブ化された job（変数、ヘッダー、残りのリトライ回数、キー）を使ってハンドラーコードを実行します。
3. 完了 — ワーカーは complete を呼び出します（または autoComplete=true の場合は値を返します）。エンジンはワーカーの出力変数をプロセススコープにマージし、トークンを次に進めます。BPMN のルールに従い、変数はジョブのスコープから上位の包含スコープに伝播します。
4. 失敗 — ワーカーは残りのリトライ回数と任意のバックオフを指定して明示的に fail を呼び出すか、例外をスローします。リトライ回数が 0 になると、エンジンは インシデント を発生させ、オペレーターが解決するまでインスタンスを一時停止します（camunda-process-mgmt を参照）。

アクティブ化タイムアウトとリトライは独立しています。 タイムアウトが発生してもリトライ回数は減らず、エンジンがジョブを再割り当てします。リトライ回数が残っている状態で fail を呼び出した場合は、バックオフ後に同じジョブが再配信されます。長時間実行されるハンドラーでは、リースの期限切れと競合しないよう、UpdateJobTimeout を使ってタイムアウトを延長してください。

冪等性 — すべてのジョブを少なくとも2回処理する

エンジンの少なくとも1回の配信保証により、同じ job.key に対してハンドラーが複数回実行されることがあります。アクティベーションのタイムアウト、ネットワークの瞬断、complete 呼び出しの失敗後の再試行はいずれも再配信の原因になります。ハンドラーは冪等でなければなりません。

次の2つのパターンが有効です。

• 下流システムでの冪等性トークン。 job.key（またはプロセス変数から導出した決定論的な値）をリクエスト ID／Idempotency-Key ヘッダー／データベースの一意制約として使用します。同じジョブの再試行では同じキーが使われるため、重複は抑止されます。
• 書き込み前の確認。 副作用を適用する前に、下流システムでその処理を示すマーカーを照会します。対応しているシステムであれば手軽ですが、常に利用できるとは限りません。

ワーカープロセスにローカルの「このジョブを実行したか」という状態を保存しても、冪等性にはなりません。プロセスはクラッシュしたり、スケールアウトしたり、置き換えられたりする可能性があるためです。

障害モード — 3つの異なる経路

どの経路を選ぶかは、障害が一時的なインフラストラクチャの問題なのか、モデル化されたビジネス上の結果なのか、予期しないプログラミングエラーなのかによって異なります。

1. 一時的な障害 → 再試行とバックオフを指定して失敗させる。 ネットワークタイムアウト、下流システムの5xx、ブローカーへの接続不可などです。ハンドラーは再試行回数を減らし、バックオフ後にエンジンが再配信するよう要求します。再試行回数が0になると、インシデントが発生します。

2. ビジネス上の結果 → BPMN エラー。 ハンドラーは BPMN でモデル化された障害（支払い拒否、在庫切れ、ライセンス拒否など）を特定できています。エラー境界イベント（またはサブプロセス内のエラー終了イベント）が捕捉するコードで BPMN エラーをスローします。ジョブは再試行されません — エンジンはエラー経路に進みます。

3. プログラミングエラー → 未処理例外。 NullPointerException、未処理のプロミス拒否、型エラーなどです。SDK はフォールバックとしてバックオフなしで失敗させます — エンジンは直ちに再配信し、再試行回数を消費して、インシデントを発生させます。制御フローのシグナルとして未処理例外を使ってはいけません。バックオフが0だとクラスターに過剰な負荷がかかり、将来の SDK の変更でデフォルトの動作が変わる可能性もあります。

SDK ごとの呼び出しシグネチャ（Spring の CamundaError.jobError／CamundaError.bpmnError、Java クライアントの newFailCommand／newThrowErrorCommand、TypeScript の job.fail／job.error）については、SDK ごとのリファレンスを参照してください。

自動完了と明示的な完了

Camunda Spring Boot Starter の @JobWorker は、デフォルトで自動的にジョブを完了します。ハンドラーの戻り値はジョブの出力変数としてシリアライズされます。ハンドラーが自身で complete を呼び出す必要がある場合（条件付き変数、非同期応答、所有権の移譲）は、autoComplete = false を設定します。

Java クライアントと TypeScript SDK は自動完了しません — ハンドラーはすべてのコードパスで complete、fail、または error を呼び出す必要があります。終端呼び出しがないと、アクティベーションタイムアウトまでジョブのリースが解放されません。

SDK を選ぶ

SDK	選択する状況
Camunda Spring Boot Starter — camunda-spring-boot-starter (ref)	新しい Java アプリケーション向けです。アノテーション駆動（@JobWorker）、自動完了、application.yaml による設定に対応しています。Java での標準的な選択肢です。
Java client — camunda-client-java (ref)	スタンドアロンの JVM アプリケーション、Spring 以外のフレームワーク、Zeebe アクセスを組み込むライブラリ向けです。より低レベルなビルダー API を使用します。非推奨の Zeebe Java Client（8.10で削除）に代わるものです。
TypeScript — @camunda8/orchestration-cluster-api (ref)	Node.js ワーカー、ブラウザーで動作するクライアント、8.9以降のプロジェクト向けです。gRPC ストリーミング、8.8未満の対象、または移行に伴う問題で明確に必要な場合に限り、@camunda8/sdk（Node.js 専用）を代わりに使用します。

Spring Boot 4 と 3 — 重要なルーティングの判断

デフォルトの Camunda Spring Boot Starter（camunda-spring-boot-starter）は Spring Boot 4.0.x に同梱され、Spring Boot 4.0.x が必要です。

Spring Boot 3.5.x を引き続き使用するアプリケーションでは、移行ブリッジとして camunda-spring-boot-3-starter を使用します。Spring による 3.5.x 系列の OSS サポートは 2026 年 6 月 に終了します。同じクラスパスで 2 つのスターターを混在させないでください。SB4 スターターは Spring Boot 3 アプリでは起動せず、SB3 スターターは Spring Boot 4 アプリに競合する推移的依存関係を取り込みます。

すべてのスターターモジュールには OpenJDK 17 以降が必要です。

よくある落とし穴

• ジョブの完了、失敗、エラーを忘れる（Java クライアント、TypeScript）。リースがタイムアウトし、エンジンが再配信します。ハンドラーは、すべてのコードパスで終端呼び出しを必ず 1 回だけ行う必要があります。Spring の autoComplete = true は正常終了時の戻り値を処理しますが、失敗時には明示的な通知が必要です。
• 未処理の例外を BPMN エラーとして扱う。 未処理の例外のスローはプログラミングエラーであり、モデル化された結果ではありません。SDK は retries - 1 と retryBackoff = 0 でジョブを失敗させます。するとエンジンはただちに再配信し、リトライを消費して、インシデントを発生させます。
• 「処理済み」の状態をワーカープロセスに保存する。 クラッシュやスケールアウトによって、その状態は失われます。冪等性は、下流システム、または再配信後も保持されるプロセス変数で実現してください。
• ポーリングとリクエストタイムアウトの不整合。 アクティベーションリクエストのタイムアウトは、ゲートウェイ／ロードバランサーの切断時間より短くする必要があります。そうでないと、ワーカーが接続を切断してループ状に再接続します。SDK のデフォルト値は妥当なため、変更は慎重に行ってください。

参考資料

SDK 固有の詳細については、references/ を参照してください。

• worker-sdk-java.md — camunda-client-java：クライアントの初期化、JobWorkerBuilder、コマンドビルダー、ストリーミング、マルチテナンシー、OAuth 設定
• worker-sdk-spring.md — Camunda Spring Boot Starter：@JobWorker パラメーターのリファレンス、@Variable／@VariablesAsType、CamundaError、設定プロパティーツリー、Spring Boot 4 と 3 のスターター選択
• worker-sdk-typescript.md — @camunda8/orchestration-cluster-api：createJobWorker／createThreadedJobWorker、ジョブハンドラーの戻り値の形式、@camunda8/sdk にフォールバックするタイミング