オプション

メインのビルダー spring_core_dart_generator:spring_core_dart は四つのオプションを受け取ります。オプションは、ビルドされるパッケージの pubspec.yaml の隣にある build.yaml に書きます。パッケージの他のビルダーはオプションを受け取りません。

# build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          aop_proxies: all
          aop_prune: true
          aop_defer: false
          dart_defines_exclude: []

build.yaml がない場合や options: がない場合、すべてのオプションはデフォルトになります。ほとんどすべてのアプリケーションではそれが正しい選択です。

使う理由

デフォルトは、Spring と同じように動く最小のコードを生み出します。オプションは、ビルドだけでは決められない場合のためにあります。実行時にコードで追加されるアドバイス、常にスターターを通して到達されるライブラリ、--dart-define で設定されてはならないプロパティです。

オプション一覧

オプション 値 デフォルト 不正な値
aop_proxies all、interfaces、none all ArgumentError: Expected all, interfaces or none
aop_prune true、false true ArgumentError: Expected true or false
aop_defer true、false false ArgumentError: Expected true or false
dart_defines_exclude プロパティ名のプレフィックスのリスト [] ArgumentError (下記を参照)

不正な値は、ファイルが生成される前にビルドを失敗させます。

aop_proxies

どの Bean が生成された AOP プロキシクラスを受け取れるか。

値 意味
all クラスまたはそのインターフェースのいずれかを実装できるすべての Bean にプロキシクラス。継承しかできないクラスにはサブクラスプロキシ。
interfaces Bean の抽象スーパータイプを通したプロキシのみ。それを持たない Bean はプロキシを受け取りません。
none プロキシクラスなし。AOP はモジュールの Bean にアドバイスできません。

値は三つの名前のいずれかで、YAML ではテキストとして書きます。

aop_prune

true では、アプリケーションのすべてのアドバイスを知っている出力が、どのアドバイスも一致しえないプロキシクラスとプロキシのメンバーを省きます。

ライブラリパッケージの @ComponentScan モジュールは刈り込まれません。スターター (lib/spring_auto_configuration.dart を持つパッケージ) の lib/ のモジュールは、アプリケーションのアスペクトだけが一致しうるプロキシクラスをアプリケーションに任せ (AopProxyFactory.deferred)、アプリケーションはそのポイントカットが一致しうるものを書き出します。

false では、すべての Bean がすべてのメンバーを持つプロキシクラスを保ち、スターターは何も任せず、アプリケーションは任されたすべてのプロキシを書き出します。アドバイスが実行時にコードで登録される場合 (レジストラー、BeanFactoryPostProcessor、registerSingleton、Advised.addAdvisor) は false を使ってください。刈り込みが有効なままだと、その場合は起動が失敗し、その旨を伝えます。

詳しくは AOP プロキシ: 刈り込みと遅延 を参照してください。

aop_defer

true では、lib/spring_auto_configuration.dart を 持たない ライブラリパッケージの lib/ のモジュールが、スターターのモジュールと同じように、アプリケーションのアスペクトだけが一致しうるプロキシクラスをアプリケーションに任せます。これは、スターターの自動構成がモジュールをインポートし、アプリケーションのビルドがそれを通してモジュールを見つけるライブラリのためのものです (spring_boot_actuator が設定しています)。その他のライブラリは、どのモジュールからもインポートされうるため、デフォルトではすべてのプロキシを保ちます。

遅延には同じビルドで aop_prune: true が必要です。アプリケーションパッケージ (publish_to: none) ではこのオプションは何も変えません。そのモジュールは代わりに刈り込まれます。

dart_defines_exclude

@SpringBootApplication の出力は、アプリケーションが読みうるすべてのプロパティを springApplication.dartDefines に列挙し、--dart-define で設定できるようにします (--dart-define キー を参照)。dart_defines_exclude のプレフィックスの下のプロパティは、両方の形 (spring.flutter.theme.mode と SPRING_FLUTTER_THEME_MODE) ともそのリストから外されます。設定ファイル、環境変数、引数では引き続き設定できます。

targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          dart_defines_exclude:
            - spring.flutter.theme
            - spring.datasource

プレフィックスの読み方:

次のそれぞれは ArgumentError でビルドを失敗させます。

値 メッセージ
リストでない (dart_defines_exclude: spring.datasource) Expected a list of property name prefixes
文字列でないエントリー Expected a property name prefix (a string)
* を含むエントリー Wildcards are not supported: a prefix already covers every property under it (write spring.datasource, not spring.datasource.*)
空のエントリー Expected a property name prefix, not a blank entry
英字、数字、_ . - [ ] 以外の文字 Expected a property name prefix: letters, digits, _ . - [ and ]

完全な例

実行時にアドバイスを追加するアプリケーション

# アプリケーションの build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          # レジストラーがビルドから見えないアドバイザーを追加する:
          # すべてのプロキシクラスとすべてのメンバーを残す。
          aop_prune: false

テーマのプロパティを --dart-define から外す Flutter アプリ

# アプリケーションの build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          dart_defines_exclude: [spring.flutter.theme]

AOP をまったく必要としないモジュール

# パッケージの build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          aop_proxies: none

spring_properties ビルダー (手書きのスターター向け)

スターターのほとんどは手で書けますが、型付きの @ConfigurationProperties クラスのバインディングは生成するのが最善です。そこに問題が生じます。スターターの lib/ は生成ファイルをインポートし、スターターのサンプル (メインのビルダーがビルドする) は lib/ をインポートします。ビルダーは同じフェーズの別の入力が書き出すものを読めないため、サンプルのビルドからはそのファイルが見えません。

spring_properties ビルダーがこれを解決します。これは lib/ に限定されたメインのビルダーで、メインのビルダーより前に動く独自のフェーズに置かれます。パッケージが有効にしない限り無効で (auto_apply: none)、メインのビルダーと同じオプションを受け取ります。

典型的なスターターの build.yaml:

# スターター (spring_boot_starter_cache) の build.yaml
targets:
  $default:
    builders:
      # メインのビルダーはサンプルのアプリケーションだけを書き出す。
      spring_core_dart_generator:spring_core_dart:
        generate_for: [example/**]
      # 型付きプロパティのバインディング。メインのビルダーより前に動く。
      spring_core_dart_generator:spring_properties:
        enabled: true
        generate_for: [lib/src/config/**]
      spring_core_dart_generator:spring_test:
        enabled: false

スターターがインポートするライブラリで、aop_defer を使うもの (spring_boot_actuator から):

# 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_core_dart_generator:spring_test:
        enabled: false

オプションはビルダーごとに設定します。spring_core_dart に与えたオプションは spring_properties には適用されず、その逆も同じです。

enabled と generate_for は build_runner 自身のキーで、すべてのビルダーで使えます。パッケージのビルダーとそれらが書き出すものは ビルダー にあります。

関連項目