Sidekiq 3.0 升级指南：关键变更与迁移策略

Sidekiq 3.0 升级指南：关键变更与迁移策略

sidekiq 项目地址: https://gitcode.com/gh_mirrors/sid/sidekiq

前言

Sidekiq 作为 Ruby 生态中最受欢迎的异步任务处理框架之一，其 3.0 版本带来了多项重要改进。本文将从技术实现角度深入解析升级过程中的关键变更点，帮助开发者顺利完成迁移。

升级前的准备工作

在正式升级到 Sidekiq 3.0 前，建议采取以下稳妥的过渡方案：

1. 先行升级到最新的 2.x 版本并稳定运行数周
2. 确保所有待重试任务（pending retries）处理完毕
3. 通过 Gemfile 锁定版本范围：gem 'sidekiq', '< 3'

这一准备阶段特别重要，因为 3.0 版本对 Redis 数据结构进行了调整，直接升级可能导致未处理的重试任务丢失。

客户端中间件重大变更

API 变更详解

Sidekiq 3.0 对客户端中间件的调用签名进行了重要修改：

# 旧版本签名
def call(worker_class, msg, queue)

# 新版本签名
def call(worker_class, msg, queue, redis_pool)

这一变更为实现 Redis 分片功能提供了基础支持，允许将任务推送到不同的 Redis 实例。

正确使用 Redis 连接

在新的 API 设计中：

1. 必须通过 redis_pool.with 块来执行 Redis 操作
2. 禁止直接使用 Sidekiq.redis 全局方法
3. 连接管理示例：

def call(worker_class, msg, queue, redis_pool)
  redis_pool.with do |conn|
    conn.set("job:#{msg['jid']}", "processing")
  end
  yield
end

部署集成变更

Capistrano 用户需要注意：

1. 原有的内置集成已被移除
2. 需要单独引入 capistrano-sidekiq gem
3. 在 deploy.rb 中配置新的集成方式

API 接口变化一览

3.0 版本对多个 API 进行了重构：

| 废弃API | 替代方案 | 说明 | |---------|----------|------| | 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 | 全新实现 | 内部线程模型重构 |

特别注意：sidekiq/api 不再自动加载，需要显式 require。

Heroku 环境配置调整

Sidekiq 3.0 取消了对 Redis-to-Go 的自动检测支持，改为更通用的配置方式：

heroku config:set REDIS_PROVIDER=REDISTOGO_URL
# 或使用通用配置
heroku config:set REDIS_URL=your_redis_url

这一变更使得 Sidekiq 可以平等支持各种 Redis 服务提供商。

错误处理机制升级

错误服务提供商集成

3.0 版本引入了全局错误处理器（error handler）来替代原有的中间件方案：

Sidekiq.configure_server do |config|
  config.error_handlers << Proc.new do |ex, context|
    # 处理异常
    MyErrorService.notify(ex, context)
  end
end

新机制的优势在于：

• 捕获 Sidekiq 进程内的所有异常
• 不仅限于任务执行期间的错误
• 统一错误处理接口

错误处理器必须实现 call(exception, context_hash) 方法。

常见错误服务适配

主流错误监控服务（Airbrake、Honeybadger 等）需要更新到最新版本才能兼容 Sidekiq 3.0。Sidekiq 核心代码库不再内置对这些服务的特殊支持。

运行时环境支持

官方支持的运行时环境调整为：

• MRI Ruby 2.0+
• JRuby 1.7+
• Rails 4.0/3.2

特别注意：MRI 1.9 已不再受官方支持。

升级检查清单

1. [ ] 更新所有客户端中间件
2. [ ] 调整 Capistrano 部署配置
3. [ ] 替换废弃 API 调用
4. [ ] 显式引入 sidekiq/api
5. [ ] 配置 Heroku 环境变量（如适用）
6. [ ] 更新错误处理集成
7. [ ] 验证运行时环境兼容性

遵循本指南进行升级，可以确保业务系统平稳过渡到 Sidekiq 3.0，同时充分利用新版本提供的改进特性。

sidekiq 项目地址: https://gitcode.com/gh_mirrors/sid/sidekiq