oban

Oban バックグラウンドジョブ リファレンス

Elixir Oban のパターンに関するクイックリファレンスです。

Oban Pro の検出

パターンを適用する前に、Oban Pro があるか確認してください：

grep -E "oban_pro|oban_web" mix.exs
grep -r "use Oban.Pro.Worker" lib/
grep -r "Oban.Pro.Engines.Smart" config/

Oban Pro が検出された場合、新しいワーカーにはすべて Pro のパターンを使用してください：

標準の Oban	Oban Pro
use Oban.Worker	use Oban.Pro.Worker
def perform(%Job{})	def process(%Job{})
Oban.Testing	Oban.Pro.Testing
アドバイザリロックエンジン	Oban.Pro.Engines.Smart

Pro の機能（すべて任意）：args_schema（型付き引数）、ワークフロー、バッチ、チャンク、 Relay、フック、暗号化、期限、チェーン、Smart Engine（グローバル同時実行数＋レート制限）。 Pro プラグイン（DynamicCron、DynamicLifeline、DynamicPruner）は、OSS 版の同等機能を強化します。モジュールを切り替え、両方を同時に実行しないでください。 すべてのパターンと移行ガイドについては、${CLAUDE_SKILL_DIR}/references/oban-pro-basics.md を参照してください。

---

絶対に守るべき原則

1. ジョブは冪等でなければなりません — 安全に再試行できるようにします。支払いには冪等性キーを使用してください
2. ジョブには構造体ではなく ID を保存してください — JSON シリアライズが必要です。%{user_id: 1} を使い、%{user: %User{}} は使わないでください
3. ジョブはすべての戻り値を処理しなければなりません — :ok、{:error, _}、{:cancel, _}、{:snooze, _}
4. 引数には文字列キーを使用してください — %{"user_id" => id} でパターンマッチし、%{user_id: id} は使わないでください
5. ユーザー操作には一意制約を設定してください — ダブルクリックによる重複を防ぎます
6. 引数に大きなデータを保存しないでください — コンテンツではなく、参照（ID、パス）を保存してください
7. Smart Engine：スヌーズ回数の制限に attempt を使用しないでください — スヌーズすると attempt カウンターがロールバックされます。代わりに meta["snoozed"] を使用してください。無限ループの原因になります

ワーカーのクイックテンプレート

defmodule MyApp.Workers.ExampleWorker do
  use Oban.Worker,
    queue: :default,
    max_attempts: 5,
    unique: [period: {5, :minutes}, keys: [:entity_id]]

  @impl Oban.Worker
  def perform(%Oban.Job{args: %{"entity_id" => id}}) do
    case process(id) do
      {:ok, _} -> :ok
      {:error, :not_found} -> {:cancel, "Entity not found"}
      {:error, :rate_limited} -> {:snooze, {5, :minutes}}
      {:error, reason} -> {:error, reason}
    end
  end
end

戻り値の意味

戻り値	状態	動作
:ok	completed	成功
{:ok, value}	completed	値を伴う成功
{:error, reason}	retryable	バックオフ付きで再試行
{:cancel, reason}	cancelled	永久に停止
{:snooze, seconds}	scheduled	遅延して再試行

クイックな判断基準

キューの選び方

• 重要な処理 → 高い同時実行数（20 以上）
• メーラー／Webhook（I/O） → 中程度の同時実行数（30～50）
• CPU 負荷の高い処理 → 低い同時実行数（3～5）
• 外部 API → レート制限には dispatch_cooldown を使用してください

テストパターン

use Oban.Testing, repo: MyApp.Repo

# Assert enqueued
assert_enqueued worker: MyApp.Worker, args: %{id: 1}

# Execute and verify
assert :ok = perform_job(MyApp.Worker, %{id: 1})

よくあるアンチパターン

誤り	正しい方法
%{user_id: id} でパターンマッチ	%{"user_id" => id}（文字列キー）
引数に %{user: %User{}} を指定	%{user_id: 1}（ID のみ）
支払いに冪等性がない	冪等性キーを使用する
戻り値を無視する	すべての結果を明示的に処理する

リファレンス

詳細なパターンについては、以下を参照してください：

• ${CLAUDE_SKILL_DIR}/references/worker-patterns.md - ワーカーのオプション、バックオフ、タイムアウト
• ${CLAUDE_SKILL_DIR}/references/queue-config.md - キューの設計、プールサイズ、cron、Smart Engine
• ${CLAUDE_SKILL_DIR}/references/testing-patterns.md - テスト、アサーション、ドレイン（OSS＋Pro）
• ${CLAUDE_SKILL_DIR}/references/oban-pro-basics.md - Pro.Worker、Workflow、Batch、Chunk、Relay、プラグイン