
# オプション

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

```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 プロキシ: 刈り込みと遅延](optimizations/aop-proxies.md) を参照してください。

### `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.md) を参照)。`dart_defines_exclude` のプレフィックスの下のプロパティは、両方の形 (`spring.flutter.theme.mode` と `SPRING_FLUTTER_THEME_MODE`) ともそのリストから外されます。設定ファイル、環境変数、引数では引き続き設定できます。

```yaml
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 ]` |

## 完全な例

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

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

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

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

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

```yaml
# パッケージの 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`:

```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` から):

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

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

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

## 関連項目

- [ビルダー](builders.md)
- [AOP プロキシ: 刈り込みと遅延](optimizations/aop-proxies.md)
- [--dart-define キー](dart-defines.md)
- [ビルドが読むプロパティ](build-properties.md)
