独自のキャッシュ
アノテーションが話す相手は 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 つから導く。 |
覚えておくべきこと:
- ヒットには
ValueWrapperを、ミスにはnullを返してください。ValueWrapper(null)はキャッシュされたnullで、単なるnullを返すとメソッドが再び実行されます。 - キーはメソッドの引数 (一つの引数ならその引数、複数なら
SimpleKey)、またはkey:が計算するものです。文字列を必要とするストアはそれらを文字列に変えなければなりません。文字列、数値、SimpleKeyには'$key'が使えます。自分のクラスにはtoStringをオーバーライドするか、key: '#isbn'を設定してください。 - 値はメソッドが返すものです。メモリ外のストアはそれらをシリアライズしなければなりません。マップ、リスト、文字列、数値には JSON を。自分のクラスには
toJson/fromJsonが必要です。 CacheDefaultsのinvalidate()は、空のキャッシュでも常にtrueを返します。アノテーションがそれを呼ぶことはありません。- Spring と同じく、
Cacheインターフェースは同期的です。非同期のストア (SQLite、shared_preferences、サーバー) では、エントリーをメモリに保持し、保存されたものをバックグラウンドで読み込み (それまでの呼び出しはミスで、メソッドが単に実行されます)、変更をunawaited(...)でバックグラウンドで書き戻してください。 - 独自のキャッシュが投げたエラーは、
CacheErrorHandlerが別のことを言わない限り (下記)、キャッシュされたメソッドの呼び出し元に届きます。
必要に応じて作られるキャッシュ
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 メソッドであってはいけません。