アノテーション
5 つのアノテーションが、Bean のメソッドの前にキャッシュを置きます。@Cacheable はキャッシュを読んで埋め、@CachePut は更新し、@CacheEvict はエントリーを取り除き、@Caching は複数を組み合わせ、@CacheConfig はクラスにデフォルトを与えます。キーと条件は、Spring と同じく SpEL 式です。
使う理由
キャッシュのルール (どのエントリーを、どのキーで、いつ忘れるか) は、それが高速化するメソッドの隣、読む人に見える場所に置くべきです。アノテーションを使えばメソッドの本体からキャッシュのコードがなくなり、どのキャッシュが背後にあっても同じアノテーションが動きます。
例
@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 はビルドを失敗させます。代わりに値を集めてください。
@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) との対応
@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 は最初の呼び出しでチェックします)。