spring-boot-cache

Spring Boot キャッシュ抽象化

概要

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

使用する場面

• サービスメソッドに @Cacheable、@CachePut、または @CacheEvict を追加する場合。
• TTL と容量ポリシーを指定して Caffeine、Redis、または Ehcache を設定する場合。
• 古いデータのエビクション戦略を実装する場合。
• キャッシュミスや無効化の問題を診断する場合。
• Actuator または Micrometer 経由でヒット／ミスのメトリクスを公開する場合。

手順

1. 依存関係を追加する — spring-boot-starter-cache とプロバイダーを追加します。

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

2. キャッシュを有効にする — @Configuration クラスに @EnableCaching を付与し、 CacheManager Bean を定義します。

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) { ... }
}

First call → cache miss, repository invoked
Second call → cache hit, repository skipped

例 2：SpEL を使用した条件付きキャッシュ

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

// Only expensive products are cached

例 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. @EnableCaching が @Configuration クラスに指定されていることを確認します。
2. メソッドが public で、クラス外部から呼び出されていることを確認します（Spring はプロキシを使用するため、自己呼び出しではキャッシュが迂回されます）。
3. SpEL キー式が正しく評価されることを確認します。
4. キャッシュマネージャー Bean が cacheManager として登録されているか、cacheManager = "myCacheManager" で明示的に参照されていることを確認します。

参考資料

• references/spring-framework-cache-docs.md： Spring Framework Reference Guide から厳選した抜粋です。
• references/spring-cache-doc-snippet.md： Spring ドキュメントの概要です。
• references/cache-core-reference.md： アノテーションのパラメーター、依存関係の一覧、プロパティのカタログです。
• references/cache-examples.md： テストを含むエンドツーエンドの例です。

ベストプラクティス

• キャッシュエントリーにはコンストラクターインジェクションと不変 DTO を優先します。
• エビクションを簡素化するため、集約ごとにキャッシュ名（users、orders）を分けます。
• キャッシュのヒット／ミスは debug レベルでのみログに記録し、Micrometer 経由でメトリクスを送信します。
• データの古さに対する許容度に基づいて TTL を調整し、その理由をコードに記載します。
• PII や認証情報を保存するキャッシュは暗号化で保護するか、キャッシュを避けます。
• ダーティーリードを防ぐため、キャッシュのエビクションをトランザクション境界に合わせます。

制約と警告

• オープンな永続化コンテキストに依存する変更可能なエンティティはキャッシュしないでください。
• 同じメソッドに Spring のキャッシュアノテーションと JCache のアノテーションを併用しないでください。
• サービスインスタンス間でキャッシュする場合は、シリアライズの互換性を検証してください。
• インメモリストアでの OOM を防ぐため、メモリ使用量を監視してください。
• Caffeine と Redis のマルチレベルキャッシュでは、パブリッシュ／サブスクライブによる無効化チャネルが必要です。

関連スキル

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