mcpField
R
redis-caching

redis-caching

github.com/shipshitdev開発3864 回インストール2 日前に更新
リポジトリ

redis-caching について

redis-caching は、Redis を第2のデータベースではなく本番環境の補助レイヤーとして設計する開発スキルです。キャッシュ、レート制限、セッション、無効化、イベント配信を扱い、Node.js、NestJS、サーバーレス、エッジランタイム向けの指針を示します。

主な機能

  1. 01Cache-aside と write-through パターン
  2. 02TTL とキー無効化の設計
  3. 03ホットキーのスタンピード対策
  4. 04スライディングウィンドウ方式の制限
  5. 05セッション保存とイベント配信

活用シーン

  1. 01Prisma の読み取りに Redis キャッシュを追加
  2. 02高コストなルートをレート制限で保護
  3. 03短期セッションや認証状態を保存
  4. 04イベントに Pub/Sub と Streams を選択

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/shipshitdev/skills --skill redis-caching

インストール後、Claude Code で/redis-cachingを入力して読み込まれたか確認します。

同梱ファイルplugin.jsonreferences/examples.md

詳細

Redis キャッシュ

Redis は 2 つ目のデータベースではなく、本番環境を支えるレイヤーとして実装します。

使用する場面

  • Prisma や API の読み取りに、キャッシュ・アサイドまたはライトスルーキャッシュを追加する場合。
  • レート制限で高コストなルートを保護する場合。
  • 短期間のセッション、検証状態、ロック、カウンターを保存する場合。
  • Pub/Sub やストリームを使ったイベントのファンアウトを追加する場合。
  • Redis のキー設計、TTL、無効化、接続処理を見直す場合。

BullMQ のジョブキューアーキテクチャには、ここでキューのパターンを重複させず、nestjs-queue-architect を使用してください。

最初に決めること

  1. ランタイムを選択します。
    • 長時間稼働する Node.js または NestJS プロセス：ioredis を使用します。
    • サーバーレスまたはエッジランタイム：Upstash Redis SDK または REST API を優先します。
    • バックグラウンドジョブ：nestjs-queue-architect の BullMQ に関するガイダンスを使用します。
  2. コードを書く前にキャッシュの契約を定義します。
    • 信頼できる唯一の情報源：Prisma／データベース、上流 API、計算結果、またはセッションの管理元。
    • 鮮度：固定 TTL、stale-while-revalidate、明示的な無効化、またはライトスルー。
    • 障害時の動作：キャッシュ読み取りはフェイルオープン、認証／セッション／レート制限の書き込みはフェイルクローズにします。
  3. キー設計と無効化を同時に考えます。
    • すべてのキーに名前空間を付けます：app:env:entity:id:variant。
    • キーは安定していて、確認しやすいものにします。
    • キャッシュ、ロック、セッション、レート制限のすべてのキーに TTL を設定します。

インストール

bun add ioredis

# Optional serverless Redis
bun add @upstash/redis @upstash/ratelimit

プロセスごとに Redis クライアントを 1 つ使用します（ホットリロードによる重複を防ぐ、モジュールレベルのシングルトンを使用します）。リクエストごとに新しい TCP クライアントを作成しないでください。error、connect、reconnecting イベントをアプリのロガーまたは APM に接続します。接続 URL に含まれる認証情報をログに記録しないでください。

完全なセットアップについては、references/examples.md（§ Redis Client Singleton）を参照してください。

Prisma を使ったキャッシュ・アサイド

短時間の古さが許容される読み取りには、キャッシュ・アサイドを使用します。キャッシュを確認し、ミスした場合はローダーを呼び出してから、ジッター付き TTL（baseTtl + random(0, jitter)）で書き戻します。これにより、頻繁に使われるキーがすべて同時に期限切れになるのを防げます。

getCached ヘルパーと Prisma を使った使用例については、references/examples.md（§ Cache-Aside With Prisma）を参照してください。

スタンピード対策

短い SET key val EX 10 NX ロックで頻繁に使われるキーを保護します。保持者（ランダムなトークンで照合されます）だけがロックを解放できます。ほかの処理は短時間待ってキャッシュを再確認してから、キャッシュを使わずに直接読み込みます。

ロックの取得と解放の完全な実装については、references/examples.md（§ Stampede Protection）を参照してください。

無効化

既知のキーには、直接の無効化を優先します。1 回の変更で多数のキーに影響する場合はタグセット（タグごとに Redis セットを作成し、そのタグで書き込まれたキーを対応付ける）を使用します。パイプラインで書き込み、タグのキーセットを読み取って UNLINK することで無効化します。緊急のパターン削除には、KEYS ではなく SCAN を使用します。頻繁に使われるリクエストパスでパターン無効化を行わないでください。

cacheSetWithTags／invalidateTag の実装については、references/examples.md（§ Tag-Based Invalidation）を参照してください。

レート制限

正確性が重要なスライディングウィンドウ制限には、ソート済みセットを使用します。期限切れのエントリーを削除し、現在のリクエストを追加し、メンバー数を数えて、キーの有効期限を設定します。これらすべてを 1 つの MULTI 内で実行します。公開トラフィックには、次のレスポンスヘッダーを設定します：X-RateLimit-Limit、X-RateLimit-Remaining、Retry-After。

slidingWindowRateLimit の完全な実装については、references/examples.md（§ Sliding-Window Rate Limiting）を参照してください。

セッションと検証状態

  • 生の JWT や長期間有効なシークレットではなく、推測困難なセッション ID またはトークンのハッシュを保存します。
  • すべてのセッションキーに TTL を設定します。
  • 権限の変更後はセッションを再生成します。
  • ログアウト、アカウント削除、パスワードリセット時にセッションを削除します。
  • ログイン、ログアウト、MFA、パスワードリセットのフローでは、Redis への書き込み失敗を認証失敗として扱います。

createSession の例については、references/examples.md（§ Session Storage）を参照してください。

Pub/Sub とストリーム

  • メッセージの取りこぼしが許容される一時的なファンアウトには、pub/sub を使用します。
  • コンシューマーが再生、バックプレッシャー、または永続的な配信を必要とする場合は、ストリームを使用します。
  • ペイロードは小さく保ち、大きなオブジェクトは別の場所に保存して、ID を配信します。
  • コンシューマーの可観測性を確保します。ラグ、デッドレター、再試行、ハンドラーエラーを確認できるようにします。

本番環境チェックリスト

  • すべてのキャッシュ、ロック、セッション、レート制限のキーに TTL が設定されています。
  • 可能な場合、キャッシュの読み取りはフェイルオープンにし、認証とレート制限の書き込みはフェイルクローズにします。
  • ホットキーには TTL ジッターまたはスタンピード対策を適用します。
  • リクエストパスで KEYS、無制限の SMEMBERS、または大規模な HGETALL を使用しません。
  • 無効化は書き込みパスとあわせてテストされています。
  • Redis のメトリクスで、レイテンシー、ヒット率、メモリ、エビクション、ブロックされたクライアント、再接続を確認できます。
  • ローカルテストで、キャッシュヒット、キャッシュミス、Redis の停止、無効化、レート制限超過を確認します。

コメント

Markdown 対応