そのRequest Scope、Async Local Storageでいいんじゃない?
はじめに
Dress Code Advent Calendar 2025 の 16 日目の記事です。
突然ですが、Dress Code 株式会社 ではバックエンドに NestJS を採用しております。
NestJS は高機能であるが故に、利用する機能を間違えると本来の力を発揮しづらいフレームワークであると感じています。
今回は、NestJS のスコープとして、Request Scope の採用についてもう一度検討をしても良いのではないか、という記事となります。
もし、検討せずに Request Scope を選択してしまった方の再考のきっかけや、今悩んでいる人の役に立てれば幸いです。
結論
Request Scope の利用用途としてリクエスト単位で独立する情報を格納する"だけ"であれば、パフォーマンスが劣化する可能性が高いので Async Local Storage の利用を検討しましょう。
全て公式ドキュメントに記載の通りではありますが、せっかくなので深掘りしていこうと思います。
前提
デフォルトスコープについて
NestJS のモジュールに登録される class は特別指定がなければ Default Scope として取り扱われ、実態は Singleton のクラスになります。
明示的に Request / Transient Scope として宣言することで Inject するインスタンスを可変にできます。
In Nest, modules are singletons by default, and thus you can share the same instance of any provider between multiple modules effortlessly.
ref. https://docs.nestjs.com/modules#shared-modules
Request Scope の Bubble up について
Request Scope は bubble up されます。
つまり、依存しているクラスが Request Scope であると自身も Request Scope となります。
The REQUEST scope bubbles up the injection chain. A controller that depends on a request-scoped provider will, itself, be request-scoped.
ref. https://docs.nestjs.com/fundamentals/injection-scopes#scope-hierarchy
これぱっと見では分かりづらいんですが、 Controller -> Service -> Repository のような依存関係になっているとして、Repository が Request Scope だと Controller/Service も Request Scope になってしまう、という性質です。
依存する側が Singleton だと Repository のどの Instance を持つべきなのか定まらないですからね。
課題
実際に弊社の実装でもそうなっていたのですが、リクエストのメタデータあるいはコンテキストとして保持しておきたいデータを Request Scope として保持してしまっていました。マルチテナントで提供する SaaS になると、どのテナントからのリクエストか、という情報はリクエスト単位で保持しておきたいのです。
Request Scope としてリクエスト単位で一意なインスタンスを生成できるようにすると、DI によってテナントやユーザーの情報にアクセスできる一方で以下のような課題が暗黙的に発生してしまっていました。
- Request Scope は bubble up するので、Repository や Query Service といった終端でアクセスすると依存する全ての class も Request Scope になってしまう
- 上記によって、リクエストごとに Controller を含め多数のクラスのインスタンス化が行われる。これによってパフォーマンスも悪化する
- 特に依存関係の多い controller だと、インスタンス化するクラスの絶対量が多くなり、パフォーマンスの悪化が大きくなる
解決策
結論に書いた通りですが、解決策は公式ドキュメントにすでに書かれています。
Node.js の v16 で安定版がリリースされた Async Local Storage を使うことでリクエスト単位のコンテキストを隔離してアクセスできるようにしましょう、ということです。
詳しくはここで述べませんが、リクエストごとに採番される(厳密に言えば非同期処理単位)asyncId ごとに分離された store に情報を格納することでリクエストごとの情報の受け渡しを実現しよう、ということです。
なお、本番導入の際は、ALS をそのまま使うより nestjs-cls などのライブラリを使うと便利です
本記事の役割としてはこの公式ドキュメントの紹介だけでも価値としては十分発揮できていると思いますが、せっかくなので定量的に比較してみましょう。
再現コード
ちょっとした再現コードを書いてみたので共有します。
環境の差分をなくすために Docker 上で動作する NestJS のアプリケーションです。
- Default Scope のみ
- Request Scope を利用
- Async Local Storage を利用(wrapper である nestjs-cls を利用)
この 3 つの実装において CPU Usage / Memory Utilization / Latency のメトリクスを比較し、実際どれくらい差があるのかを比較してみました。
リポジトリ
README に記載の通りではありますが、3種類のエンドポイントを用意して負荷テストを実施し、計測するような形式になっています。
環境差分をなくすために docker-compose でリソースの制約をかけています(1CPU, 512M)。
負荷をかける仕組みには autocannon を、計測には Node.js の V8 Engine に備わっている APIを利用しています。
結果
| パターン | RPS | Latency | CPU(avg%) | Memory(peak) | 備考 |
|---|---|---|---|---|---|
| Singleton | 100% (5661/s) | 100% (17.21ms) | 100% (99.9%) | 100% (236MB) | ベースライン |
| Request Scope | 77.6% (4395/s) | 129.6% (22.31ms) | 100.1% (100.0%) | 100% (236MB) | memAvg 88.5% (172MB) と低いが RPS 低下 |
| CLS | 105.1% (5951/s) | 94.8% (16.32ms) | 100.0% (99.9%) | 100% (236MB) | memAvg 78.0% (152MB) と最小 |
備考:
Latency p95/p99: Singleton 60/89ms, Request Scope 71/105ms, CLS 59/85ms
- 計測環境: Docker cgroup 1CPU / 512MB
- 負荷条件: autocannon 100 接続・30 秒
- CPU 100% は上限張り付き(環境依存)。RPS/Latency はこの条件での相対比較。
所見
Singleton と Async Local Storage を使った CLS のパターンは RPS / Latency どちらも大きくは変わらないように見受けられます。
一方で、Request Scope に関しては有意に RPS が約 20%低下しているのが分かります。
※CLS が Singleton より RPS がよく見えますがおそらく誤差だと思われます・・・
ただ、メモリに関しては大きな違いは見受けられませんでした。
一時的に heap が使用されることで負荷がかかるはずではありますが、計測方法が悪かったのか理解に齟齬があるのかは分かりません・・・。
可能性があるとしたら CPU が 100%に張り付いているので GC が働いた結果メモリの使用量には影響を及さなかったが、RPS が下がっていることから CPU は余分に使われたと考えることもできそうです。
少なくとも計測した範囲においてはパフォーマンスにのみ差がある、と言えるでしょう。
Request Scope を使うべき場面
上述の通り、テナント ID やユーザー ID をリクエストごとに引き回す場合は Async Local Storage を使うのが良いでしょう。
一方で、テナント ID をもとに DB の接続情報を変えたかったり、IAM Role を assume してたりするケースは状態の持ち方が別なので Request Scope でやるべきでしょう。
つまり、ライフサイクルをリクエストごとに完結させたいケースにおいてはむしろ Request Scope の方が合っていると思われます。
データストアをスキーマあるいはデータベースで分離しているケースや、同じテーブルからの読み込みが多く cache を持っておきたいケースなどが考えられます。
アーキテクチャによってはそもそも不要であることのほうが多いのかな、と直感的に感じています。
注意点
Async Local Storage は別のプロセスには引き継がれません。worker threadであっても同様です。
NestJS だと暗黙的に使われることはないかなと思いますが、ライブラリが Worker Thread を立てるようなケースでは注意が必要です。
同じように、Queue や PubSub を用いているようなケースや microservice の構成を取っている場合は明示的に引き継ぐ必要があります。
終わりに
公式ドキュメントに書かれていても、なかなか最初から全部を読んで脳内メモリに置き続けるのも、常に追い続けるのも難しいですよね。
今回これに気づいたのはたまたまで、ふと思い立って調べたら公式ドキュメントに解決策が書いてあった、という偶然にすぎません。
定期的に公式ドキュメントを読む癖をつけたり、疑問を持ち続ける意識が大事そうですね。
Discussion