アノテーション

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 とは併用しない)。

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

キー

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 の生成時にチェックされるため、誤った組み合わせはメンバーを示して起動を失敗させます。

このチェックは 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 は最初の呼び出しでチェックします)。

関連項目