Spring Boot キャッシュ抽象化

概要

Spring Boot 3.5+ アプリケーションにおいて、キャッシュ抽象化の有効化、プロバイダ設定（Caffeine、Redis、Ehcache）、サービスメソッドへのアノテーション付与、動作検証を行う 6 ステップのワークフロー。読み取り時は @Cacheable、書き込み時は @CachePut、削除時は @CacheEvict を適用します。TTL/削除ポリシーを設定し、Actuator 経由でメトリクスを公開します。

使用時期

• サービスメソッドに @Cacheable、@CachePut、または @CacheEvict を追加する場合
• Caffeine、Redis、または Ehcache を TTL および容量ポリシー付きで設定する場合
• 古いデータのための削除戦略を実装する場合
• キャッシュミスまたは無効化の問題を診断する場合
• Actuator または Micrometer 経由でヒット/ミスメトリクスを公開する場合

手順

1. 依存関係を追加 — spring-boot-starter-cache とプロバイダを追加：

   • Caffeine: caffeine スターター
   • Redis: spring-boot-starter-data-redis
   • Ehcache: ehcache スターター

2. キャッシング有効化 — @Configuration クラスに @EnableCaching を付与し、CacheManager ビーンを定義。

3. メソッドにアノテーション付与 — 読み取りは @Cacheable、書き込みは @CachePut、削除は @CacheEvict。

4. TTL/削除を設定 — spring.cache.caffeine.spec、spring.cache.redis.time-to-live、または spring.cache.ehcache.config を設定。

5. キーを成形 — key 属性内で SpEL を使用；condition/unless で選別的キャッシングを保護。

6. セットアップ検証 — 統合テストを実行して 2 回目の呼び出しでキャッシュヒットを確認；GET /actuator/caches でキャッシュマネージャ登録を確認；GET /actuator/metrics/cache.gets でヒット/ミスレシオをクエリ。

例

例 1: 基本的な @Cacheable 使用法

@Service
@CacheConfig(cacheNames = "users")
class UserService {

    @Cacheable(key = "#id", unless = "#result == null")
    User findUser(Long id) { ... }
}

1 回目の呼び出し → キャッシュミス、リポジトリが実行される
2 回目の呼び出し → キャッシュヒット、リポジトリがスキップされる

例 2: SpEL を使った条件付きキャッシング

@Cacheable(value = "products", key = "#id", condition = "#price > 100")
public Product getProduct(Long id, BigDecimal price) { ... }

// 高価な商品のみキャッシュされます

例 3: キャッシュ削除

@CacheEvict(value = "users", key = "#id")
public void deleteUser(Long id) { ... }

段階的なシナリオ（基本的な製品キャッシュ、多層削除、Redis 統合）については、references/cache-examples.md を参照してください。

高度なオプション

• JSR-107 相互運用性を重視するプロバイダに対して JCache アノテーション（@CacheResult、@CacheRemove）を使用；同じメソッドで Spring アノテーションと混在させない。
• リアクティブな戻り値型（Mono、Flux）または CompletableFuture 値をキャッシュ。
• REST 経由でキャッシュされたレスポンスを公開する場合、HTTP CacheControl ヘッダを適用。
• 時間限定のキャッシュに対して @Scheduled で定期削除をスケジュール。
• プログラマティックな cacheManager.getCache(name) のために CacheManagementService を作成。

トラブルシューティング

@Cacheable 追加後もキャッシュミスが続く場合：

1. @Configuration クラスに @EnableCaching があることを確認。
2. メソッドがパブリックであり、クラス外から呼び出されていることを確認（Spring はプロキシを使用；自己呼び出しはキャッシュをバイパス）。
3. SpEL キー式が正しく解決されることを検証。
4. キャッシュマネージャビーンが cacheManager として登録されているか、cacheManager = "myCacheManager" で明示的に参照されていることを確認。

リファレンス

• references/spring-framework-cache-docs.md: Spring Framework リファレンスガイドからの厳選抜粋。
• references/spring-cache-doc-snippet.md: Spring ドキュメンテーションからのナラティブ概要。
• references/cache-core-reference.md: アノテーションパラメータ、依存関係マトリックス、プロパティカタログ。
• references/cache-examples.md: テスト付きのエンドツーエンド例。

ベストプラクティス

• コンストラクタインジェクションと不変 DTO をキャッシュエントリに優先。
• キャッシュ名を集約ごと（users、orders）に分離して削除を簡素化。
• キャッシュヒット/ミスはデバッグレベルのみでログ出力；メトリクスを Micrometer 経由でプッシュ。
• TTL をデータ陳腐化許容度に基づいて調整；コード内で根拠を記述。
• PII または認証情報を保存するキャッシュは暗号化で保護するか、キャッシングを回避。
• キャッシュ削除をトランザクション境界と整合させてダーティリード防止。

制約と警告

• 開かれた永続化コンテキストに依存する可変エンティティのキャッシングを回避。
• 同じメソッドで Spring キャッシュアノテーションと JCache アノテーションを混在させない。
• サービスインスタンス間のキャッシング時にシリアライゼーション互換性を検証。
• インメモリストアの OOM 防止のためにメモリフットプリントを監視。
• Caffeine + Redis 多層キャッシュはパブリッシュ/サブスクライブ無効化チャネルが必要。

関連スキル

• ../spring-boot-rest-api-standards
• ../spring-boot-test-patterns
• ../unit-test-caching