オプション
メインのビルダー 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 では、アプリケーションのすべてのアドバイスを知っている出力が、どのアドバイスも一致しえないプロキシクラスとプロキシのメンバーを省きます。
@SpringBootApplicationの出力。- アプリケーション (
pubspec.yamlにpublish_to: none) の@ComponentScanモジュール。外部からインポートされることはありません。
ライブラリパッケージの @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
プレフィックスの読み方:
- プレフィックスは、
.で区切られたセグメント単位で一致する、その下のすべてのプロパティを対象にします。spring.datasourceはspring.datasource.urlを対象にしますが、spring.datasourceishは対象にしません。 - 名前は緩いバインディングで、大文字小文字を区別せず、セグメント内の
-と_を無視して比較されます。spring.dataSource、spring.data-source、SPRING_DATASOURCEは同じプレフィックスです。 - 各エントリーは前後の空白が取り除かれ、末尾の
.や[は落とされます (spring.datasource.は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 自身のキーで、すべてのビルダーで使えます。パッケージのビルダーとそれらが書き出すものは ビルダー にあります。