Sidekiq 3.0 升级指南:从 2.x 迁移的 API 变更、Redis 数据调整与错误处理改造
Sidekiq 3.0 升级指南:从 2.x 迁移的 API 变更、Redis 数据调整与错误处理改造
本篇技术指南以 Sidekiq 官方 3.0 升级文档为核心,系统梳理从 2.x 迁移到 3.0 时必须处理的六类变更:客户端中间件签名重写、API 命名迁移、Redis 数据元素调整、Capistrano 集成拆分、错误处理模型重构与运行时支持范围收窄。读者在读完本文后,可以按清单完成一次干净的 3.0 升级,并理解这些变更背后的设计动机——尤其是"把 Redis 连接实例传入客户端中间件以支持分片"这一架构决策。文中所有 API 均对照当前仓库源码(Sidekiq 8.x,见 lib/sidekiq/version.rb)进行了溯源印证,帮助读者理解这些接口在后续版本中的演化脉络。
历史背景说明:本文对应 Sidekiq 3.0(约 2014 年 2 月发布)的官方迁移文档 docs/3.0-Upgrade.md。当前仓库版本已演进至 8.x,文中标注的源码位置以当前仓库为准,用于印证这些 API 的后续形态;具体迁移步骤针对 2.x → 3.0 场景。
升级前的准备:先跑稳 2.x 再迁移
Sidekiq 3.0 带来了若干新特性,同时移除了一批旧 API,并改变了 Redis 中的部分数据元素。官方升级文档给出的第一条建议是:
- 先升级到最新版 Sidekiq 2.x,并运行数周,确保没有积压的、仍在重试队列(retries)中的任务:
gem 'sidekiq', '< 3'
文档特别强调,只有在仍有待处理的重试任务(retries pending)时才需要这一步。原因是 3.0 重构了内部进程/线程数据模型,并改变了 Redis 中的部分数据结构,如果带着 2.x 时代的重试数据直接跨大版本,可能出现数据读取不一致。先在 2.x 上把重试队列消化干净,是成本最低的平滑迁移方式。
这条建议背后的逻辑延续至今:Sidekiq 的重试数据、调度数据(scheduled set)都持久化在 Redis 中(相关实现可参见 lib/sidekiq/scheduled.rb),跨大版本升级前清空或消化存量数据,始终是官方推荐的稳妥策略。
客户端中间件 API 变更:Redis 连接实例传入 call
3.0 对**客户端中间件(client-side middleware)**做了一次破坏性 API 变更:某个任务对应的 Redis 连接会通过中间件传递,目的是支持分片(sharding)——即任务可以被推送到不同的 Redis 服务器实例。
旧签名只有三个参数,新签名为:
def call(worker_class, msg, queue, redis_pool)
客户端中间件必须使用 redis_pool.with { |conn| ... } 来执行 Redis 操作,而不是再使用 Sidekiq.redis。这是因为在分片场景下,每个队列可能对应不同的 Redis 实例,中间件必须通过 redis_pool 拿到"该任务应写入的那个连接"。
从当前仓库源码可以看到这一设计已被完整保留并继续演化:
- lib/sidekiq/client.rb 中,
Client#push通过middleware.invoke(item["class"], normed, normed["queue"], @redis_pool)将连接池传入中间件链; - 同一文件 raw_push 内部使用
@redis_pool.with do |conn| ... end执行实际的 Redis 写入; - lib/sidekiq/capsule.rb 中
redis_pool会优先取Thread.current[:sidekiq_redis_pool],这正是分片场景下为当前执行上下文注入"目标实例连接池"的机制。
迁移动作:所有第三方 gem 或自研的客户端中间件,把方法签名改为上述四参数形式,并把内部 Sidekiq.redis { |c| ... } 改写为 redis_pool.with { |conn| ... }。
Capistrano 集成拆分:改用 capistrano-sidekiq
如果你此前使用了 Sidekiq 自带的 Capistrano 集成,3.0 起它被从主仓库拆出。迁移动作:
- 在 Gemfile 中引入新的
capistrano-sidekiqgem; - 在
deploy.rb中使用它提供的任务(require 'capistrano/sidekiq'等,具体以该 gem 文档为准)。
这一拆分与后续版本中 web UI、Pro/Ent 功能持续外置的思路一脉相承——Sidekiq 主仓库保持核心,周边集成由独立 gem 维护。
API 变更明细:四个替换关系
3.0 对公开 API 做了一轮命名收敛,官方升级文档列出的替换关系如下:
| 旧 API(2.x) | 新 API(3.0) |
|---|---|
Sidekiq::Client.registered_workers |
Sidekiq::Workers.new |
Sidekiq::Client.registered_queues |
Sidekiq::Queue.all |
Sidekiq::Worker#retries_exhausted |
Sidekiq::Worker.sidekiq_retries_exhausted |
Sidekiq::Workers#each(旧语义) |
语义随进程/线程数据模型重构而改变 |
逐个说明其迁移含义与当前仓库中的演化形态:
registered_queues → Queue.all
Sidekiq::Queue.all 在 lib/sidekiq/api.rb 中的实现是:
def self.all
Sidekiq.redis { |c| c.sscan("queues").to_a }.sort.map { |q| Sidekiq::Queue.new(q) }
end
即从 Redis 的 queues 集合中扫描全部队列名,再包装成 Sidekiq::Queue 对象数组。Sidekiq::Queue 实例提供 size(实时队列长度)、latency(最旧任务滞留秒数)等方法(lib/sidekiq/api.rb),并支持按页遍历任务。迁移时把"查询当前已注册队列"的调用点统一改为 Sidekiq::Queue.all 即可。
registered_workers → Workers.new
Sidekiq::Workers.new 返回当前所有存活 worker(进程内的线程)的快照。这一改动背后是 Sidekiq 对内部进程/线程数据模型的整体重构:3.0 起,Sidekiq 进程通过心跳(heartbeat)在 Redis 中维护 processes 集合,每个进程的哈希里记录 info、busy、concurrency、beat、quiet、rss、rtt_us 等字段。
当前仓库中对应的实体是 ProcessSet(进程集合)与其 each 实现(lib/sidekiq/api.rb):先 sscan("processes") 拿到所有进程 key,再用 pipelined 批量读取各进程的元数据,并跳过已停止进程。而 Workers(进程内的 worker 线程集合)及其 each 位于 lib/sidekiq/api.rb。文档特别提醒:Sidekiq::Workers#each 的语义发生显著变化,依赖旧版"遍历所有 worker"逻辑的监控类代码,需要按新模型(进程 → 线程)重新适配。
retries_exhausted → sidekiq_retries_exhausted
重试彻底耗尽(所有重试次数用尽)时的钩子由实例方法改为类方法。当前仓库中 lib/sidekiq/job_retry.rb 会查找 worker 类上的 sidekiq_retries_exhausted_block 并执行,且支持 ActiveJob 等包装类(wrapped class)场景——这正是从 3.0 起类方法钩子形态延续至今的证据。迁移时把 def retries_exhausted 改为 def self.sidekiq_retries_exhausted,并将原有逻辑放入其中。
sidekiq/api 不再自动加载
2.x 中 sidekiq/api 会被自动 require;3.0 起不再自动加载。如果代码中使用了 Sidekiq::Queue、Sidekiq::Workers、Sidekiq::ProcessSet、Sidekiq::DeadSet 等 API 类,必须显式添加:
require "sidekiq/api"
迁移时请全局搜索 Sidekiq:: 下 API 类的使用点,在入口处补上该 require,避免运行时 NameError。
Heroku / Redis 配置:不再透明激活 Redis-to-Go
3.0 之前,Sidekiq 在 Heroku 上会"透明地"激活 Redis-to-Go 服务;3.0 起为了不对任何特定 Redis 服务商偏袒,这一行为被移除。迁移动作是在应用侧显式设置配置项:
heroku config:set REDIS_PROVIDER=REDISTOGO_URL
也可以使用通用的 REDIS_URL 环境变量。配置细节可参考官方文档中的"Advanced Options: Setting the Location of your Redis server"一节(原文档以外部链接形式给出,此处不再展开外部内容)。
这一设计取向同样延续至今:Sidekiq 只认标准的 REDIS_PROVIDER / REDIS_URL 约定,不绑定任何特定 Redis 托管服务。
错误服务提供商:从 server middleware 改为全局 error handler
这是 3.0 最具实质性的架构变化之一。2.x 时代,捕获任务执行错误的通行做法是在 server 中间件链里挂一个错误上报中间件;3.0 改为注册全局错误处理器,其优势在于:Sidekiq 进程内任何环节(不只是任务执行过程)出错都会被记录并交给处理器,覆盖面更完整。
官方文档给出的迁移代码同时兼容两个版本:
if Sidekiq::VERSION < '3'
# old behavior
Sidekiq.configure_server do |config|
config.server_middleware do |chain|
chain.add MyErrorService::Middleware
end
end
else
Sidekiq.configure_server do |config|
config.error_handlers << proc {|ex,context| MyErrorService.notify(ex, context) }
end
end
关键约定:错误处理器必须响应 call(exception, context_hash)(即实现 def call(ex, ctx),或直接传一个 proc)。
这一机制在后续版本中被完整保留。当前仓库 lib/sidekiq/config.rb 中,error_handlers 是配置项数组,默认注册一个记录日志的处理器(ERROR_HANDLER,见同文件第 65 行);而 handle_exception 会遍历所有已注册 handler 并逐个调用,同时用 rescue Exception 保护——单个错误处理器自身抛异常不会拖垮 Sidekiq 进程,只会被记入日志。注意后续版本中 handler 的实际调用签名已扩展为 call(ex, ctx, config)(三参数,第三参数为配置对象),向上兼容旧的两参数形式,但迁移到更高版本时可留意这一点。
迁移动作:把自定义错误上报从 server_middleware 迁移到 error_handlers;使用 Airbrake、Honeybadger、Exceptional、ExceptionNotifier 等错误服务的用户,需同步升级对应错误 gem 到支持 Sidekiq 的最新版本。官方明确表示不会为特定错误服务提供显式支持(同样是不偏袒任何服务商的设计取向),因此错误上报统一走全局 handler 协议。
运行时支持范围收窄:MRI 1.9 退役
3.0 起 MRI 1.9 不再被官方支持。Sidekiq 的官方支持策略是:支持当前及前一个主版本的 MRI 与 Rails。以 2014 年 2 月为时间点,官方支持的组合为:
- MRI 2.1、MRI 2.0、JRuby 1.7
- Rails 4.0、Rails 3.2
对于其他平台/版本发现的问题,官方表示会考虑接受用户提交的修复 PR(pull request),但不作支持承诺。升级到 3.0 前,请先确认运行环境的 Ruby/JRuby 与 Rails 版本落在上述范围内。
迁移检查清单
按官方文档整理出一份可直接对照执行的检查清单:
- 存量重试数据:若 Redis 中仍有 pending 重试任务,先将 Gemfile 锁定
gem 'sidekiq', '< 3'并运行数周,待重试队列消化后再升级; - 客户端中间件:全量检查第三方 gem 与自研中间件,签名改为
call(worker_class, msg, queue, redis_pool),内部 Redis 操作用redis_pool.with { |conn| ... }替代Sidekiq.redis; - Capistrano:若使用部署集成,移除内置集成,改用
capistrano-sidekiqgem 并在deploy.rb中引用; - API 调用点:
registered_workers→Sidekiq::Workers.new;registered_queues→Sidekiq::Queue.all;retries_exhausted→sidekiq_retries_exhausted;按新进程/线程数据模型重写依赖Workers#each的监控逻辑; - 显式 require:使用 API 类的文件顶部补
require "sidekiq/api"; - Redis 配置:Heroku 上执行
heroku config:set REDIS_PROVIDER=REDISTOGO_URL(或使用REDIS_URL); - 错误上报:将 server middleware 中的错误上报改为
config.error_handlers << proc {|ex, ctx| ... },并升级 Airbrake / Honeybadger / Exceptional / ExceptionNotifier 等错误 gem 到最新版; - 运行时版本:确认 Ruby(MRI 2.0+ / JRuby 1.7+)与 Rails(3.2+ / 4.0)满足 3.0 的支持范围。
完成上述全部动作后,Sidekiq 3.0 的迁移即可视为干净收尾。想深入了解这些 API 在当代版本中的完整行为,可以直接阅读仓库中的 lib/sidekiq/api.rb(队列、进程、worker 监控 API)、lib/sidekiq/client.rb(客户端中间件与分片连接池)以及 lib/sidekiq/config.rb(错误处理器与生命周期配置),并结合 test/api_test.rb 等测试用例验证调用约定。