
# AOP プロキシ: 刈り込みと遅延

Spring は実行時に、JDK 動的プロキシまたは CGLIB サブクラスで AOP プロキシを作ります。Dart は実行時にクラスを作れないため、ジェネレーターは、アドバイスがラップする必要がありうる Bean ごとにプロキシクラス (`_$OrdersProxy`) を書き出します。コンテキストは、アドバイザーが Bean に一致するときはそのクラスを、それ以外では Bean そのものを使います。

すべての Bean にプロキシクラスを書くと、決して実行されない大量のコードになります。このページでは、ジェネレーターが、アプリケーションのアドバイスが到達しうるプロキシクラスとそのメンバーだけを残す方法を説明します。

## 使う理由

プロキシクラスは Bean のすべてのメンバーを繰り返します。各メソッドとゲッターが、アドバイスのチェーンを通して Bean に転送します。何百もの Bean と少数のアスペクトを持つアプリでは、それらのクラスのほとんどすべてが死んだコードです。生成ファイルを長くし、コンパイルを遅くし、アプリを大きくします。

ビルドはアプリケーションが宣言するすべてのポイントカットを見ているので、アドバイスがどの Bean に一致しうるかがわかります。それらにはプロキシクラスを書き、残りには「ビルドは調べたが、アドバイスは見つからなかった」と示す小さなマーカーを書きます。ビルドが見なかったものが実行時に現れた場合、コンテキストはアドバイスを黙ってスキップする代わりに、明確なメッセージとともに起動時に失敗します。

## 三つのオプション

三つともアプリケーションの `build.yaml` で設定します ([オプション](../options.md) を参照)。

| オプション | 値 | デフォルト | 決めるもの |
|---|---|---|---|
| `aop_proxies` | `all`、`interfaces`、`none` | `all` | そもそもどの Bean がプロキシクラスを持ちうるか。 |
| `aop_prune` | `true`、`false` | `true` | どのアドバイスも一致しえないプロキシクラスとメンバーを省くかどうか。 |
| `aop_defer` | `true`、`false` | `false` | `lib/spring_auto_configuration.dart` のないライブラリパッケージが、スターターと同じように、プロキシクラスをアプリケーションに任せるかどうか。 |

オプションが変えるのは生成されるコードの量だけです。実行時には、一致するアドバイスのない Bean は、どの設定でもラップされることはありません。

## `aop_proxies`: どの Bean をプロキシ化できるか

| 値 | プロキシクラス |
|---|---|
| `all` | クラスまたはそのインターフェースのいずれかを実装できるすべての Bean に対して、Bean の型を実装するラッパークラス (`class _$OrdersProxy implements Orders, ...`)。継承しかできないクラス (たとえば private なメンバーを持つ) は代わりにサブクラスプロキシを受け取り、Bean は生成されたサブクラスとして生成されます。 |
| `interfaces` | JDK 動的プロキシのように、Bean の抽象スーパータイプを通してのみ。それを持たない Bean はプロキシを受け取りません。 |
| `none` | プロキシクラスなし。AOP はモジュールの Bean にアドバイスできません。 |

`all` は Spring の `@EnableAspectJAutoProxy(proxyTargetClass = true)` に、`interfaces` は `proxyTargetClass = false` に相当します。

## `aop_prune`: アドバイスが一致しうるプロキシだけ

`aop_prune: true` (デフォルト) では、ジェネレーターは Bean ごとに、アプリケーションのいずれかのアドバイスがそのメンバーのいずれかに一致しうるかを判断します。

### 刈り込む場所

刈り込みにはアプリケーションのすべてのアドバイスを知る必要があるので、ビルドがそのすべてを見られる場所でだけ行われます。

| 出力 | 刈り込み | 理由 |
|---|---|---|
| `@SpringBootApplication` の出力 | する | アプリケーションのすべてのモジュールとその自動構成を知っている。 |
| アプリケーション (`pubspec.yaml` に `publish_to: none` を持つパッケージ) の `@ComponentScan` モジュール | する | アプリケーションの外からインポートされることはない。ビルドは `lib/` と `bin/` にあるパッケージの他のライブラリと、自動構成のアドバイスを読む。 |
| ライブラリパッケージの `@ComponentScan` モジュール | しない | どのアプリケーションもそれをインポートし、ライブラリのビルドからは見えないアスペクトを持ち込みうる。 |
| スターターの `lib/` のモジュール | プロキシは遅延される。下記を参照 | アプリケーションのビルドがそれらを書き出す。 |

### 読むアドバイス

判断のため、ビルドは次のものを読みます。

- アプリケーションのモジュールのすべての `@Aspect` クラス (アドバイスと `@Pointcut` の式)。
- `@Bean` メソッドが返すアスペクト。
- `@Bean` メソッドが `DefaultPointcutAdvisor(ExpressionPointcut('<定数の式>'), ...)`、`AnnotationMatchingPointcut<A>()`、またはアノテーションを宣言するポイントカットを組み立てるアドバイザー Bean。
- 自動構成のアドバイザー。スターターのアノテーションのポイントカットは、一致するアノテーションを `static const annotationTypes` リストで宣言します (`@Transactional`、`@Cacheable`、メソッドセキュリティ、`@Validated`)。そのいずれかを持つ Bean だけがプロキシを保ちます。

ポイントカットはランタイム自身のパーサーとマッチャー (`spring_core_dart` の `ExpressionPointcut`) で照合されるので、何が一致するかについてビルドと実行中のアプリの見解は一致します。

### プロキシを保つもの

Bean は次の場合にプロキシクラスを保ちます。

- ポイントカットがそのメンバーのいずれかに一致しうる (名前、型、アノテーション、その名前、エイリアス、修飾子による `bean(...)`)。
- そのクラスまたはメンバーのいずれか (またはパラメーター、オーバーライドされた宣言) が、アノテーション駆動のアドバイザーが一致するアノテーション、またはそのようなアノテーションのサブクラス (`class AdminTransactional extends Transactional`) を持つ。
- `@DeclareParents` のイントロダクションを持つ。
- そのプロキシが `ChangeNotifier` を mixin する (Flutter アプリで、それ自体は `ChangeNotifier` でない `@ChangeNotifierComponent`)。

SDK (`@override`、`@Deprecated`)、`package:meta`、`spring_core_dart` のアノテーションは、アドバイザーがそれを指定しない限り (`AnnotationMatchingPointcut<Service>`) プロキシを保ちません。`@ConfigurationProperties` クラスの `@Validated` も保ちません。起動時にバインドされた値を一度バリデーションするだけで、メソッドバリデーションは Spring Boot と同じくそのようなクラスを対象外にするからです。

### 何も刈り込まれない場合

刈り込みには確実性が必要です。次の場合、すべての Bean が完全なプロキシを保ちます。

- モジュールが、ビルドが読めないポイントカット (変数からの式、手書きのポイントカットクラス) を持つアドバイザー Bean を宣言している。
- 自動構成がアスペクトを宣言している (そのライブラリが `AspectMetadata` に触れる)、またはビルドが読めないポイントカットを持つアドバイザーを宣言している。
- ポイントカットが、ビルドがたどれない名前付きポイントカットを参照している。
- `aop_prune: false` が設定されている。

### 刈り込まれた Bean

一致するアドバイスのない Bean は、プロキシクラスを受け取らず、定数のマーカーを受け取ります。実際の生成ファイルから、インポートのプレフィックスを外したものです。

```dart
const _$knownAdvisors0 = {
  r'package:spring_boot_dart',
  r'package:spring_boot_starter_cache',
  r'package:spring_boot_starter_flutter',
  // ... ビルドがアドバイザーを読んだすべてのスターター
};

// ...
BeanDefinition<AppAssets>(
  name: r'appAssets',
  source: r'package:neon_books_app/src/about/app_assets.dart#AppAssets',
  // ...
  aopProxy: const AopProxyFactory.pruned(
    knownAdvisors: _$knownAdvisors0,
  ),
),
```

- `AopProxyFactory.pruned()` は、ビルドがその Bean のアドバイスを見つけなかったことをコンテキストに伝えます。その `unavailableReason` は `AopProxyFactory.prunedReason` で、"the build found no pointcut of the application that matches it, so it generated no proxy class for it (set the build option aop_prune: false to generate one for every bean)." です。このテキストはすべての生成ファイルではなく、ランタイムに一度だけ存在します。
- `knownAdvisors` は、ビルドが知っていたすべてのアスペクトとアドバイザー Bean の `source` を列挙します。`#` のないエントリーはパッケージ全体を表します。このセットはモジュールごとに一度宣言されます。
- サブクラスプロキシも同じように刈り込まれます。その場合、Bean は自身のクラスとして生成されます (`create: (r) => Counted()`)。

### 部分的なプロキシ: メンバー単位の転送

アドバイスが Bean の一部のメンバーにだけ一致しうる場合、プロキシクラスはそれらだけをインターセプトします。入力:

```dart
@Service()
class MixedOrders {
  @Transactional()
  Future<void> place() async {}

  int count() => 0;

  String get label => '';
}
```

プロキシ (簡略化、プレフィックスは外しています):

```dart
class _$MixedOrdersProxy with AdvisedWrapper implements MixedOrders {
  // ...
  /// place: `@Transactional()`
  @override
  Future<void> place() => this.aopInvoker.invokeAsync<void>(/* ... */);

  // どのポイントカットも一致しえないメンバー: アドバイスなしで転送される。
  @override
  int count() => this._target.count();

  @override
  String get label => this._target.label;
}
```

生成された各プロキシクラスとメンバーには `///` コメントがあり、ビルドがその周りで実行するものとして何を見つけたかを示します。アドバイザーが一致するアノテーションは書かれたとおり (`@Transactional()`)、アスペクトのアドバイスは `@Around TimingAspect.time` のように、アドバイザー Bean です。インボーカーは名前付き引数 (`proxy:`、`target:`、`methodIndex:`、`arguments:`、`original:`) で呼ばれ、AOT のベンチマークでは測れるほどのコストはありません。

ファクトリーに `MethodSignature` を持つのは `place` だけです。サブクラスプロキシは、アドバイスされるメンバーだけをオーバーライドし、それ以外を継承することで同じことを行います。部分的なプロキシのファクトリーも `knownAdvisors` を持ちます。

### ビルドが見なかったアドバイスが現れたとき

ビルドからは、コードで登録されたアドバイスは見えません。`BeanDefinitionRegistrar`、`BeanFactoryPostProcessor`、`registerSingleton` で登録されたアスペクトやアドバイザーです。刈り込まれたプロキシや部分的なプロキシでは、そのアドバイスはビルドが省いたメンバーに届きません。そこでコンテキストは起動時、シングルトンを生成する前にチェックし、失敗します。

```text
The advisor bean 'audit' (registered in code) is not one the build knew of
when it generated the proxies of the beans for only the advice it found (bean
'mixedOrders' and maybe others): its advice would not reach the members left
out. Build the application with the option aop_prune: false, or declare the
advice where the build reads it (an @Aspect, or a @Bean method returning a
DefaultPointcutAdvisor with a constant pointcut).
```

部分的なプロキシに対する `Advised.addAdvisor` も同じ理由で失敗します。アプリケーションが実行時にアドバイスを追加する場合は、`aop_prune: false` でビルドしてください。

## 遅延されるプロキシ: スターターはアプリケーションに任せる

スターターのビルドは、それを使うアプリケーションのアスペクトを知りえません。「念のため」すべてのスターターの Bean にプロキシクラスを書くと、そのコードがすべてのアプリに入ってしまいます。そこでスターター (`lib/spring_auto_configuration.dart` を持つパッケージ) の `lib/` のモジュールは、アプリケーションのアスペクトだけが一致しうる各 Bean に対して、代わりにプレースホルダーを書きます。

```dart
// spring_boot_dart/lib/spring_gen/src/properties/properties.spring.dart
// (生成。プレフィックスは外している)
BeanDefinition<MainProperties>(
  name: r'mainProperties',
  source: r'package:spring_boot_dart/src/properties/boot_properties.dart#MainProperties',
  create: (r) => MainProperties(),
  annotations: const [ConfigurationProperties(r'spring.main')],
  aopProxy: const AopProxyFactory.deferred(
    signatures: [
      MethodSignature.of(
        r'allowBeanDefinitionOverriding',
        _$target0,
        kind: MemberKind.getter,
        returnType: r'bool',
      ),
      // ... メンバーごとに一つのシグネチャー
    ],
  ),
),
```

Bean が遅延されるのは、スターター自身の何ものもそれにアドバイスできない場合だけです。そのアノテーション、そのメンバーとパラメーターのアノテーションが、どのアドバイザーも一致しないもの (SDK、`package:meta`、`spring_core_dart`、`spring_boot_dart` のもの。`@Validated` を除く) であり、スターター自身のパッケージのどのポイントカットも一致せず、(サブクラスプロキシではなく) ラッパーであり、イントロダクションを持たないことです。モジュールがアドバイザー Bean を宣言するスターター、または自動構成がビルドの読めないアスペクトやアドバイザーを宣言するスターターは、何も遅延しません。

### アプリケーションがそれらを書き出す

`@SpringBootApplication` の出力は、自動構成ライブラリとアプリケーション自身のライブラリが、インポートまたはエクスポートするライブラリを通して到達する生成されたモジュールの中で、任意のパッケージにわたってこれらのプレースホルダーを探します。アプリケーションのポイントカットのいずれかがメンバーに一致しうるそのような Bean ごとに、プロキシクラスを書き出し、そのファクトリーを Bean の `source` で登録します。

```dart
// bin/spring_gen/main.spring.dart (生成。プレフィックスは外し、ファクトリーは短縮)
class _$BannerPropertiesProxy with AdvisedWrapper implements BannerProperties {
  // ...
}

BeanModule get $application => BeanModule(
  r'application',
  [/* アプリケーションの Bean */],
  aopProxies: {
    r'package:spring_boot_dart/src/properties/boot_properties.dart#BannerProperties':
        AopProxyFactory(
          signatures: const [/* ... */],
          create: (target, invoker) =>
              _$BannerPropertiesProxy(target as BannerProperties, invoker),
        ),
  },
);
```

コンテキストは、どのモジュールが先に読み込まれても、プレースホルダーの場所にそのファクトリーを置きます。どのポイントカットも一致しない遅延された Bean は、アプリケーションで何も受け取りません。`aop_prune: false` では、アプリケーションはすべての遅延された Bean のプロキシを書き出します。`aop_proxies: none` では何も書き出しません。

アプリケーションの生成されたモジュールなしで組み立てられたコンテキスト (`ApplicationContextRunner`、手書きのモジュールのリスト) には、遅延された Bean のプロキシクラスがありません。その場合、それに一致するアドバイスは `AopProxyFactory.deferredReason` で起動を失敗させます。それは、`@SpringBootApplication` でアプリケーションをビルドするか、`aop_prune: false` を使うか、`@Bean` メソッドで Bean を宣言するよう伝えます。

### `aop_defer`: スターターがインポートするライブラリ

`lib/spring_auto_configuration.dart` のないライブラリパッケージは、どのモジュールからもインポートされうるため、デフォルトではすべてのプロキシを保ちます。常にスターターの自動構成を通して到達されるライブラリもあります。`spring_boot_actuator` はその一つです (アクチュエータースターターの自動構成がそれをインポートします)。そのようなライブラリは `aop_defer: true` を設定し、その `lib/` のモジュールはスターターのものと同じように遅延します。

```yaml
# spring_boot_actuator の build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        enabled: false
      spring_core_dart_generator:spring_properties:
        enabled: true
        generate_for: [lib/src/properties/**]
        options:
          aop_defer: true
```

`spring_boot_actuator` では、これにより生成されたモジュールが 2083 行から 1420 行になりました。遅延には、ライブラリのビルドで `aop_prune` が `true` である必要があります。

### 遅延されるプロキシはビルド条件に従う

スターターのモジュールがプロパティによってビルドから外される場合 ([ビルドから外されるモジュール](build-conditions.md) を参照)、その Bean のプロキシも一緒に外されます。

| 遅延された Bean を定義するもの | アプリケーションでは |
|---|---|
| `never` と判定されたモジュールだけ | プロキシクラスなし、`aopProxies` エントリーなし、インポートなし |
| `notInRelease` と判定されたモジュールだけ | `if (!const bool.fromEnvironment('dart.vm.product'))` の下の `aopProxies` エントリー。リリースではクラスが取り除かれる |
| 常に含まれるモジュールが一つ以上 | 通常どおりのプロキシ |

## オプションの選び方

- ほとんどすべてのアプリケーションでは、デフォルト (`aop_proxies: all`、`aop_prune: true`) のままにします。
- アドバイスが実行時にコードで登録される場合は `aop_prune: false` を設定します。
- 抽象型を通してだけアドバイスするには `aop_proxies: interfaces` を、AOP をまったく必要としないモジュールには `none` を設定します。
- `aop_defer: true` は、スターターの自動構成がそのモジュールをインポートするライブラリでだけ設定します。

## 関連項目

- [オプション](../options.md)
- [ビルドから外されるモジュール](build-conditions.md)
- [最適化の概要](index.md)
- [ビルド時のチェック](../checks.md)
- [プロキシ](../../spring-core-dart/aop/proxies.md)
- [ポイントカット](../../spring-core-dart/aop/pointcut.md)
