
# メモリ上のキャッシュ

何も設定しなくても、スターターは `cacheManager` の Bean、`InMemoryCacheManager` (Spring の `ConcurrentMapCacheManager`) を作ります。各キャッシュは `InMemoryCache` で、動作中のアプリのメモリ上のマップです。アノテーションが最初にそれを指定したときに作られます。有効期間とサイズの上限は、全体またはキャッシュごとに、`spring.cache.*` プロパティから来ます。

## 使う理由

ほとんどのキャッシュは、再起動後に再計算するのが安価な、遅い呼び出しの結果を保持します。メモリはそれらにとって最も速い場所で、何の準備も要りません。Spring の `simple` タイプには有効期限もサイズの上限もなく、そのためには Caffeine を使うよう案内されます。ここではメモリ上のキャッシュが両方を持つため、長時間動くサーバーが際限なく大きくなることはありません。

## 例

```properties
# 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  # ドットを含むキャッシュ名
```

```dart
// 管理者の操作: キャッシュされたすべての本を捨てる。
@Component()
class CacheAdmin {
  CacheAdmin(this.caches);

  final CacheManager caches;

  void clearBooks() => caches.getCache('books')?.clear();
}
```

## メモリ上のキャッシュがすること

- 各キャッシュは、`spring.cache.cache-names` が集合を固定していない限り、アノテーションが最初にそれを指定したとき (`'books'`) に作られます。
- エントリーは、アプリが停止したとき、そしてコンテキストが再起動したとき (Bean を変えるホットリロードでも) に失われます。キャッシュは空から始まります。再起動後も残したい結果には、[再起動後も残るキャッシュ](disk-caches.md) を参照してください。
- 設定しない限り、何も期限切れにならず、サイズの上限もありません。
- 有効期間は、Caffeine のティッカーと同じく単調時計で測られます。デバイスやサーバーの時計を設定しても、エントリーが長く保たれることも、早く捨てられることもありません。
- 期限切れのエントリーは読まれたときに捨てられ、書き込みがときどき他のものを掃き出します。もう書き込まれないキャッシュは、それらを読まれるまで保持します。
- キャッシュがいっぱいになると、最も長く使われていないエントリーが出ていきます。
- `null` の結果も保存されます。Spring と同じく、保存された `null` はヒットです。
- 一つのアプリ、一つの Isolate: キャッシュはプロセス、Isolate、デバイスの間で共有されません。複数の isolate で動くサーバーについては [isolate のプールがある場合](#isolate-のプールがある場合) を参照してください。

## プロパティ

デフォルトのマネージャーは、アプリケーションが独自の `CacheManager` を宣言しない場合にだけ、`spring.cache.*` から作られます。

| プロパティ | デフォルト | 意味 |
|---|---|---|
| `spring.cache.type` | `Cache` の Bean があれば `generic`、なければ `simple` | `generic`: `Cache` の Bean の `SimpleCacheManager` (少なくとも一つ必要)。`simple`: メモリ上のキャッシュ。`disk`: 再起動後も残るディスク上のキャッシュ ([再起動後も残るキャッシュ](disk-caches.md))。`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 を宣言します。その場合、プロパティはもう適用されません。

```dart
@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` | テスト用の時計 ([テスト](testing.md) を参照)。 |

負の `maxSize` や `timeToLive` は `ArgumentError` を投げます。

## スターターのマネージャーを調整する

- `CacheManagerCustomizer` の Bean は、新しいマネージャーとともに一度だけ呼ばれます。たとえば起動時にいくつかのキャッシュを作るためです。ジェネリックではありません。マネージャーを受け取り、その型をチェックします。
- `cacheManagerFromProperties(properties, environment, caches:, customizers:)` は、スターターと同じマネージャーを組み立てます。それを包むものなど、独自の `CacheManager` の Bean のためです。

```dart
@Bean()
CacheManager cacheManager(CacheProperties properties, Environment environment) =>
    MeteredCacheManager(cacheManagerFromProperties(properties, environment)); // 自分のラッパー
```

## isolate のプールがある場合

Web サーバーが [isolate のプール](../spring-boot-starter-web/server/isolates.md) を動かすとき (`server.isolates.count`)、すべての isolate が自分の `CacheManager` と自分のキャッシュされた値を持ちます。

- 値は、アプリケーションで一度ではなく、isolate ごとに一度計算されます。
- `@CacheEvict` と `@CachePut` は、それを実行する isolate のキャッシュを変えます。他の isolate は、期限切れになるまで古い値を持ち続けます。
- `max-size` は isolate ごとに数えられ、エントリーのメモリーも同じです。

プールは、最初に isolate を追加するときに一度だけそのことを伝えます。スターターのマネージャーであるデフォルトのインメモリのものと `SimpleCacheManager` は、その警告の中で `cached values` として示されます。

```text
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 が共有するストアの上の [独自のキャッシュ](custom-caches.md) を使ってください。

## Spring (Java) との対応

```properties
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.*`) から来ます。

## 関連項目

- [すべてのプロパティ](properties.md)
- [再起動後も残るキャッシュ](disk-caches.md)
- [独自のキャッシュ](custom-caches.md)
- [isolate のプール](../spring-boot-starter-web/server/isolates.md)
- [Durations](../spring-core-dart/conversion/durations.md)
