---
title: "Shoryuken（Ruby gem）とは？SQSワーカーの導入・設定とActive Job連携・リトライ設計【7.0.4対応】"
url: "https://www.issoh.co.jp/tech/details/3429/"
published: 2024-08-30
updated: 2026-10-17
categories: ["Ruby on Rails"]
publisher: "株式会社一創"
---

# Shoryuken（Ruby gem）とは？SQSワーカーの導入・設定とActive Job連携・リトライ設計【7.0.4対応】

Shoryuken（しょうりゅうけん）は、Amazon SQSのメッセージをマルチスレッドで処理するRuby製のワーカーgemです。格闘ゲームの技名と同じ綴りのため検索結果が混ざりますが、ここで扱うのはRubyのgemのほうです。Redisを前提とするSidekiqと違い、キューの実体はSQSそのもの。ブローカーを自前で持たずにジョブ基盤を組める点が採用の決め手になります。

2026年10月17日時点の最新版は、2026年9月23日公開の7.0.4です。本稿のコードと出力は、Ruby 4.0.6・Shoryuken 7.0.4・Active Job 8.1.4で、AWS SDKのスタブ（実際のSQSに接続しない応答差し替え）を使って実行した結果です。インストールから起動までの手順に加え、FIFOキューで同じジョブが黙って消える重複排除IDの扱いと、7.0.4で増えた設定を扱います。

## まとめ

- 7.0系の動作要件はRuby 3.2以上・Rails 7.2以上（Active Jobで使う場合）・aws-sdk-sqs 1.66以上です。Ruby 3.1のままでは7.0系へ上げられません。
- 導入はGemfileへの追加、キューの作成、`bundle exec shoryuken`での起動の3段階です。Railsのジョブを処理させるなら起動時に`-R`を付けます。
- 多重度は`concurrency`で指定し、既定値は25スレッドです。重み付きキューの重みは初期配分ではなく上限値です。
- Active Job拡張は`shoryuken`を読み込んだ瞬間に1回だけ判定されます。Active Jobより先に読むと`NameError`で落ちます。
- FIFOキューでは既定で内容から重複排除IDが作られ、同じ内容の投入は5分間で1件に潰れます。Active Job経由は7.0.3、`perform_async`などの直接送信は7.0.4で、それぞれ止める設定が入りました。
- 独自ワーカーの`retry_intervals`は再試行を打ち切りません。回数の上限はSQSのリドライブポリシーで決めます。

## SQS専用ワーカーとしての立ち位置とSidekiqからの選び分け

Shoryukenが担うのは「SQSからメッセージを取り出し、スレッドプールでワーカーに渡し、成功したら削除する」というループだけです。キューの永続化・可視性制御・順序保証はすべてSQS側の機能で、gemはその消費者に徹しています。この分担が、他のジョブ基盤との違いをそのまま決めます。

### Sidekiq・Solid Queueとの分担基準

| 観点     | Shoryuken      | Sidekiq       | Solid Queue          |
| ------ | -------------- | ------------- | -------------------- |
| キューの実体 | Amazon SQS     | Redis         | RDB                  |
| 運用対象   | ワーカープロセスのみ     | Redisとワーカー    | DBとワーカー              |
| 順序保証   | FIFOキューで可      | なし            | なし                   |
| 再試行の主体 | SQSの可視性タイムアウト  | Sidekiq独自の再試行 | Active Jobのretry\_on |
| 管理画面   | なし（CloudWatch） | Web UI同梱      | Mission Control      |

選定の分かれ目は再試行の主体です。Sidekiqは失敗ジョブを自前のRedis上に積み直しますが、Shoryukenは失敗メッセージをSQSへ戻すだけで、何回で諦めるかの判断もSQSに委ねます。ジョブの信頼性設計がコードではなくキューの属性設定になる、ということです。すでにAWS上で動いていてワーカープロセス以外を増やしたくないなら有力な選択肢になります。逆に管理画面でジョブを目視したい、失敗ジョブを画面から再実行したいという運用要件が強いなら、[Sidekiqとは？Rails 8.1での導入・リトライ・Web UI設定【Sidekiq 8.1.7】](/tech/details/7843/)で扱っている構成のほうが手数は少なくなります。

### 採用前に確認したい開発の継続状況

SQSという狭い用途のgemなので、保守が続いているかは採用判断に直結します。2026年10月17日にGitHubとRubyGemsのAPIで確認したところ、[GitHubのruby-shoryuken/shoryuken](https://github.com/ruby-shoryuken/shoryuken)はアーカイブされておらず、直近のpushは同日（日本時間）、スター数は2,127でした。[RubyGems.org](https://rubygems.org/gems/shoryuken)の累計ダウンロードは34,045,634件です。6.2.1（2024年2月）のあと1年3か月ほどリリースが途絶えましたが、2025年5月のアルファ版を経て2026年1月19日に7.0.0が出て、以降は7.0.1（2月）・7.0.2（4月）・7.0.3（7月）・7.0.4（9月）と続いています。空白期間だけを見て開発停止と判断するのは誤りです。

## Shoryukenのインストールと最初のジョブの起動

公式の[Getting Started](https://github.com/ruby-shoryuken/shoryuken/wiki/Getting-Started)に沿って、gemの追加からジョブの投入までを順に見ます。

### 7.0.4の動作要件と6.2.1との違い

| 項目             | 6.2.1（2024-02-09） | 7.0.4（2026-09-23）     |
| -------------- | ----------------- | --------------------- |
| gemspecのRuby下限 | 指定なし              | 3.2.0以上               |
| 対応Rails        | 7.1以前を含む          | 7.2以上                 |
| SQS依存          | aws-sdk-core 2以上  | aws-sdk-sqs 1.66.0以上  |
| 読み込み方式         | 個別require         | zeitwerk（2.6以上・3.0未満） |

値は各版のgemspecとGetting Startedの記載です。GitHubのREADMEは長く「Ruby 3.0 or greater」のままでしたが、2026年10月16日（日本時間）のコミット（#1064）でgemspecに合わせて「Ruby 3.2 or greater」へ直りました。古いREADMEを引用した解説記事を見てRuby 3.1のまま上げようとすると、bundle installの段階で解決に失敗します。CHANGELOGの7.0.0にも「Drop support for Ruby 3.1」とあり、3.1系を使い続ける場合は6.x系に留まります。

```
$ gem install shoryuken -v 7.0.4
Successfully installed shoryuken-7.0.4

$ ruby -e "s = Gem::Specification.find_by_name('shoryuken','7.0.4'); puts s.required_ruby_version"
>= 3.2.0
```

### Gemfileへの追加とキューの作成

Gemfileに`gem 'shoryuken'`を書いて`bundle install`を実行します。キューはAWSコンソールで作ってもかまいませんが、gemに同梱のCLIでも作れます。

```
# 標準キュー
$ bundle exec shoryuken sqs create hello

# 名前が .fifo で終わると FifoQueue 属性が自動で付く
$ bundle exec shoryuken sqs create orders.fifo
```

`sqs create`は、キュー名が`.fifo`で終わるときに`FifoQueue`属性を自動で付けます（7.0.4のCLI実装で確認）。CLIにはこのほか`ls`・`purge`・`dump`・`mv`・`requeue`があり、デッドレターキューの中身を確認したり戻したりする作業に使えます。`dump`と`mv`は7.0.3まで実際のSQSで途中までしか処理しないことがあり、7.0.4でロングポーリングを使って最後まで読み切るよう直りました。

### Plain RubyとRailsで異なる起動コマンド

Railsを使わない場合は、`Shoryuken::Worker`をincludeしたクラスを書き、そのファイルを`-r`で読み込ませて起動します。

```
# hello_worker.rb
class HelloWorker
  include Shoryuken::Worker
  shoryuken_options queue: 'hello', auto_delete: true

  def perform(sqs_msg, name)
    puts "Hello, #{name}"
  end
end

# 起動（別のプロセスから HelloWorker.perform_async('Ken') で投入する）
$ bundle exec shoryuken -q hello -r ./hello_worker.rb
```

RailsでActive Jobのジョブを処理させるなら、起動時に`-R`（`--rails`）を付けます。これを付け忘れるとRailsアプリもActive Jobも読み込まれず、起動ログに`No worker supplied for hello`という警告が出ます（7.0.4の起動時検証の実装）。投入側は成功するため、ワーカー側のこの警告を見落とすとジョブが実行されない原因に気づけません。設定ファイルは`-C`で渡します。

```
$ bundle exec shoryuken -R -C config/shoryuken.yml
```

起動オプションの`-t`はヘルプ上「Hard shutdown timeout」と説明される値で、次の章で見る`timeout`と同じものです。

### IAMで許可するSQSのアクション

認証情報はAWS SDK for Rubyの通常の解決順（環境変数・共有設定ファイル・ECSタスクロールやEC2インスタンスプロファイル）で読まれ、Shoryuken独自の認証設定はありません。7.0.4のソースが呼んでいるSQS APIから、必要な権限は次のとおりです。

| 権限                          | 使われる場面                        |
| --------------------------- | ----------------------------- |
| sqs:GetQueueUrl             | キュー名からURLを引く                  |
| sqs:GetQueueAttributes      | FIFO判定・可視性タイムアウト取得            |
| sqs:ReceiveMessage          | メッセージの受信                      |
| sqs:DeleteMessage           | 処理済みメッセージの削除（バッチ版も含む）         |
| sqs:ChangeMessageVisibility | retry\_intervals・可視性タイムアウトの延長 |
| sqs:SendMessage             | ジョブの投入（バッチ版も含む）               |

AWSの[バッチ操作の説明](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-batch-api-actions.html)にあるとおり、`SendMessageBatch`や`DeleteMessageBatch`には個別の権限を設定できず、`SendMessage`や`DeleteMessage`の許可がそのままバッチ版にも効きます。ワーカー用のロールと投入側（Webアプリ）のロールを分けるなら、投入側は`GetQueueUrl`・`GetQueueAttributes`・`SendMessage`が基本です。キューをカスタマーマネージドKMSキーで暗号化している場合は、[AWSの鍵管理の説明](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html)のとおり、送信側に`kms:GenerateDataKey`と`kms:Decrypt`、受信側に`kms:Decrypt`の許可が追加で要ります。SQSとIAM・ECSの構成をまとめて設計する場合は、[AWSのインフラ構築支援](/service/system/aws/)でも相談を受けています。

ローカル開発では実際のSQSの代わりに互換サーバーへ向けられます。Shoryuken自身の結合テストは2026年3月にLocalStackからElasticMQへ切り替わっており、CLIは`-e http://localhost:9324`のようにエンドポイントを指定できます。LocalStackを使う場合の判断材料は[LocalStackとは？AWSをローカルで動かす手順と有料化後の料金・判断基準](/tech/details/17634/)にまとめています。

## shoryuken.ymlの構成とジョブの多重度の決め方

設定は`config/shoryuken.yml`に集約し、起動時に読み込ませます。ここで指定する`concurrency`が、1プロセスが同時に処理するジョブの多重度です。

### 既定値25が意味するスレッド数

何も書かなければ既定値が使われます。7.0.4をロードして確認した値が次のものです。

```
require 'shoryuken'
pp Shoryuken.options.slice(:concurrency, :timeout, :thread_priority, :delay)

# => {concurrency: 25, timeout: 8, thread_priority: -1, delay: 0.0}
```

`concurrency: 25`は、そのプロセスが最大25件のメッセージを並行して処理するという意味です。実際の上限を決めるのはこの数値ではなく下流の資源で、ジョブがDBへ書き込む処理ならコネクションプールが先に頭打ちになります。RailsのプールサイズがShoryukenの多重度より小さいと、超過したスレッドがコネクション待ちで滞留し、その間もメッセージの可視性タイムアウトは進みます。多重度を上げるときはプールサイズを同数以上に合わせてください。

`timeout: 8`はジョブの実行時間制限ではなく、停止時に実行中のワーカーを待つ秒数です。この秒数を過ぎると実行中のスレッドは強制終了され、削除されなかったメッセージは可視性タイムアウトの経過後に再配信されます。7.0.2まではUSR1・TSTPによる穏やかな停止がこの値を無視して無期限に待ち、TSTPのあとにUSR1を送るとプロセスが固まる不具合もありました（どちらも7.0.3で修正）。デプロイのたびに古いワーカーが残るなら、まず版を確認してください。

### ロングポーリングとリクエスト課金

SQSはメッセージ単位ではなくAPIリクエスト単位の課金で、AWSは[料金ページ](https://aws.amazon.com/sqs/pricing/)で「すべてのAmazon SQSアクションが1リクエストとして数えられる」と説明しています。1回の受信で取れるのは最大10件です。

注意したいのは、Shoryukenの受信処理が既定では`wait_time_seconds`を送らない点です（7.0.4のFetcher実装で確認）。この場合はキュー属性`ReceiveMessageWaitTimeSeconds`の値が使われ、作成時の既定である0のままだとショートポーリングになります。空のキューを何度も問い合わせることになり、リクエスト数がそのまま請求に乗ります。[AWSのドキュメント](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html)によればロングポーリングの待ち時間は最大20秒です。キュー属性で20秒にするか、初期化子で受信オプションに渡します。

```
# config/initializers/shoryuken.rb
Shoryuken.sqs_client_receive_message_opts = { wait_time_seconds: 20 }
```

FIFOキューは例外で、バッチ処理のワーカーでない限り1回の受信で1件しか取りません。同じメッセージグループの複数件を別スレッドが同時に処理しないための制限で、FIFOのスループットはグループの分け方で決まります（後述）。

### 重み付きキューによる優先度配分

複数キューを扱うときは、キュー名に重みを添えて記述します。設定ファイルはERBとして評価されるため、環境変数の埋め込みも可能です。

```
# config/shoryuken.yml
concurrency: 25
delay: 25
queues:
  - [high_priority, 6]
  - [default, 2]
  - [low_priority, 1]
```

ここで誤解されやすいのが重みの効き方です。指定した数値は「常にその比率で読む」という意味ではなく、ローテーションに確保できる枠の上限値です。既定のWeightedRoundRobin戦略は初期化時にキューの重複を除いたリストから始めるため、起動直後は重みに関係なく全キューが1枠ずつの均等巡回になります。

```
# 起動直後のローテーション（まだメッセージが見つかっていない）
high_priority -> default -> low_priority -> high_priority -> default -> low_priority

# high_priority でメッセージが見つかるたびに枠が1つずつ増える
INFO: Increasing high_priority weight to 2, max: 6
INFO: Increasing high_priority weight to 3, max: 6
...
INFO: Increasing high_priority weight to 6, max: 6
```

つまり重みは、混んでいるキューへ処理を寄せていくための上限であって、初期状態の配分ではありません。散発的にしかジョブが入らないキューでは重みを大きくしても効果が出にくく、常時流量のあるキューでこそ差が出ます。`delay`は、メッセージが見つからなかったキューをポーリング対象から外しておく秒数です。既定の0のままだと空振りの受信が積み上がるため、ロングポーリングを使わない構成では25秒程度を明示しておくと無駄が減ります。

## Active Job連携の読み込み順と拡張の初期化

Shoryuken独自のワーカークラスを書く方法もありますが、Railsアプリでは[Rails Active Jobとは？非同期ジョブ処理の実装とSolid Queue・リトライ設定](/tech/details/3988/)で解説しているActive Job経由が標準です。アダプタを差し替えるだけで既存のジョブクラスをそのまま流用できます。

### アダプタ指定とキュー名の対応

```
# config/application.rb
config.active_job.queue_adapter = :shoryuken
```

`queue_as`に書いたキュー名が、そのままSQSのキュー名として解決されます。`queue_as :default`ならSQS上にも`default`という名前のキューが必要で、存在しない場合は`Shoryuken::Errors::QueueNotFoundError`が上がります。7.0.0でエラークラスが専用の名前空間に整理され、以前は`RuntimeError`や`ArgumentError`で区別できなかった失敗を型で捕まえられるようになりました。

### 読み込み順が崩れたときに出る2つの例外

Shoryukenは、gem本体を読み込んだ時点でActive Jobが存在するかどうかを見て、Active Job拡張を読むかどうかを決めています。

```
# shoryuken.rb の末尾（7.0.4）
if Shoryuken.active_job?
  require 'active_job/extensions'
  require 'active_job/queue_adapters/shoryuken_adapter'
  require 'active_job/queue_adapters/shoryuken_concurrent_send_adapter'
end
```

この判定は`shoryuken`を読み込んだ瞬間に1回だけ行われます。Active Jobより先にShoryukenが読み込まれると分岐が偽になり、拡張もアダプタも定義されません。あとからActive Jobを読んでも手遅れです。

```
require 'shoryuken'
p Shoryuken.active_job?   # => nil ← この時点の判定で拡張を読むかが決まる

require 'active_job'
p Shoryuken.active_job?   # => "constant"（後から読んでも判定はやり直されない）

p ActiveJob::Base.method_defined?(:sqs_send_message_parameters)   # => false

ActiveJob::Base.queue_adapter = :shoryuken
# => NameError: uninitialized constant ActiveJob::QueueAdapters::ShoryukenAdapter
```

紛らわしいのは、`Shoryuken.active_job?`自体は呼び出した時点でActive Jobの有無を評価するため、順序を誤った後に確認すると`"constant"`を返してしまう点です。読み込みが済んでいるかどうかは`method_defined?`側で判断してください。

アダプタ定数だけを個別にrequireしていて`active_job/extensions`が読まれていない場合は、ジョブ投入まで進んでから`NoMethodError: undefined method 'sqs_send_message_parameters'`で落ちます。どちらの文面もキュー設定にもAWS認証にも触れないため、設定ファイルやIAMポリシーを疑って時間を溶かしがちです。Railsアプリ内ではフレームワークが先にActive Jobを読むため通常は起きませんが、rakeタスクやスタンドアロンのワーカースクリプト、初期化子で個別にrequireしている構成では順序が崩れます。

### perform\_all\_laterによる一括送信

7.0.0でRails 7.1以降の一括投入に対応しました。`ActiveJob.perform_all_later`に複数ジョブを渡すと、SQSの`SendMessageBatch`にまとめられます。

```
ActiveJob.perform_all_later((1..23).map { |n| ReportJob.new(n) })

# 実測: send_message_batch の呼び出し 3回（entries 10件・10件・3件）
```

SQSのバッチ上限に合わせて10件ずつ分割されます。同一キューへ100件を投入する場合、送信APIの呼び出しは100回から10回に減ります。ただし、課金上はペイロード64 KBごとに1リクエストとして数えるため、料金が必ず10分の1になるわけではありません。あわせて7.0.0ではRails 8.1のActive Job Continuationsにも対応し、アダプタが`stopping?`を実装しています。デプロイでワーカーが停止に入ったことをジョブ側へ伝え、長時間ジョブを途中から再開させる設計は[Active Job Continuationsとは？Rails 8.1のstep・cursorでジョブを中断・再開する方法](/tech/details/8853/)で扱っています。

## FIFOキューでジョブが消える原因は重複排除IDの二層構造

FIFOキューを使うと、同じジョブを2回投入したのに1回しか実行されないという現象が起きます。バグではなく、重複排除IDが二か所で生成されている結果です。7.0.4で設定が1つ増え、組み合わせで挙動が変わるようになりました。

### 既定で付く内容ベースの重複排除ID

1層目はActive Jobアダプタです。FIFOキュー宛のメッセージに、シリアライズしたジョブ本体から`job_id`と`enqueued_at`を除いた内容のSHA-256を重複排除IDとして付けます。同じジョブクラスに同じ引数を渡せば、投入のたびに同じIDになります。2層目はキュー層の`Shoryuken::Queue`で、IDが未指定のときにメッセージ本文全体のSHA-256を付けます。独自ワーカーの`perform_async`はこちらを通ります。

```
FifoJob.perform_later(1)  # dedup_id = ec89062088c630...
FifoJob.perform_later(1)  # dedup_id = ec89062088c630...  ← 一致
FifoJob.perform_later(2)  # dedup_id = ec910290bcbaad...  ← 引数が違えば別ID

RawWorker.perform_async('hello')  # dedup_id = 2cf24dba5fb0a3...（本文 "hello" のSHA-256）
RawWorker.perform_async('hello')  # dedup_id = 2cf24dba5fb0a3...  ← 一致

message_group_id = "ShoryukenMessage"  # 全メッセージ共通の既定値
```

[SendMessageのAPIリファレンス](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API%5FSendMessage.html)によれば、同じ重複排除IDのメッセージは送信には成功するものの、5分間の重複排除インターバル内は配信されません。ネットワーク再送の対策としては正しい挙動です。しかし「同じ利用者に同じ通知を5分以内に2回送る」「同じレポートIDで再集計をかける」といった、意図的に同じ引数で2回実行したいジョブでは、2件目が例外もログも出さずに消えます。送信元は成功したように見えるため、発覚が遅れます。

`message_group_id`が全メッセージ共通の固定値である点も見落とされがちです。FIFOキューはグループ内を直列に処理するため、既定のままだとすべてのジョブが1グループに入り、`concurrency`を25にしてもFIFOキューの処理は1件ずつしか進みません。並行性が必要なら、テナントIDや注文IDなど分割できる値をグループIDに指定します。

### 7.0.3と7.0.4で追加された2つの設定

7.0.3（2026年7月10日）でActive Job側の生成を止める`active_job_fifo_message_deduplication`が、7.0.4（2026年9月23日）でキュー層の生成を止める`fifo_message_deduplication`が入りました。どちらも既定は`true`で、明示的に渡した`message_deduplication_id`は常に優先されます。同一引数で2回投入して組み合わせごとに確かめた結果が次の表です。

| 経路             | active\_job\_fifo… | fifo\_message\_deduplication | 付くID            | 同一内容の2件目 |
| -------------- | ------------------ | ---------------------------- | --------------- | -------- |
| Active Job     | true（既定）           | true（既定）                     | 引数由来で一致         | 消える      |
| Active Job     | false              | true                         | 本文全体（job\_id込み） | 配信される    |
| Active Job     | false              | false                        | なし              | キュー属性次第  |
| perform\_async | （無関係）              | true（既定）                     | 本文由来で一致         | 消える      |
| perform\_async | （無関係）              | false                        | なし              | キュー属性次第  |

```
# config/initializers/shoryuken.rb
Shoryuken.active_job_fifo_message_deduplication = false   # 7.0.3以降

# 実測（同一引数で2回）: 7df3d3dac502e8... と 3717c2668ee080...  不一致
# ※値は job_id を含むため実行ごとに変わる
```

Active Jobで同じ内容を投入回数だけ実行させたいなら、`active_job_fifo_message_deduplication`だけを`false`にするのが最短です。キュー層の生成が残り、本文に毎回異なる`job_id`が入るので、IDは投入ごとに変わります。

両方を`false`にすると、送信パラメータから重複排除IDそのものが消えます。SendMessageのAPIリファレンスには「`MessageDeduplicationId`を渡さず、キューに`ContentBasedDeduplication`も設定していなければ送信は失敗する」とあるため、この組み合わせはキュー属性で内容ベースの重複排除を有効にしているか、IDを自分で渡す前提でしか使えません。内容ベースの重複排除は本文のSHA-256で判定するため、`job_id`を本文に含むActive Jobは投入ごとに別IDになりますが、`perform_async`で同じ本文を送れば2件目はやはり消えます。独自ワーカーで同じ本文を複数回送る必要があるなら、業務上のキーを`message_deduplication_id`として渡してください。

```
RawWorker.perform_async('hello', message_deduplication_id: 'order-42')
# => dedup_id = "order-42"（指定値がそのまま使われる）
```

判断基準は、同じ内容の投入を同一の業務イベントとして扱うかどうかです。同じイベントの再送を1回に丸めたいなら既定のまま、同じ内容でも回数分の実行が業務上必要なら設定を変えるか、IDを明示します。

### FIFOキューにwaitを付けたときの例外

FIFOキューはメッセージ単位の遅延配信に対応していません。Active Jobの`set(wait:)`をFIFOキュー宛に使うと、7.0.1以降は専用の例外で止まります。

```
FifoJob.set(wait: 3).perform_later(1)

# => Shoryuken::Errors::FifoDelayNotSupportedError:
#    FIFO queue 'orders.fifo' does not support per-message delays.
#    When using ActiveJob retry_on with FIFO queues, set `wait: 0`.
```

実務で問題になるのは`retry_on`との組み合わせで、`retry_on`は既定で3秒待つため、FIFOキューを使うジョブに何気なく付けると再試行のたびにこの例外に当たります。FIFOキューでは`wait: 0`を明示してください。版によって例外の型も違います。7.0.0は`ArgumentError`を送出していましたが、7.0.1で`FifoDelayNotSupportedError`に置き換わりました。後者は`Shoryuken::Errors::BaseError`の子で`ArgumentError`を継承していないため、7.0.0時点で書いた`rescue ArgumentError`は7.0.1以降で素通りします。

## retry\_intervalsの再試行間隔とDLQによる打ち切り

Shoryuken独自ワーカーでは`retry_intervals`で再試行間隔を指定できます。指数バックオフの設定として紹介されることが多いのですが、この配列は「何回まで試すか」を表していません。

### 配列を使い切った後の挙動

間隔を決める処理を7.0.4で実際に呼び出し、失敗回数ごとの戻り値を並べた結果が次のものです。

```
class MyWorker
  include Shoryuken::Worker
  shoryuken_options queue: 'default', auto_delete: true,
                    retry_intervals: [1, 5, 25, 125]
end

# 失敗回数 1〜8 回目に設定される可視性タイムアウト（秒）
# => [1, 5, 25, 125, 125, 125, 125, 125]
```

4回目で配列を使い切った後も、最後の値である125秒が使われ続けます。再試行が止まることはありません。7.0.3のCHANGELOGでも、「最後の間隔のあとで諦める」と書かれていたドキュメントの説明が誤りだったとして訂正されています。配列の長さを再試行回数の上限だと理解していると、失敗したジョブが延々とキューに残ります。間隔を動的に決めたい場合は呼び出し可能オブジェクトも渡せ、`->(attempts) { attempts * 10 }`なら1回目から順に10・20・30・40秒が返りました。

### リドライブポリシーによる受信回数の制限

再試行の上限はgem側ではなくSQS側で設定します。デッドレターキューを作り、ソースキューにリドライブポリシーを付けます。

```
{
  "deadLetterTargetArn": "arn:aws:sqs:ap-northeast-1:123456789012:default-dlq",
  "maxReceiveCount": "5"
}
```

AWSの定義では`maxReceiveCount`は「デッドレターキューへ移される前に、消費者がメッセージを受信できる回数」です。5を指定すれば5回目の受信までは処理が試みられ、それでも削除されなければDLQへ移ります。`retry_intervals`は間隔だけを決め、回数はここで決まるという分担です。リドライブポリシーの無いキューでは、失敗ジョブがメッセージ保持期間の上限まで残り続けます。標準キューとFIFOキューの属性設計、DLQの置き方は[Amazon SQSとは？標準キューとFIFOの違い・可視性タイムアウトとDLQ設計を解説](/tech/details/17241/)で詳しく扱っています。

### 再試行させたくない失敗と処理時間の長いジョブ

入力データが不正な場合など、何度試しても成功しない失敗まで再試行するのは無駄です。`shoryuken_options`に`non_retryable_exceptions`を指定すると、該当する例外が出たメッセージは再試行されずに削除されます。値には例外クラスの配列のほか、例外を受け取って真偽を返す呼び出し可能オブジェクトも渡せます。ただし7.0.2までは、`retry_intervals`を同時に指定するとこの設定が無視され、不正なメッセージが最後の間隔で再試行され続ける不具合がありました（7.0.3で修正）。両方を使うなら7.0.3以上が前提です。

`auto_delete: true`はジョブが例外なく終わった時点で自動削除します。`false`のままだとワーカー内で`sqs_msg.delete`を呼ばない限りメッセージが残り、可視性タイムアウトの経過後に再配信されます。処理が成功しているのにジョブが繰り返し実行される場合は、削除漏れや削除APIの失敗、可視性タイムアウトの超過を確認します。標準キューでは、サービス仕様による重複配信も起こりえます。処理時間がキューの可視性タイムアウトを超えうるジョブには`auto_visibility_timeout: true`を付けます。7.0.4の実装では、キューの可視性タイムアウトが切れる5秒前に同じ秒数だけ延長し直すタイマーが動きます（可視性タイムアウトが5秒以下なら半分の時点）。

## 6.x系から7.0系への移行で確認する項目

| 変更点                     | 影響                        | 対応                             |
| ----------------------- | ------------------------- | ------------------------------ |
| 専用エラークラスの導入             | rescue の条件が外れる            | Shoryuken::Errors 配下へ変更        |
| FIFO遅延の例外型変更（7.0.1）     | rescue ArgumentError が素通り | FifoDelayNotSupportedError を捕捉 |
| Shoryuken::Shutdown の削除 | 参照箇所で NameError           | 該当コードを削除                       |
| core\_ext.rb の廃止        | 拡張メソッドが消失                 | Helpers 配下の関数へ置換               |
| 停止処理の修正（7.0.3）          | 停止が無期限に待つ                 | 7.0.3以上へ上げる                    |

手が止まりやすいのはエラークラスの整理です。6.x系では不正な設定もキュー未検出も`ArgumentError`や`RuntimeError`で上がっていたため、それらを広く捕まえるコードが残っている現場は少なくありません。7.0系の例外は`Shoryuken::Errors::BaseError`の子で`ArgumentError`を継承しないので、既存の`rescue`を素通りして落ちます。移行時は`rescue ArgumentError`と`rescue RuntimeError`を全文検索し、Shoryuken由来の例外を捕まえている箇所を`Shoryuken::Errors::BaseError`へ寄せてください。

上げる先の版は7.0.4を勧めます。7.0.3では停止処理の不具合がまとめて直り、7.0.4では`perform_async`に渡したオプションのハッシュが書き換えられ、使い回すと2回目以降の`:queue`が消えて既定のキューへ送られる不具合が直っています。7.0.0〜7.0.2で止めると、移行後に別の原因で詰まります。SQSをLambdaやEventBridgeと組み合わせる構成との比較は[EventBridgeとSQS・Lambdaの非同期構成｜キューポリシー・部分バッチ応答・DLQの置き場所](/tech/details/6034/)が参考になります。

## よくある質問

### Shoryukenの読み方と、gemとしての正式な入手先は？

読み方は「しょうりゅうけん」です。gemはRubyGems上の`shoryuken`、ソースはGitHubの`ruby-shoryuken/shoryuken`で公開されています。以前は作者個人アカウントの`phstc/shoryuken`にありましたが組織アカウントへ移管され、旧URLは現在のリポジトリに転送されます。2026年10月17日時点の最新版は7.0.4です。

### Railsで使うとき、SidekiqのようなWeb管理画面はありますか？

同梱されていません。ジョブの滞留状況はSQSのCloudWatchメトリクスで見ます。`ApproximateNumberOfMessagesVisible`が未処理件数、`ApproximateAgeOfOldestMessage`が最も古いメッセージの経過時間です。失敗ジョブの再実行も画面からではなく、デッドレターキューのリドライブ機能か`shoryuken sqs requeue`でソースキューへ戻す操作になります。

### ジョブの多重度はどこで指定し、どこまで上げられますか？

`shoryuken.yml`の`concurrency`か、起動オプションの`-c`で指定します。既定値は25で、これがそのプロセスの最大同時処理スレッド数です。DBを使うジョブでは、Railsのコネクションプールを多重度以上にします。FIFOキューではメッセージグループを分けない限り多重度を上げても直列のままです。

### FIFOキューで同じジョブが1回しか実行されないのはなぜですか？

重複排除IDが原因である可能性が高いです。Active Jobアダプタはジョブクラスと引数から、`perform_async`はメッセージ本文から、それぞれSHA-256の重複排除IDを自動で付けます。同じ内容なら同じIDになり、SQSの5分間の重複排除インターバル内では2件目が配信されません。エラーは出ません。Active Jobなら7.0.3以降で`Shoryuken.active_job_fifo_message_deduplication = false`を設定します。`perform_async`なら、業務上別の実行ごとに異なる`message_deduplication_id`を渡します。7.0.4以降の`Shoryuken.fifo_message_deduplication = false`でgem側の生成を止めても、キューの`ContentBasedDeduplication`は本文からSHA-256を作るため、同じ本文は結局まとめられます。

### retry\_intervalsに指定した回数を超えたらジョブは諦めますか？

Shoryuken独自ワーカーの`retry_intervals`は諦めません。`[1, 5, 25, 125]`なら4回目以降はずっと125秒間隔で再試行が続きます。打ち切りたい場合はSQS側でデッドレターキューとリドライブポリシーを設定し、`maxReceiveCount`で受信回数の上限を決めてください。なおActive Job経由なら、`retry_on`には既定で初回を含む5回の試行上限があります。ただし、上限到達時にブロックなどで例外を処理しなければ例外がShoryukenへ伝わり、SQSによる再配信は続きます。

## 関連記事

- [Sidekiqとは？Rails 8.1での導入・リトライ・Web UI設定【Sidekiq 8.1.7】](/tech/details/7843/)
- [Rails Active Jobとは？非同期ジョブ処理の実装とSolid Queue・リトライ設定](/tech/details/3988/)
- [Amazon SQSとは？標準キューとFIFOの違い・可視性タイムアウトとDLQ設計を解説](/tech/details/17241/)
- [Active Job Continuationsとは？Rails 8.1のstep・cursorでジョブを中断・再開する方法](/tech/details/8853/)
- [EventBridgeとSQS・Lambdaの非同期構成｜キューポリシー・部分バッチ応答・DLQの置き場所](/tech/details/6034/)

---

出典: [Shoryuken（Ruby gem）とは？SQSワーカーの導入・設定とActive Job連携・リトライ設計【7.0.4対応】](<https://www.issoh.co.jp/tech/details/3429/>)（株式会社一創）
