メモリ上のキャッシュ
何も設定しなくても、スターターは cacheManager の Bean、InMemoryCacheManager (Spring の ConcurrentMapCacheManager) を作ります。各キャッシュは InMemoryCache で、動作中のアプリのメモリ上のマップです。アノテーションが最初にそれを指定したときに作られます。有効期間とサイズの上限は、全体またはキャッシュごとに、spring.cache.* プロパティから来ます。
使う理由
ほとんどのキャッシュは、再起動後に再計算するのが安価な、遅い呼び出しの結果を保持します。メモリはそれらにとって最も速い場所で、何の準備も要りません。Spring の simple タイプには有効期限もサイズの上限もなく、そのためには Caffeine を使うよう案内されます。ここではメモリ上のキャッシュが両方を持つため、長時間動くサーバーが際限なく大きくなることはありません。
例
# lib/resources/application.properties
spring.cache.simple.time-to-live=10m
spring.cache.simple.max-size=1000
spring.cache.simple.caches.prices.time-to-live=30s # 価格はより早く古くなる
spring.cache.simple.caches[books.byIsbn].max-size=200 # ドットを含むキャッシュ名
// 管理者の操作: キャッシュされたすべての本を捨てる。
@Component()
class CacheAdmin {
CacheAdmin(this.caches);
final CacheManager caches;
void clearBooks() => caches.getCache('books')?.clear();
}
メモリ上のキャッシュがすること
- 各キャッシュは、
spring.cache.cache-namesが集合を固定していない限り、アノテーションが最初にそれを指定したとき ('books') に作られます。 - エントリーは、アプリが停止したとき、そしてコンテキストが再起動したとき (Bean を変えるホットリロードでも) に失われます。キャッシュは空から始まります。再起動後も残したい結果には、再起動後も残るキャッシュ を参照してください。
- 設定しない限り、何も期限切れにならず、サイズの上限もありません。
- 有効期間は、Caffeine のティッカーと同じく単調時計で測られます。デバイスやサーバーの時計を設定しても、エントリーが長く保たれることも、早く捨てられることもありません。
- 期限切れのエントリーは読まれたときに捨てられ、書き込みがときどき他のものを掃き出します。もう書き込まれないキャッシュは、それらを読まれるまで保持します。
- キャッシュがいっぱいになると、最も長く使われていないエントリーが出ていきます。
nullの結果も保存されます。Spring と同じく、保存されたnullはヒットです。- 一つのアプリ、一つの Isolate: キャッシュはプロセス、Isolate、デバイスの間で共有されません。複数の isolate で動くサーバーについては isolate のプールがある場合 を参照してください。
プロパティ
デフォルトのマネージャーは、アプリケーションが独自の CacheManager を宣言しない場合にだけ、spring.cache.* から作られます。
| プロパティ | デフォルト | 意味 |
|---|---|---|
spring.cache.type |
Cache の Bean があれば generic、なければ simple |
generic: Cache の Bean の SimpleCacheManager (少なくとも一つ必要)。simple: メモリ上のキャッシュ。disk: 再起動後も残るディスク上のキャッシュ (再起動後も残るキャッシュ)。none: 何もキャッシュしない (アノテーションは残り、メソッドは常に実行される)。それ以外の値は起動を失敗させる。 |
spring.cache.cache-names |
空 | キャッシュの固定の集合 (books,authors または YAML のリスト)。その場合、別のキャッシュを指定するアノテーションは失敗する。空: キャッシュは最初の使用時に作られる。 |
spring.cache.simple.time-to-live |
なし | エントリーが書かれた後に生きる時間: 10m、30s、PT1H、またはミリ秒。0 は何も保持しない。負の値は起動を失敗させる。 |
spring.cache.simple.max-size |
なし | キャッシュごとの最大のエントリー数。0 は何も保持しない。負の値は起動を失敗させる。 |
spring.cache.simple.caches.<name>.time-to-live |
全体のもの | 一つのキャッシュについて同じ。 |
spring.cache.simple.caches.<name>.max-size |
全体のもの | 一つのキャッシュについて同じ。 |
キャッシュごとの値はすべて、キャッシュがまだ存在するかどうかにかかわらず、起動時にチェックされます。
キーの中のキャッシュ名
- ドットを含むキャッシュ名は、Spring Boot の他のマップと同じく角括弧に入れます:
spring.cache.simple.caches[books.byIsbn].max-size=2。YAML ではキー"[books.byIsbn]":。 - そのまま書いても (
spring.cache.simple.caches.books.byIsbn.max-size) 動きます。プロパティはキーの末尾 (max-size、time-to-live、または緩い形:maxSize、max_size、MAXSIZE) で、残りがキャッシュ名です。 - 環境変数では、Spring Boot と同じく:
SPRING_CACHE_SIMPLE_CACHES_BOOKS_MAX_SIZE=5または..._BOOKS_MAXSIZE=5、SPRING_CACHE_SIMPLE_CACHES_PRICES_TIME_TO_LIVE=30s。キャッシュ名は小文字になるため、大文字やダッシュを含む名前はこの方法では設定できません。その中の_はここではドットです (..._BOOKS_BYISBN_MAX_SIZEはキャッシュbooks.byisbnを設定します)。
コードで設定する
独自の InMemoryCacheManager の Bean を宣言します。その場合、プロパティはもう適用されません。
@Configuration()
class CacheSetup {
@Bean()
CacheManager cacheManager() => InMemoryCacheManager(
cacheNames: ['books', 'prices'], // この 2 つだけ
defaultSpec: const CacheSpec(timeToLive: Duration(minutes: 10)),
specs: {'prices': const CacheSpec(timeToLive: Duration(seconds: 30), maxSize: 500)},
);
}
InMemoryCacheManager のパラメーター |
意味 |
|---|---|
cacheNames |
キャッシュの固定の集合。なければ、キャッシュは必要に応じて作られる。 |
defaultSpec |
すべてのキャッシュの CacheSpec(timeToLive:, maxSize:)。デフォルトは無制限。 |
specs |
キャッシュ名ごとの仕様。 |
specFor |
キャッシュの名前から仕様を計算する関数。 |
allowNullValues |
デフォルトは true。false では、null を保存すると例外を投げる。 |
clock |
テスト用の時計 (テスト を参照)。 |
負の maxSize や timeToLive は ArgumentError を投げます。
スターターのマネージャーを調整する
CacheManagerCustomizerの Bean は、新しいマネージャーとともに一度だけ呼ばれます。たとえば起動時にいくつかのキャッシュを作るためです。ジェネリックではありません。マネージャーを受け取り、その型をチェックします。cacheManagerFromProperties(properties, environment, caches:, customizers:)は、スターターと同じマネージャーを組み立てます。それを包むものなど、独自のCacheManagerの Bean のためです。
@Bean()
CacheManager cacheManager(CacheProperties properties, Environment environment) =>
MeteredCacheManager(cacheManagerFromProperties(properties, environment)); // 自分のラッパー
isolate のプールがある場合
Web サーバーが isolate のプール を動かすとき (server.isolates.count)、すべての isolate が自分の CacheManager と自分のキャッシュされた値を持ちます。
- 値は、アプリケーションで一度ではなく、isolate ごとに一度計算されます。
@CacheEvictと@CachePutは、それを実行する isolate のキャッシュを変えます。他の isolate は、期限切れになるまで古い値を持ち続けます。max-sizeは isolate ごとに数えられ、エントリーのメモリーも同じです。
プールは、最初に isolate を追加するときに一度だけそのことを伝えます。スターターのマネージャーであるデフォルトのインメモリのものと SimpleCacheManager は、その警告の中で cached values として示されます。
Each isolate keeps its own cached values in memory, and a request may reach any isolate: what one keeps the others do not see. Keep it where all of them do (a database, a shared store), or accept one copy per isolate.
独自の CacheManager は、IsolateLocalState を実装していれば示されます。
キャッシュは、isolate ごとに一つのコピーでも問題ないことがよくあります。持っているものは再び計算でき、有効期間が、二つの isolate が食い違う時間の上限になります。変更の後に古い値が許されない場合は、すべての isolate が共有するストアの上の 独自のキャッシュ を使ってください。
Spring (Java) との対応
spring.cache.type=simple
spring.cache.cache-names=books,authors
spring.cache.type と spring.cache.cache-names は Spring Boot のものです。type が知っているのは generic、simple、disk、none で、disk はこのスターター独自のものです。spring.cache.simple.* はこのスターターのものです。Spring Boot では有効期間とサイズは Caffeine や Redis (spring.cache.caffeine.*、spring.cache.redis.*) から来ます。