ペルソナ: キャッシングをシステム設計の決定として扱う Go エンジニアです。測定されたアクセス パターンに基づいてエビクション アルゴリズムを選択し、ワーキング セット データからキャッシュ サイズを決定し、常に有効期限、ローダー障害、モニタリングを計画します。

Go での samber/hot を使用したインメモリキャッシング

Go 1.22 以上対応のジェネリック、型安全なインメモリキャッシング ライブラリで、9 つのエビクション アルゴリズム、TTL、singleflight 重複排除を備えたローダー チェーン、シャーディング、stale-while-revalidate、Prometheus メトリクスを備えています。

公式リソース:

• pkg.go.dev/github.com/samber/hot
• github.com/samber/hot

このスキルは網羅的ではありません。詳細については、ライブラリのドキュメントとコード例を参照してください。Context7 はディスカバリ プラットフォームとして役立ちます。

go get -u github.com/samber/hot

アルゴリズムの選択

アクセス パターンに基づいて選択します — 間違ったアルゴリズムはメモリを無駄にするか、ヒット率を低下させます。

アルゴリズム	定数	最適な用途	避けるべき場合
W-TinyLFU	hot.WTinyLFU	汎用、混合ワークロード (デフォルト)	デバッグの簡潔性が必要な場合
LRU	hot.LRU	最近性重視 (セッション、最近のクエリ)	頻度が重要な場合 (スキャン汚染でホット アイテムがエビクトされる)
LFU	hot.LFU	頻度重視 (人気商品、DNS)	アクセス パターンが変動する場合 (古い人気アイテムがエビクトされない)
TinyLFU	hot.TinyLFU	読み込み集約的で頻度バイアス有り	書き込み集約的 (アドミッション フィルター オーバーヘッド)
S3FIFO	hot.S3FIFO	高スループット、スキャン耐性	小さいキャッシュ (<1000 アイテム)
ARC	hot.ARC	自動チューニング、未知のパターン	メモリ制約 (2 倍の追跡オーバーヘッド)
TwoQueue	hot.TwoQueue	ホット/コールド分割を伴う混合	チューニング複雑性が許容できない場合
SIEVE	hot.SIEVE	シンプルなスキャン耐性 LRU 代替	極端に歪んだアクセス パターン
FIFO	hot.FIFO	シンプル、予測可能なエビクション順序	ヒット率が重要な場合 (頻度/最近性の認識なし)

決定のショートカット: hot.WTinyLFU から始めます。プロファイリングでミス率が SLO に対して高すぎることが示された場合のみ切り替えます。

詳細なアルゴリズム比較、ベンチマーク、決定ツリーについては、アルゴリズム ガイドを参照してください。

コア使用方法

TTL を使用した基本的なキャッシュ

import "github.com/samber/hot"

cache := hot.NewHotCache[string, *User](hot.WTinyLFU, 10_000).
    WithTTL(5 * time.Minute).
    WithJanitor().
    Build()
defer cache.StopJanitor()

cache.Set("user:123", user)
cache.SetWithTTL("session:abc", session, 30*time.Minute)

value, found, err := cache.Get("user:123")

ローダー パターン (読み取りスルー)

ローダーは singleflight 重複排除を使用して欠落キーを自動的に取得します — 同じ欠落キーに対する複数の Get() 呼び出しは、1 つのローダー呼び出しを共有します:

cache := hot.NewHotCache[int, *User](hot.WTinyLFU, 10_000).
    WithTTL(5 * time.Minute).
    WithLoaders(func(ids []int) (map[int]*User, error) {
        return db.GetUsersByIDs(ctx, ids) // バッチ クエリ
    }).
    WithJanitor().
    Build()
defer cache.StopJanitor()

user, found, err := cache.Get(123) // ミス時にローダーをトリガー

キャパシティ サイジング

キャッシュ キャパシティを設定する前に、メモリ予算に適合するアイテム数を推定します:

1. 単一アイテム サイズを推定 — struct のサイズを推定し、ヒープ割り当てフィールド (スライス、map、文字列) のサイズを追加します。キー サイズを含めます。エントリあたりの約 100 バイトの大まかなオーバーヘッドは、内部ブックキーピング (ポインタ、有効期限タイムスタンプ、アルゴリズム メタデータ) をカバーします。
2. 開発者に確認 本番環境でこのキャッシュに割き当てるメモリ量 (例: 256 MB、1 GB)。これはサービスの合計メモリとプロセスを共有するその他の内容に依存します。
3. キャパシティを計算 — capacity = memoryBudget / estimatedItemSize。余裕を残すために切り下げます。

例: *User struct ~500 bytes + 文字列キー ~50 bytes + オーバーヘッド ~100 bytes = ~650 bytes/エントリ
    256 MB 予算 → 256_000_000 / 650 ≈ 393,000 アイテム

アイテム サイズが不明な場合、開発者に N 個のアイテムを割り当て、runtime.ReadMemStats をチェックする単体テストでそれを測定するよう依頼します。キャパシティを測定せずに推測すると、OOM またはメモリ浪費につながります。

よくある間違い

1. WithJanitor() を忘れる — これなしでは、期限切れのエントリはアルゴリズムがエビクトするまでメモリに留まります。常にビルダーで .WithJanitor() をチェーンし、defer cache.StopJanitor() を実行します。
2. 欠落キャッシュ設定なしで SetMissing() を呼び出す — 実行時にパニックします。最初にビルダーで WithMissingCache(algorithm, capacity) または WithMissingSharedCache() を有効にします。
3. WithoutLocking() + WithJanitor() — 相互に排他的で、パニックします。WithoutLocking() はバックグラウンド クリーンアップなしのシングル ゴルーチン アクセスにのみ安全です。
4. オーバーサイズ キャッシュ — すべてを保持するキャッシュはオーバーヘッド付きのマップです。ワーキング セット (通常は全データの 10-20%) にサイズを調整します。ヒット率をモニタリングして検証します。
5. ローダー エラーを無視する — ローダー障害時に Get() は (zero, false, err) を返します。常に err をチェックし、found だけではなく。

ベスト プラクティス

1. 常に TTL を設定します — 無制限のキャッシュは更新シグナルがないため、期限切れデータを無期限に提供します
2. WithJitter(lambda, upperBound) を使用して有効期限を分散します — ジッターなしでは、一緒に作成されたアイテムが一緒に期限切れになり、ローダーでの雷鳴群が発生します
3. WithPrometheusMetrics(cacheName) でモニタリングします — ヒット率が 80% 未満は通常、キャッシュがアンダーサイズ化されているか、アルゴリズムがワークロードに不適切であることを意味します
4. ミュータブル値に対して WithCopyOnRead(fn) / WithCopyOnWrite(fn) を使用します — コピーなしでは、呼び出し元がキャッシュされたオブジェクトをミュートし、共有状態を破損します

高度なパターン (再検証、シャーディング、欠落キャッシュ、モニタリング セットアップ) については、本番パターンを参照してください。

完全な API サーフェスについては、API リファレンスを参照してください。

samber/hot でバグまたは予期しない動作が発生した場合は、https://github.com/samber/hot/issues で issue をオープンしてください。

クロスリファレンス

• → 一般的なキャッシング戦略および インメモリキャッシュ対 Redis 対 CDN をいつ使用するかについては、samber/cc-skills-golang@golang-performance スキルを参照してください
• → Prometheus メトリクス統合とモニタリングについては、samber/cc-skills-golang@golang-observability スキルを参照してください
• → キャッシュ ローダーとペアになるデータベース クエリ パターンについては、samber/cc-skills-golang@golang-database スキルを参照してください
• → CLI 経由で Prometheus キャッシュ メトリクスをクエリするには、samber/cc-skills@promql-cli スキルを参照してください