nestjs-features-performance

NestJS の機能、スケーリング、パフォーマンス

懸念事項に合ったライフサイクルを持つ NestJS のプリミティブを選択してください。システムを最適化または分散する前に、制約となっているリソースを診断してください。

実行前の競合確認

ファイルを編集したり、状態を変更するコマンドを実行したりする前に、有効な指示を照合してください。読み取り専用の確認は続行できます。

前提条件

リポジトリの指示、インストール済みのバージョン、ブートストラップ／トランスポートおよびデプロイ設定、テスト、運用上の契約、ベースライン測定値を確認してください。ユーザーの変更を保持し、最適化やデリバリーのアクションを選択する前に、ライフサイクル、根拠、環境、承認を確認してください。ほかの有効なスキルは、その判断が重なる場合にのみ読み取ってください。

主な担当範囲

このスキルは、Nest のライフサイクル、API／エラー／セキュリティの契約、テストレイヤー、パフォーマンスの根拠、信頼性、可観測性、ランタイムのデリバリーを担当します。導入済みで関連性がある場合は、以下と連携してください。

• nestjs-architecture-principles：モジュール、依存関係、データ、トランザクションの境界。
• nestjs-oop-design-patterns：オブジェクトの責務、不変条件、パターン。
• nestjs-professional-software-engineering：実装と検証。
• nestjs-code-audit：読み取り専用の品質に関する根拠と、重複を排除した報告。
• nestjs-feature-audit：ブランチ固有のロードマップのゲートと機能に関する報告。
• nestjs-git-commit-pr-message：承認された Git の公開と CI のフォローアップ。

これらは判断の境界であり、必須の依存関係ではありません。作業を別のワークフローに引き継ぐ際も、ドメインの担当範囲は維持してください。

競合の確認

互換性のない編集や契約、コマンドの順序や副作用、担当者の競合、バージョン、根拠、承認、リポジトリに関する未充足の前提条件がないか確認してください。明示的なユーザーの意図、リポジトリの契約、検証済みのランタイム制約の順に優先し、最も範囲の狭い担当者に判断を委ねて解決してください。各判断の主担当は一人に定め、矛盾する助言を満たすための並行設計を作成しないでください。重大な競合が残る場合は、変更を加える前に停止し、不足している最小限の判断をユーザーに確認してください。監査は読み取り専用とし、明示的な修正の承認は、実装フェーズを別に設けて適用してください。

ランタイムのベースラインを確認する

動作を推奨または変更する前に、以下を行ってください。

1. インストール済みの NestJS／Node のバージョン、ブートストラップコード、アダプター、モジュール、トランスポート、永続化クライアント、キャッシュ／キューの設定、デプロイマニフェストを確認してください。
2. 代表的なリクエスト、メッセージ、またはジョブが、ガード、パイプ、インターセプター、ハンドラー、プロバイダー、永続化処理、外部呼び出しをどのように通過するか追跡してください。
3. 現在の症状と根拠を特定してください。レイテンシのパーセンタイル、スループット、エラー率、イベントループの遅延、CPU、ヒープ／GC、データベースの処理時間、接続プールの飽和、外部サービスのレイテンシ、またはキューの滞留などです。
4. 目標とワークロードを定義してください。「高速化する」は、測定可能な受け入れ基準ではありません。
5. フレームワークとライブラリの API を、公式ドキュメントおよびリポジトリのバージョンに照らして確認してください。

コードの見た目だけでパフォーマンスの向上を主張してはいけません。代表的なワークロードのもとで、変更前後を測定してください。

動作を適切な NestJS 機能に配置する

references/feature-selection.mdを使用してください。

一般的な HTTP ライフサイクル：

request
  -> middleware
  -> guards
  -> interceptors (before)
  -> pipes
  -> controller/resolver + providers
  -> interceptors (after, reverse order)
  -> exception filters for uncaught errors
  -> response

デフォルト：

• ミドルウェア： 生のプロトコルの前処理と相関コンテキスト。
• ガード： 実行コンテキストに対する認証／認可の判定。
• パイプ： 入力の検証と変換。
• インターセプター： ハンドラー実行前後の動作、レスポンスのマッピング、タイミング計測、トレース、または互換性のあるキャッシュ。
• 例外フィルター： プロトコル固有の最終的なエラーマッピング。
• デコレーター： 宣言的なメタデータや確立済みコンテキストの抽出。隠れた I/O は行いません。
• プロバイダー／アプリケーション操作： ビジネス動作とオーケストレーション。
• キュー／ワーカー： 永続化が必要な処理、遅延処理、バースト性のある処理、またはリソースを大量に消費する処理。
• イベント： 完了した事実と、それに対する独立した反応。インプロセス配信と永続的な配信のどちらを使うかを明示的に選択します。

API とトランスポートに関するガイダンスは、references/api-runtime.mdを読み込んでください。対象となるリスクに応じて、エラー処理、セキュリティ、テスト、API 設計、デプロイの各ルールブックを使用してください。

リソース別にパフォーマンスを診断する

references/performance-diagnosis.mdを使用してください。

対策を選ぶ前に、主な制約を分類してください。

制約	根拠	一般的な初期対応
イベントループのブロッキング	イベントループの遅延／使用率が高い、CPU コールバックのホットスポット	同期処理をなくす。入力を制限する。CPU 処理をオフロードする
データベース	クエリの遅さ、N+1、コネクションプールの待機、ロック、スキャン行数の多さ	クエリの形状／インデックスを見直す。結果を制限する。トランザクションを短縮する
外部 I/O	依存先のスパンがレイテンシの大部分を占める	デッドライン、接続の再利用、制限付きの再試行、同時実行数の制御
メモリ／GC	ヒープの増加、GC の一時停止、OOM／再起動	メモリの保持をなくす。データをストリーミング／制限する。割り当てをプロファイリングする
シリアライズ／ログ記録	レスポンスに応じて CPU 使用量またはペイロードサイズが増加する	フィールドを選択する。ページネーション／ストリーミングを行う。ホットパスのログ記録を減らす
キャパシティ	インスタンスごとのパフォーマンスは安定しているが、レプリカが飽和している	ステートレスなプロセスと安全な依存先を使って水平スケールする

ボトルネックを示す根拠が特定され、互換性への影響が把握できるまでは、Fastify への切り替え、Redis の追加、ワーカースレッドの導入、サービスの分割を行わないでください。

スケーリングのルール

references/scaling-reliability.mdを使用してください。

1. Web レプリカをステートレスに保ちます。共有セッション、ロック、ジョブの状態、調整処理は、適切な外部システムに移します。
2. デフォルトではシングルトンプロバイダーを優先します。リクエストスコープはインジェクションチェーン全体に伝播し、リクエストごとの割り当てを増やすため、実際にライフタイム要件がある場合にのみ使用します。
3. すべてのコレクション、ページ、バッチ、キューの同時実行数、再試行回数、ペイロード、アップロード、タイムアウトに上限を設けます。
4. ジョブとメッセージコンシューマーを冪等にします。重複配信と部分的な失敗を想定してください。
5. 一時的な障害にはジッターを加えた指数バックオフを使用します。検証エラー、認可エラー、不変条件のエラーを決して無条件に再試行しないでください。
6. バックプレッシャーを追加します。メモリとレイテンシが際限なく増加するのを防ぐため、負荷を拒否、削減、一時停止、またはキューイングします。
7. キャパシティの特性が異なる場合は、ユーザー向けプロセスと、CPU 負荷の高い処理や時間のかかるバックグラウンド処理を分離します。
8. キャッシュは派生状態として扱います。キーの名前空間、TTL、無効化、スタンピード時の動作、安全なフォールバックを定義します。
9. シャットダウン前にドレインします。作業の受け付けを停止し、準備状態を解除し、処理中の作業を完了するか安全に再キューイングしてから、リソースを閉じます。
10. 平均 CPU 使用率だけでなく、サービスレベル目標と飽和の兆候に基づいてスケールします。

実装ワークフロー

機能の追加または変更

1. 適切なライフサイクル段階と、既存のリポジトリ規約を確認します。
2. 契約、スコープ、障害時の動作を定義します。
3. 必要最小限のプロバイダー／コンポーネントを実装し、最も狭い有効なレベルでバインドします。
4. 単独での動作と、境界での順序／配線をテストします。
5. 公開契約または運用契約が変わる場合は、OpenAPI／スキーマ、設定の検証、テレメトリー、ドキュメントを更新します。

エラー処理の設計または修正

1. すべてのエントリーポイント、現在の公開エラー契約、フィルターのバインド、アダプター／ベンダーのエラー、クライアント依存関係、部分的な副作用を洗い出します。
2. メッセージを解析せずに、予期されるビジネス、検証、認証／アクセス、競合、一時的、恒久的、キャンセル／タイムアウト、不明の各障害に分類します。
3. アプリケーションが所有する型／結果を定義し、安全な原因を保持しながら、インフラストラクチャアダプターでベンダー障害を変換します。
4. 各 HTTP、GraphQL、RPC/gRPC、WebSocket、ワーカーの境界を個別にマッピングし、機密情報を含まない不明時のフォールバックを1つに統一します。
5. 復旧ロジックを追加する前に、期限、キャンセル、再試行／冪等性、確認応答、トランザクション、不明な結果の動作を定義します。
6. 適切な最小範囲の NestJS フィルター／ハンドラーをバインドし、該当する場合はハイブリッド、ゲートウェイ、アダプター、ストリーム、プロセス致命的エラーの各経路を検証します。
7. 安定した契約、副作用、可観測性の所有者、機密データが含まれないこと、再起動／復旧時の動作をテストします。

遅い処理経路の最適化

1. 制御されたベンチマークまたはトレースで再現します。
2. ベースラインのパーセンタイル、スループット、エラー、リソースの飽和状況を記録します。
3. 支配的な処理経路をプロファイリングします。
4. 制限要因を1つ変更します。
5. 同じワークロードを再実行して比較します。
6. 正常系と障害系のテストを実行します。誤った動作を速めても、リグレッションです。
7. 容量上限とロールバックの判断基準を記録します。

スケールの計画

1. ワークロードの形状、SLO、一貫性、耐久性、コストの制約を定義します。
2. インスタンスごとの容量を見積もり、共有依存先の上限を特定します。
3. 実際のリソース境界に基づいて、垂直方向のチューニング、レプリカ、ワーカー、キュー、パーティション、サービスの切り出しを選択します。
4. 容量を増やす前に、過負荷時および部分障害時の動作を設計します。
5. リスクに応じた負荷、長時間稼働、急増、障害の各テストで計画を実証します。

本番環境のビルド、デプロイ、または診断

1. ソースのリビジョン、不変のアーティファクト／イメージダイジェスト、対象環境、担当者を特定します。
2. リポジトリで意図された状態、ビルド済みアーティファクト、望ましいデプロイ状態、実行中の状態を比較します。設定ファイルだけから実稼働中の状態を推測してはいけません。
3. マイグレーション／設定の互換性、ロールアウト戦略、成功の判断基準、中止のしきい値、ロールバックまたは前進修復の経路を定義します。
4. リポジトリのデリバリー手段を通じて、承認された最小限の変更を適用します。
5. 実稼働中のリビジョン、レディネス、代表的なトラフィック／処理、エラー、レイテンシ、飽和状況、キュー／依存先、ドレインの動作を検証します。
6. リリースまたはインシデントの証跡を記録し、緊急対応による差分があれば宣言された状態に反映し直します。

本番環境への移行ゲート

機能を本番環境対応済みと判断する前に、references/production-readiness.md を使用します。最低限、設定、セキュリティ、契約、リソース上限、可観測性、ヘルス／レディネス、シャットダウン、復旧を確認します。

参照先の案内

エンハンサーの適用範囲、ライフタイム、責務、テスト済みの実行パスについては、enhancer-composition.md を参照してください。

タスク	参照先
ミドルウェア、ガード、パイプ、インターセプター、フィルター、デコレーター、イベント、キュー、スケジューラーを選ぶ	feature-selection.md
HTTP／GraphQL／WebSocket／SSE／マイクロサービスのコントラクトとテストを構築する	api-runtime.md
障害を分類する、安定したエラーにマッピングする、またはフィルターとリトライを設計する	error-handling.md
型付きエラー／結果、公開コード、バリデーションの形式、Problem Details、または HTTP のセマンティクスを定義する	error-taxonomy-contracts.md
HTTP、GraphQL、RPC／gRPC、WebSocket、ワーカー、またはハイブリッドアプリ全体でフィルターを実装する	exception-filters-transports.md
デッドライン、キャンセル、安全なリトライ、致命的なプロセス障害への対応、テレメトリー、または障害テストを設計する	failure-resilience-testing.md
認証、認可、バリデーション、シークレット、出力、または不正利用対策を確認する	security.md
ユニット、モジュール、統合、コントラクト、E2E、または信頼性テストを選ぶ	testing.md
DTO、レスポンス、エラー、ページネーション、冪等性、またはバージョニングを設計する	api-design.md
レイテンシー、CPU、イベントループ、データベース、メモリー、キャッシュ、または Fastify の選択を診断する	performance-diagnosis.md
レプリカ、ワーカー、キュー、リトライ、冪等性、バックプレッシャー、または分散協調を追加する	scaling-reliability.md
ビルド、設定、移行、ヘルスチェック、オブザーバビリティ、ロールアウト、またはシャットダウン制御を設計する	devops-deployment.md
CI/CD、コンテナーイメージ、プロベナンス、昇格、またはアーティファクトのロールバックを構築する	ci-cd-containers.md
Kubernetes のワークロード、プローブ、リソース、HPA、ロールアウト、または終了処理を設定または診断する	kubernetes-operations.md
SLO、ログ／メトリクス／トレース、アラート、ダッシュボード、インシデント、バックアップ、または復旧を定義する	observability-sre.md
運用準備状況とロールアウトの安全性を確認する	production-readiness.md

期待する回答

パフォーマンス／スケーリングに関する作業では、以下を報告してください。

• 症状と目標
• ベースラインの根拠
• 主な制約
• 推奨する変更とトレードオフ
• 正確性／障害のリスク
• 変更前後の検証計画

根拠が不足している場合は、アーキテクチャを変更する前に必要となる、最小限の測定を提案してください。

エラー処理に関する作業では、以下を報告してください。

• 障害モデル： 分類、安定したコード／型、想定される動作と未知の動作。
• 境界でのマッピング： 影響を受けるすべてのエントリーポイントにおける、アプリケーションからトランスポートへのマッピング。
• 影響とレジリエンス： 確定済み／発生し得る副作用、期限、キャンセル、再試行／冪等性、復旧の担当。
• 情報開示： 公開するフィールド、秘匿化、ロギングの担当、機密データの制御。
• フレームワークの配線： フィルター／ハンドラーの適用範囲、実行コンテキスト、アダプター／ハイブリッド構成の網羅性、プロセスの致命的障害時の動作。
• 検証： コントラクト、アダプター、タイムアウト、重複、部分的な副作用、プライバシー、再起動のテスト。

DevOps に関する作業では、以下を報告してください。

• リリースの識別情報： ソースリビジョン、アーティファクト／ダイジェスト、環境、担当者。
• 状態の比較： リポジトリの意図、デプロイのあるべき状態、実行時に観測された状態。
• 安全性： 移行／設定の互換性、セキュリティゲート、障害のリスク。
• ロールアウト： 戦略、成功／中止のシグナル、観測期間、キャパシティへの影響。
• 検証： 稼働中のリビジョン、健全性、代表的な処理、テレメトリー、ドレイン。
• 復旧： ロールバックまたは前進修復の手順と、その実施条件。