独自のキャッシュ

アノテーションが話す相手は 2 つのインターフェースだけです。CacheManager (名前でキャッシュを見つける) と Cache (一つのキャッシュ: get、put、evict、clear) です。そのため、ファイル、キーバリューのデータベース、テナントごとのキャッシュなど、何でもその背後に置けます。CacheManager の Bean を宣言すれば、スターターのものは身を引きます。

使う理由

メモリ上のキャッシュは再起動で失われ、インスタンス間で共有されません。Flutter アプリはキャッシュしたデータを再起動後も残したいかもしれませんし、クラスターは一つの共有のキャッシュを望むかもしれません。同じ @Cacheable メソッドは動き続け、ストレージだけが変わります。

例

メモリ上のキャッシュと混在させた、キーバリューのストアに JSON として保持されるエントリー:

import 'dart:convert';

/// 任意の同期的なキーバリューのストレージ: ファイル、キーバリューのデータベース...
abstract interface class KeyValueStore {
  String? read(String key);
  void write(String key, String value);
  void delete(String key);
  void deleteAll({required String prefix});
}

/// 再起動後も残るよう、ストアに JSON として保持されるエントリー。
final class StoreCache with CacheDefaults implements Cache {
  StoreCache(this.name, this.store);

  @override
  final String name;
  final KeyValueStore store;

  String _key(Object? key) => '$name:$key';

  @override
  ValueWrapper? get(Object? key) => switch (store.read(_key(key))) {
        null => null,                                 // ミス: メソッドが実行される
        final json => ValueWrapper(jsonDecode(json)), // ヒット (保存された null も)
      };

  @override
  void put(Object? key, Object? value) => store.write(_key(key), jsonEncode(value));

  @override
  void evict(Object? key) => store.delete(_key(key));

  @override
  void clear() => store.deleteAll(prefix: '$name:');
}

@Configuration()
class CacheSetup {
  @Bean()
  CacheManager cacheManager(KeyValueStore store) => SimpleCacheManager([
        StoreCache('books', store),   // ストアに保持される
        InMemoryCache('prices'),      // メモリ上
      ]);
}

インターフェース

型 働き 組み込みのもの
CacheManager getCache(name)、cacheNames。 InMemoryCacheManager、SimpleCacheManager、NoOpCacheManager
Cache name、get、put、putIfAbsent、evict、evictIfPresent、clear、invalidate。 InMemoryCache、NoOpCache
CacheDefaults (mixin) putIfAbsent、evictIfPresent、invalidate を他の 4 つから導く。

覚えておくべきこと:

必要に応じて作られるキャッシュ

SimpleCacheManager は与えられたキャッシュしか知りません。その場合 @Cacheable('other') は "Cannot find cache named 'other'" で失敗します。最初に指定されたときにキャッシュを作るには、CacheManager を実装します。

final class StoreCacheManager implements CacheManager {
  StoreCacheManager(this.store);

  final KeyValueStore store;
  final _caches = <String, Cache>{};

  @override
  Cache? getCache(String name) => _caches.putIfAbsent(name, () => StoreCache(name, store));

  @override
  Iterable<String> get cacheNames => _caches.keys;
}

spring.cache.type=generic (Cache の Bean があるときのデフォルト) では、スターターは Cache の Bean から SimpleCacheManager を作ります。

複数のマネージャー

ほとんどのメソッドにはメインのマネージャーを使い、一部には別のものを使うには、別のものに名前を付け、型による注入から隠し、アノテーションでそれを指定します。

@Configuration()
class CacheSetup {
  // セッションはストアに保持し、それ以外はメモリに置く。
  @Bean(autowireCandidate: false)
  CacheManager sessionCaches(KeyValueStore store) =>
      SimpleCacheManager([StoreCache('sessions', store)]);
}

@Cacheable('sessions', cacheManager: 'sessionCaches')
Session load(String token) => sessions.load(token);

独自のキー: KeyGenerator

// "978-0-00" と "978000" は同じ本。
final class IsbnKeys implements KeyGenerator {
  const IsbnKeys();

  @override
  Object? generate(Object target, MethodSignature method, List<Object?> args) =>
      (args.first! as String).replaceAll('-', '');
}

@Configuration()
class Keys {
  @Bean()
  KeyGenerator isbnKeys() => const IsbnKeys();
}

@Cacheable('books', keyGenerator: 'isbnKeys')
Book find(String isbn) => load(isbn);

呼び出しごとにキャッシュを選ぶ: CacheResolver

CacheResolver は、呼び出しのたびに、操作がどのキャッシュを使うかを決めます。たとえばテナントごとに一つのキャッシュです。操作 (そのキャッシュ名、キー...)、Bean、メソッド、引数を見ます。

// 各テナントは独自のキャッシュを持つ: "acme.books"、"globex.books"...
final class TenantCacheResolver implements CacheResolver {
  TenantCacheResolver(this.manager, this.tenants);

  final CacheManager manager;
  final TenantContext tenants;

  @override
  Iterable<Cache> resolveCaches(CacheOperationInvocationContext context) => [
        for (final name in context.operation.cacheNames)
          manager.getCache('${tenants.current}.$name')!,
      ];
}

@Cacheable('books', cacheResolver: 'tenantCacheResolver')
Book find(String isbn) => load(isbn);

組み込みのもの: SimpleCacheResolver(manager) (デフォルト: マネージャーの中の操作の名前) と NamedCacheResolver(manager, ['audit']) (常に同じキャッシュ。その場合、操作は名前を必要としない)。Spring Boot と同じく、cacheResolver という名前の Bean があると、スターターの cacheManager は身を引きます。

すべてのデフォルト: CachingConfigurer

CachingConfigurer を実装する一つの Bean が、すべてのキャッシュ操作のデフォルトを設定します。null を返すメソッド (デフォルト) はスターターのものを保ちます。

メソッド デフォルト
cacheManager() CacheManager の Bean
cacheResolver() キャッシュマネージャーの SimpleCacheResolver
keyGenerator() SimpleKeyGenerator
errorHandler() SimpleCacheErrorHandler: キャッシュのエラーは呼び出し元に届く
@Configuration()
class CacheSetup with CachingConfigurer {
  @override
  KeyGenerator keyGenerator() => const IsbnKeys();

  // ダウンしているキャッシュ: ログに出し、メソッドを実行し、続ける。
  @override
  CacheErrorHandler errorHandler() => const LoggingCacheErrorHandler();
}

メソッドは、キャッシュが最初に使われたときに一度だけ呼ばれます。メソッドに @Bean を付けるのではなく、オブジェクト (または構成に注入した Bean) を返してください。Dart は @Configuration クラスをプロキシしないため、@Bean メソッドを呼ぶと 2 つ目のインスタンスが作られます。

エラー: CacheErrorHandler

再スローしない CacheErrorHandler があると、失敗した get はミスとみなされ (メソッドが実行されます)、失敗した put、evict、clear はスキップされます。LoggingCacheErrorHandler はそれらを spring.cache に warning レベルでログに出します (logStackTraces: true はスタックトレースを追加し、logger: は別のロガーを指定します)。ハンドラーのメソッドは、エラーとともにスタックトレースを受け取ります。

Spring (Java) との対応

@Bean
CacheManager cacheManager() { return new SimpleCacheManager(); }

インターフェースは Spring のものですが、Cache はより小さく、get(key, Class)、get(key, Callable)、retrieve、getNativeCache はありません。retrieve は、ストアの応答が後から来るキャッシュのための AsyncCache にあります (再起動後も残るキャッシュ を参照)。CacheManagerCustomizer はジェネリックではありません。CachingConfigurer のメソッドは @Bean メソッドであってはいけません。

関連項目