
# アノテーション

5 つのアノテーションが、Bean のメソッドの前にキャッシュを置きます。`@Cacheable` はキャッシュを読んで埋め、`@CachePut` は更新し、`@CacheEvict` はエントリーを取り除き、`@Caching` は複数を組み合わせ、`@CacheConfig` はクラスにデフォルトを与えます。キーと条件は、Spring と同じく SpEL 式です。

## 使う理由

キャッシュのルール (どのエントリーを、どのキーで、いつ忘れるか) は、それが高速化するメソッドの隣、読む人に見える場所に置くべきです。アノテーションを使えばメソッドの本体からキャッシュのコードがなくなり、どのキャッシュが背後にあっても同じアノテーションが動きます。

## 例

```dart
@Service()
@CacheConfig(cacheNames: ['books'])
class Books {
  Books(this.api);

  final CatalogApi api;

  @Cacheable.of(key: '#isbn')                               // キャッシュは @CacheConfig から来る
  Future<Book> find(String isbn, {bool includeReviews = false}) => api.load(isbn);

  @Cacheable('books', key: "#isbn + '-' + #lang")           // 組み合わせたキー
  Future<Book> translated(String isbn, String lang) => api.translated(isbn, lang);

  @Cacheable('books', condition: '#isbn.length() == 13')    // 13 桁の ISBN だけキャッシュする
  Future<Book> findIsbn(String isbn) => api.load(isbn);

  @Cacheable('books', unless: '#result == null')            // 見つからなかったものは覚えない
  Future<Book?> maybe(String isbn) => api.maybe(isbn);

  @CachePut('books', key: '#result.isbn')                   // Book は @Introspected
  Future<Book> save(Book book) => api.save(book);

  @CacheEvict('books', allEntries: true)                    // カタログが変わった
  Future<void> reimport() => api.reimport();

  @Caching(evict: [CacheEvict('books', key: '#isbn'), CacheEvict('prices', key: '#isbn')])
  Future<void> delete(String isbn) => api.delete(isbn);
}
```

## アノテーション

| アノテーション | 働き |
|---|---|
| `@Cacheable('books')` | キャッシュされた結果があればそれを返す。なければメソッドを実行し、結果を保存する。 |
| `@CachePut('books', key: '#isbn')` | 常にメソッドを実行し、結果を保存して、エントリーを更新する。`@Cacheable` のヒットと並ぶ場合、Spring と同じく、put の `condition` が通るとき (`#result` を読む条件は通るとみなされる) にだけ、メソッドはいずれにせよ実行される。 |
| `@CacheEvict('books', key: '#isbn')` | メソッドが戻った後にエントリーを取り除く。`allEntries: true` はキャッシュ全体をクリアする。`beforeInvocation: true` は呼び出しの前に取り除くため、例外を投げたときも取り除かれる。 |
| `@Caching(cacheable: [...], put: [...], evict: [...])` | 一つのメソッドに複数の操作。アノテーションを繰り返しても動く。 |
| `@CacheConfig(cacheNames: [...], keyGenerator:, cacheManager:, cacheResolver:)` | クラスに付ける: そのメソッドのデフォルト。 |

`@Cacheable('books')` は一つのキャッシュを指定します。複数のキャッシュを指定するには、あるいは `@CacheConfig` からそれらを取るには、`.of` コンストラクターを使います: `@Cacheable.of(cacheNames: ['books', 'isbn'])` または `@Cacheable.of(key: '#isbn')`。`CachePut.of` と `CacheEvict.of` も同じです。Dart のコンストラクターは、任意の位置引数の名前と名前付き引数を混ぜられないためです。

## オプション

| オプション | 付ける場所 | 意味 |
|---|---|---|
| `cacheNames` | すべて | キャッシュ。`.of` で。 |
| `key` | すべて | キーを計算する SpEL。デフォルト: 引数。 |
| `condition` | すべて | SpEL。`true` のときだけキャッシュが使われる。 |
| `unless` | `@Cacheable`、`@CachePut` | `#result` を使う SpEL。`true` のとき結果は保存されない。ヒットを妨げはしない。 |
| `sync` | `@Cacheable` | `Future` のメソッド向け: 同じキーでの同時の呼び出しは一つの呼び出しを共有する。 |
| `allEntries` | `@CacheEvict` | キャッシュ全体をクリアする。 |
| `beforeInvocation` | `@CacheEvict` | 呼び出しの前に取り除く。 |
| `keyGenerator` | すべて | `KeyGenerator` の Bean の名前 (`key` とは併用しない)。 |
| `cacheManager` | すべて | 使う `CacheManager` の Bean の名前。 |
| `cacheResolver` | すべて | キャッシュを選ぶ `CacheResolver` の Bean の名前 (`cacheManager` とは併用しない)。 |

## アノテーションが適用される場所

- クラスに付けた `@Cacheable`、`@CachePut`、`@CacheEvict`、`@Caching` は、独自のキャッシュのアノテーションを持たないすべての public メソッドに適用されます (ゲッター、セッター、`toString` には適用されません)。
- クラスレベルのアノテーションと `@CacheConfig` は、メソッドの本体を宣言するクラスから、それになければそのスーパークラスから読まれます (最も近いものが優先されます)。`@CacheConfig` を持つ基底クラスはそれを継承する Bean に使われますが、サブクラスのクラスレベルのアノテーションは、それが継承したメソッドには適用されません。
- `@CacheConfig` は、操作が未指定のままにしたものだけを埋めます。操作がキャッシュ名を指定しなければそのキャッシュ名を、操作が `key` も `keyGenerator` も設定しなければその `keyGenerator` を、操作がどちらも設定しなければその `cacheResolver` (なければ `cacheManager`) を使います。

## キー

`key` がなければ、Spring の `SimpleKeyGenerator` と同じく、キーは引数から作られます。

| 引数 | キー |
|---|---|
| なし | `SimpleKey.empty` |
| 一つ | 引数そのもの (単一のリスト、セット、マップは `SimpleKey` に包まれる。Dart のコレクションは同一性で比較されるため) |
| 複数 | 内容で比較する `SimpleKey([...])`。中のコレクションも |

`null` になるキー (`key` やキージェネレーターから) は、`ArgumentError` で呼び出しを失敗させます。

## key、condition、unless の SpEL

`#{}` なしで、そのまま書きます。

| 式 | 値 |
|---|---|
| `#isbn` | `isbn` という名前の引数。 |
| `#p0`、`#a0` | 最初の引数。 |
| `#result` | 結果: `unless` で。`@CachePut` の `key` と `condition` で。呼び出し後の `@CacheEvict` で。 |
| `#root.methodName` | `find`。 |
| `#root.method.name` | `find` (`returnType`、`parameterTypes`、`parameterNames`、`parameterCount` もテキストとして)。 |
| `#root.args` | すべての引数。`#root.args[1]`。 |
| `#root.target` | Bean。 |
| `#root.targetClass` | Bean のクラス名、`Books`。 |
| `#root.caches` | 操作のキャッシュ名。 |
| `@region` | `region` という名前の Bean。 |

自分のオブジェクトのプロパティを読んだりメソッドを呼んだりする (`#book.isbn`、`#result.isbn`、`@clock.zone()`) には、そのクラスに `@Introspected()` が必要です。ジェネレーターが SpEL の使うアクセサーを書きます。文字列、数値、リスト、マップはそのまま使えます (`#isbn.length()`、`#tags.size()`)。

## 非同期のメソッド

`Future` を返すメソッドは、Future ではなく**値**をキャッシュします。値は Future が完了したときに保存され、ヒットはすでに完了した `Future` を返し、エラーは決してキャッシュされないため、次の呼び出しは再び試みます。

`sync: true` では、最初の呼び出しがまだ実行中に届いた呼び出しは、メソッドを再び実行する代わりにそれを待ちます。`sync` の操作は、メソッドの唯一のキャッシュのアノテーションで、一つのキャッシュを使い、`unless` を持たないものでなければなりません。待機はメソッドごとではなく、キャッシュとキーごとに共有されます。同じキャッシュを使い同じキーを計算する 2 つの `sync` メソッドは、一つの保留中の結果を共有します。

`Stream` はキャッシュできません。一度しか購読できないためです。`Stream` を返すメソッドの `@Cacheable` と `@CachePut` はビルドを失敗させます。代わりに値を集めてください。

```dart
@Cacheable('events')
Future<List<Event>> recent() => api.events().toList();
```

## 起動時のチェック

プロキシされたすべての Bean のアノテーションは Bean の生成時にチェックされるため、誤った組み合わせはメンバーを示して起動を失敗させます。

- `key` と `keyGenerator`。
- `cacheManager` と `cacheResolver`。
- 他の操作、複数のキャッシュ、または `unless` を伴う `sync`。
- キャッシュ名のない操作 (キャッシュリゾルバーがそれを選ぶ場合を除く)。
- `Stream` を返すメソッドの `@Cacheable` / `@CachePut`。

このチェックは `cacheOperationValidator` の Bean で、独立したモジュールにある起動時チェックです。`spring.main.startup-checks.enabled` でビルドに含まれ、未設定ならデバッグビルドとプロファイルビルドだけなので、リリースビルドにはそのコードがなく、誤ったアノテーションはそのメンバーの最初の呼び出しで失敗します。`application.yml` または `application.properties` で `true` にするとすべてのビルドに、`false` にするとどのビルドにも含まれません。

## Spring (Java) との対応

```java
@Cacheable(cacheNames = {"books", "isbn"}, key = "#isbn", unless = "#result == null")
public Book find(String isbn) { ... }
```

アノテーションと SpEL の変数は Spring のものです。`#root.caches` はキャッシュ名を、`#root.targetClass` はクラス名を、`#root.method` は `MethodSignature` を持ちます。`sync` のルールは起動時にチェックされます (Spring は最初の呼び出しでチェックします)。

## 関連項目

- [メモリ上のキャッシュ](in-memory-caches.md)
- [独自のキャッシュ](custom-caches.md)
- [SpEL](../spring-core-dart/spel/index.md)
