Oban项目v2.0版本升级指南：关键变更与迁移策略-优快云博客

Oban项目v2.0版本升级指南：关键变更与迁移策略

oban 💎 Robust job processing in Elixir, backed by modern PostgreSQL or SQLite3 项目地址: https://gitcode.com/gh_mirrors/ob/oban

前言

Oban是一个强大的Elixir后台任务处理库，其v2.0版本带来了大量新特性和改进。作为一次重大版本更新，v2.0在API设计、配置方式和核心功能等方面都有显著变化。本文将全面解析这些变更，并提供详细的迁移指导，帮助开发者顺利完成升级。

依赖项更新

首先需要更新项目中的依赖项版本：

defp deps do
  [
    {:oban, "~> 2.0.0"},
    # 其他依赖...
  ]
end

对于使用Web和Pro版本的用户，还需要添加相应的依赖：

defp deps do
  [
    {:oban, "~> 2.0.0"},
    {:oban_web, "~> 2.0.0", organization: "oban"},
    {:oban_pro, "~> 0.3.0", organization: "oban"}
    # 其他依赖...
  ]
end

Worker接口变更

v2.0版本对Worker接口进行了重大重构，旨在提供更一致的API设计。

perform回调变更

原先的perform/2回调被简化为perform/1，现在只接收一个Oban.Job结构体作为参数。这种变更使得所有Worker回调的接口更加统一，减少了参数模式匹配可能带来的混淆。

迁移时需要将原有的双参数形式改为单参数形式：

- def perform(%{"id" => id}, _job)
+ def perform(%Job{args: %{"id" => id}})

backoff回调变更

类似地，backoff/1回调现在也接收完整的Job结构体，而非单独的attempt数值：

- def backoff(attempt)
+ def backoff(%Job{attempt: attempt})

配置系统重构

v2.0对配置系统进行了现代化改造，引入了插件架构来替代部分旧有配置项。

日志配置变更

日志级别配置项名称从:verbose改为:log，与Ecto.Repo的配置风格保持一致：

config :my_app, Oban,
- verbose: false,
+ log: false

任务清理机制

任务清理功能现在通过插件系统实现。原有的:prune相关配置需要替换为Pruner插件：

config :my_app, Oban,
- prune: {:max_age, 60},
- prune_interval: 30_000,
- prune_limit: 5000,
+ plugins: [{Oban.Plugins.Pruner, max_age: 60}]

在测试环境中，可以通过设置plugins: false来完全禁用插件：

config :my_app, Oban,
-  prune: false,
+  plugins: false

心跳与任务救援

v2.0移除了基础版中的心跳检测和孤儿任务救援功能。这意味着在系统崩溃或强制关闭后，开发者需要手动处理处于执行状态的任务。

移除以下配置项：

config :my_app, Oban,
-  beats_maxage: 10,
-  rescue_after: 30_000,
-  rescue_interval: 5_000

测试辅助工具改进

v2.0引入了新的测试辅助工具perform_job，它能够自动验证、规范化并执行任务，简化了测试代码。

迁移测试用例：

- assert :ok = MyApp.Worker.perform(%{id: 1}, %Oban.Job{})
+ assert :ok = perform_job(MyApp.Worker, %{id: 1})

对于集成测试中的队列清空操作：

- Oban.drain_queue(:myqueue, with_safety: false)
+ Oban.drain_queue(queue: :myqueue, with_safety: false)

Telemetry事件更新

Telemetry事件系统进行了标准化改造，事件名称、元数据和计时单位都有所变化。

事件处理器更新

更新事件处理器以匹配新的事件名称：

- def handle_event([:oban, :failure], measure, meta, _) do
+ def handle_event([:oban, :job, :exception], measure, meta, _) do

同时更新事件附加代码：

- :telemetry.attach("oban", [[:oban, :failure]], &handle_event/4, %{})
+ :telemetry.attach("oban", [[:oban, :job, :exception]], &handle_event/4, %{})

元数据字段变更

meta.stack字段更名为meta.stacktrace：

- Sentry.capture_exception(meta.error, stacktrace: meta.stack, extra: extra)
+ Sentry.capture_exception(meta.error, stacktrace: meta.stacktrace, extra: extra)

事件名称对照表

以下是新旧事件名称的完整对照：

[:oban, :started] -> [:oban, :job, :start]
[:oban, :success] -> [:oban, :job, :stop]
[:oban, :failure] -> [:oban, :job, :exception]
[:oban, :trip_circuit] -> [:oban, :circuit, :trip]
[:oban, :open_circuit] -> [:oban, :circuit, :open]

Web界面升级（可选）

Oban.Web在v2.0中进行了简化，现在与主库共享配置并使用新的插件系统。

配置变更

移除单独的Web配置：

- config :my_app, Oban.Web, repo: MyApp.Repo

改为在Oban主配置中添加必要插件：

config :my_app, Oban,
  plugins: [
    Oban.Pro.Plugins.DynamicPruner,
    Oban.Pro.Plugins.Lifeline,
    Oban.Web.Plugins.Stats
  ],
  ...

应用监督树调整

从应用监督树中移除ObanWeb：

children = [
  MyApp.Repo,
  MyApp.Endpoint,
  {Oban, oban_opts},
- {ObanWeb, oban_web_opts}
]

路由配置简化

使用新的oban_dashboard宏简化路由配置：

+ import Oban.Web.Router

scope "/" do
  pipe_through :browser

-  live "/oban", ObanWeb.DashboardLive, layout: {ObanWeb.LayoutView, "app.html"}
+  oban_dashboard("/oban")
end