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

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

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

使う理由

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

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

三つのオプション

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

オプション 値 デフォルト 決めるもの
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/ のモジュール プロキシは遅延される。下記を参照 アプリケーションのビルドがそれらを書き出す。

読むアドバイス

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

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

プロキシを保つもの

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

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

何も刈り込まれない場合

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

刈り込まれた Bean

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

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,
  ),
),

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

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

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

  int count() => 0;

  String get label => '';
}

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

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

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 に対して、代わりにプレースホルダーを書きます。

// 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 で登録します。

// 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/ のモジュールはスターターのものと同じように遅延します。

# 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 である必要があります。

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

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

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

オプションの選び方

関連項目