
# 独自のキャッシュ

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

## 使う理由

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

## 例

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

```dart
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` を実装します。

```dart
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` を作ります。

## 複数のマネージャー

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

```dart
@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

```dart
// "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、メソッド、引数を見ます。

```dart
// 各テナントは独自のキャッシュを持つ: "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`: キャッシュのエラーは呼び出し元に届く |

```dart
@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) との対応

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

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

## 関連項目

- [メモリ上のキャッシュ](in-memory-caches.md)
- [アノテーション](annotations.md)
- [@Bean](../spring-core-dart/beans/bean-method-annotation.md)
