oban

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oban Background Jobs Reference

Oban后台作业参考指南

Quick reference for Elixir Oban patterns.

Elixir Oban模式快速参考。

Oban Pro Detection

Oban Pro 检测

Before applying patterns, check for Oban Pro:

bash

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

If Oban Pro detected, see

references/oban-pro-basics.md

for key differences:

Standard Oban	Oban Pro
`use Oban.Worker`	`use Oban.Pro.Worker`
`@impl Oban.Worker`	`@impl Oban.Pro.Worker`
`def perform(%Oban.Job{})`	`def process(%Oban.Job{})`
`Oban.Testing`	`Oban.Pro.Testing`

Pro features covered: Workflows, Batches, Structured/Recorded/Encrypted workers. See

references/oban-pro-basics.md

for patterns. For Pro plugins (Lifeline, Smart Engine, DynamicPrioritizer), consult oban.pro/docs.

在应用模式之前，请检查是否使用Oban Pro：

bash

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

如果检测到Oban Pro，请查看

references/oban-pro-basics.md

了解关键差异：

标准Oban	Oban Pro
`use Oban.Worker`	`use Oban.Pro.Worker`
`@impl Oban.Worker`	`@impl Oban.Pro.Worker`
`def perform(%Oban.Job{})`	`def process(%Oban.Job{})`
`Oban.Testing`	`Oban.Pro.Testing`

涵盖的Pro功能：工作流、批处理、结构化/记录式/加密工作器。有关模式请查看

references/oban-pro-basics.md

。对于Pro插件（Lifeline、Smart Engine、DynamicPrioritizer），请参考oban.pro/docs。

Iron Laws — Never Violate These

铁律——绝对不可违反

JOBS MUST BE IDEMPOTENT — Safe to retry. Use idempotency keys for payments
JOBS MUST STORE IDs, NOT STRUCTS — JSON serialization.
```
%{user_id: 1}
```
not
```
%{user: %User{}}
```
JOBS MUST HANDLE ALL RETURN VALUES —
```
:ok
```
,
```
{:error, _}
```
,
```
{:cancel, _}
```
,
```
{:snooze, _}
```
ARGS USE STRING KEYS — Pattern match
```
%{"user_id" => id}
```
not
```
%{user_id: id}
```
UNIQUE CONSTRAINTS FOR USER ACTIONS — Prevent double-click duplicates
NEVER STORE LARGE DATA IN ARGS — Store references (IDs, paths), not content

作业必须是幂等的——可安全重试。支付场景使用幂等键
作业必须存储ID，而非结构体——JSON序列化。使用
```
%{user_id: 1}
```
而非
```
%{user: %User{}}
```
作业必须处理所有返回值——
```
:ok
```
、
```
{:error, _}
```
、
```
{:cancel, _}
```
、
```
{:snooze, _}
```
参数使用字符串键——模式匹配
```
%{"user_id" => id}
```
而非
```
%{user_id: id}
```
用户操作需设置唯一约束——防止重复提交（如双击）
绝不在参数中存储大量数据——存储引用（ID、路径），而非内容

Quick Worker Template

快速工作器模板

elixir

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

elixir

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

Return Value Meanings

返回值含义

Return	State	Behavior
`:ok`	`completed`	Success
`{:ok, value}`	`completed`	Success with value
`{:error, reason}`	`retryable`	Retry with backoff
`{:cancel, reason}`	`cancelled`	Stop permanently
`{:snooze, seconds}`	`scheduled`	Delay and retry

返回值	状态	行为
`:ok`	`completed`	成功
`{:ok, value}`	`completed`	成功并返回值
`{:error, reason}`	`retryable`	带退避策略重试
`{:cancel, reason}`	`cancelled`	永久终止
`{:snooze, seconds}`	`scheduled`	延迟后重试

Quick Decisions

快速决策指南

Which Queue?

选择哪个队列？

Critical operations → High concurrency (20+)
Mailers/Webhooks (I/O) → Medium concurrency (30-50)
CPU-intensive → Low concurrency (3-5)
External APIs → Use
```
dispatch_cooldown
```
for rate limiting

关键操作 → 高并发（20+）
邮件/网络钩子（I/O密集型） → 中并发（30-50）
CPU密集型 → 低并发（3-5）
外部API调用 → 使用
```
dispatch_cooldown
```
进行速率限制

Testing Pattern

测试模式

elixir

use Oban.Testing, repo: MyApp.Repo

elixir

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})

undefined

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

undefined

Common Anti-patterns

常见反模式

Wrong	Right
`%{user_id: id}` pattern match	`%{"user_id" => id}` (string keys)
`%{user: %User{}}` in args	`%{user_id: 1}` (IDs only)
No idempotency for payments	Use idempotency keys
Ignoring return values	Handle all outcomes explicitly

错误做法	正确做法
`%{user_id: id}` 模式匹配	`%{"user_id" => id}` （字符串键）
参数中使用 `%{user: %User{}}`	`%{user_id: 1}` （仅使用ID）
支付场景不做幂等处理	使用幂等键
忽略返回值	显式处理所有结果

References

参考资料

For detailed patterns, see:

```
references/worker-patterns.md
```
- Worker options, backoff, timeout
```
references/queue-config.md
```
- Queue design, pool sizing, cron
```
references/testing-patterns.md
```
- Testing, assertions, drain

如需详细模式，请查看：

```
references/worker-patterns.md
```
- 工作器选项、退避策略、超时设置
```
references/queue-config.md
```
- 队列设计、池大小配置、定时任务
```
references/testing-patterns.md
```
- 测试、断言、任务排空