bitrix-background-jobs

バックグラウンドジョブ

ベースライン：main 23.0+ · 検証済み：main 26.800.0

タスク	参照先
定期タスクまたは遅延タスク、cron で実行するエージェント、長時間実行するエージェント	rules/agents.md
レスポンス送信後に行う短時間の後処理	rules/background-job.md
キュー：メッセージ、受信側、ディスパッチ、再試行	rules/messenger.md
キュー設定、ブローカー、messenger:consume、カーネルキュー	rules/messenger-config.md

選択の目安：スケジュール実行 → エージェント（cron で実行）；レスポンス送信後に行う数秒程度の処理 → addBackgroundJob；再試行、大量処理、並列ワーカー → Messenger（main 25.100.300 以降、アルファ版）；単発の長時間実行マイグレーション → コンソールコマンド（bitrix-console-commands）。

不変条件

• バックグラウンドコードにはユーザーコンテキストがありません。エージェントと受信側では global $USER = null を設定し、$_SESSION／Cookie は使用しません。ユーザー ID とサイト ID は明示的に渡してください。
• リクエストを受けた場合、エージェント、web モードの Messenger、addBackgroundJob() は、レスポンス送信後、OnAfterEpilog と session_write_close() の後に実行されます。このとき、DB プールは強制的にマスターへ接続します。
• ジョブのコードは薄く保ちます。ServiceLocator::getInstance()->get() でサービスを解決して呼び出してください（エージェントではコンストラクター DI を使用しません — bitrix-framework）。
• ジョブは冪等である必要があります。エージェントは並列で 2 回実行されることがあり、メッセージは再配信されることがあります。
• 失敗は PSR-3 ロガー（bitrix-logger）を通じて記録してください。モジュールのアンインストール時には、エージェントを削除してください。