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，所有新 Worker 都使用 Pro 模式：

标准 Oban	Oban Pro
use Oban.Worker	use Oban.Pro.Worker
def perform(%Job{})	def process(%Job{})
Oban.Testing	Oban.Pro.Testing
Advisory lock 引擎	Oban.Pro.Engines.Smart

Pro 功能（均为可选）：args_schema（类型化参数）、Workflows、Batches、Chunks、 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"]。否则会导致无限循环

Worker 快速模板

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 - Worker 选项、退避、超时
• ${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、插件