
# ビルドから外されるモジュール

スターターは、自動構成モジュールの一つに `build: AutoConfigurationBuild('some.property')` を付けることができます。そうすると、アプリケーションの設定が、**`build_runner` の実行時に**、そのモジュールをそもそもアプリケーションの一部にするかどうかを決めます。

- `some.property: true`: モジュールはすべてのビルドに含まれます。
- `some.property: false`: モジュールはどのビルドにも含まれません。生成コードはそれに触れません。
- 未設定: スターターのデフォルト。スターターが別のことを言わない限り「デバッグとプロファイルのビルドに含め、リリースには含めない」です。

典型的な使い道は、`spring_boot_starter_flutter` のデバッグパネルのような、開発者だけが必要とする機能です。そうすると、リリースビルドにはそのコードが一切含まれません。

## 使う理由

実行時の条件 (`@ConditionalOnProperty`) は、アプリケーションの起動時に Bean を無効にします。それらの Bean のコード (クラス、ウィジェット、文字列) は、それでもアプリにコンパイルされます。デバッグパネルにとって、それはすべてのリリースでの無駄な重さであり、パネルに何ができるかをユーザーやリバースエンジニアに見せてしまいます。

ビルド条件は一段階早く働きます。生成されたアプリケーションがモジュールのコードをそもそも参照するかどうかを決めます。何も参照しないコードは Dart のコンパイラーが取り除く (ツリーシェイキング) ので、外されたモジュールは出荷されるアプリで何のコストにもなりません。

設計を形作った三つの目標:

- **シンプル。** スターターの作者にはアノテーションの引数が一つ、アプリケーションにはプロパティが一つ。呼ぶものもインポートするものもありません。
- **実際のビルドを決して遅くしない。** プロパティは、あるモジュールが `build:` を使う場合にだけ読まれ、プロキシのための追加の作業は、モジュールが実際に取り除かれる場合にだけ行われます。[ビルド時間のコスト](#ビルド時間のコスト) を参照してください。
- **無効にしたら痕跡なし。** `false` と判定されたモジュールは参照されず、(そのライブラリの他の何かが使われない限り) インポートされず、アプリケーションにプロキシクラスを持ちません。[生成コードの見た目](#生成コードの見た目) を参照してください。

## モジュールを宣言する (スターターの作者向け)

アノテーションは、他の自動構成モジュールと同じく、スターターの `lib/spring_auto_configuration.dart` のモジュール変数に付けます ([自動構成](../auto-configurations.md) を参照)。

```dart
// パッケージ `neon_inspector` の lib/spring_auto_configuration.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';
import 'spring_gen/src/inspector.spring.dart';

// すべてのアプリケーションが受け取るモジュール。
@AutoConfigurationModule()
final BeanModule neonInspectorAutoConfiguration = $neonInspectorBeans;

// 開発者ツール: `neon.inspector.enabled` で決まる。
// 未設定: デバッグとプロファイルのビルドだけ (デフォルトの whenMissing)。
@AutoConfigurationModule(
  build: AutoConfigurationBuild('neon.inspector.enabled'),
)
final BeanModule neonInspectorToolsAutoConfiguration = $neonInspectorToolsBeans;
```

`AutoConfigurationBuild` には二つのパラメーターがあります。

| パラメーター | 型 | デフォルト | 意味 |
|---|---|---|---|
| `property` (位置引数) | `String` | 必須 | 判定に使う、アプリケーションの設定のプロパティ。 |
| `whenMissing` | `BuildInclusion` | `BuildInclusion.notInRelease` | プロパティが設定されていないとき、モジュールをどこに含めるか。 |

`BuildInclusion` には三つの値があります。

| 値 | モジュールが含まれるもの |
|---|---|
| `BuildInclusion.always` | すべてのビルド |
| `BuildInclusion.notInRelease` | デバッグとプロファイルのビルド。リリースビルドではコンパイル時に取り除かれる |
| `BuildInclusion.never` | どのビルドにも含まれない |

`build:` を持つモジュールは `order`、`before`、`after` を保ち、他のモジュールは自身のそれらでそのモジュールを指定してもかまいません。

## プロパティを設定する (アプリケーション)

アプリケーションは、`lib/resources/` にある自身の設定ファイルでプロパティを設定します。

```yaml
# lib/resources/application.yml
neon:
  inspector:
    enabled: false   # このアプリのどのビルドにもインスペクターのコードを含めない
```

または

```properties
# lib/resources/application.properties
neon.inspector.enabled=true
```

その後、`dart run build_runner build` を実行します (または `watch` を動かしておきます)。`lib/resources/` の設定ファイルはビルドの入力なので、それを変更すると `build_runner` はアプリケーションの `.spring.dart` ファイルを書き直します。

### ビルドが読むもの

ビルドは、アプリケーションが設定を読むのと同じようにプロパティを読みますが、次の制限があります。

- `lib/resources/` の `application.yml`、`application.yaml`、`application.properties` を読みます (`lib/` の外のエントリーポイントでは、より近い `lib/resources/` フォルダーも読みます。[埋め込みリソース](../resources.md) を参照)。
- それらを **外部からのプロファイルなし** で読みます。プラットフォームのプロファイル (`web`、`ios` など) も、`--spring.profiles.active` 引数も、環境変数もありません。ファイル自身が有効にするプロファイル (`application.yml` に書かれた `spring.profiles.active: dev`) は、実行中のアプリケーションと同じく適用され、ビルドが読める `spring.config.import` のエントリーも適用されます。
- 環境変数も `--dart-define` の値も読みません。デフォルト付きの `${...}` プレースホルダーは動きます (`${INSPECTOR:true}` は `true`)。ビルドが解決できないプレースホルダーや、解析できないファイルはビルドを失敗させます。
- 値は前後の空白が取り除かれ、大文字小文字を区別せずに比較されます。`true`、` TRUE `、`True` はすべて `true` を意味します。

プロファイルのファイル (`application-dev.yml`、`application-web.properties`) でだけ設定された値は読まれません。ビルドはそれについて警告します ([警告](#警告) を参照)。

## 判定

`build:` を持つ各モジュールについて、ジェネレーターはプロパティを一度検索し、次のように判定します。

| プロパティ | モジュール | 警告 |
|---|---|---|
| `true` | 常に含まれる | なし |
| `false` | 決して含まれない | なし |
| 未設定、または空 | `whenMissing` のとおり (デフォルトは `notInRelease`) | なし。ただしプロファイルのファイルが設定している場合を除く |
| `application-<profile>.*` でだけ設定されている | `whenMissing` のとおり | あり: ビルドはプロファイルのファイルを読まない |
| その他の値 (`yes`、`1`、`off`) | `whenMissing` のとおり | あり: `true` でも `false` でもない |

「常に含まれる」と「決して含まれない」は、生成コードの中で確定します。「リリースには含まれない」は、以下で説明するとおり、Dart のコンパイラーがビルドモードから判定します。

## 生成コードの見た目

ジェネレーターは `@SpringBootApplication` の出力 (`main.spring.dart`。[アプリケーション](../spring-boot-application.md) を参照) を書き出します。その `springApplication` ゲッターが自動構成モジュールを列挙します。以下の例は `example/flutter_guide` の実際の出力から、インポートのプレフィックス (`_i67.`) だけを外したものです。

### `true`、または `whenMissing: always`

モジュールは他のものと同じように列挙されます。

```dart
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    springBootAutoConfiguration,
    springBootStarterFlutterAutoConfiguration,
    springBootStarterFlutterDebugAutoConfiguration,
    springBootStarterFlutterNavigationAutoConfiguration,
    // ...
  ],
  // ...
);
```

### `false`、または `whenMissing: never`

モジュールはリストにありません。ファイルの他の場所もそれに触れません。

```dart
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    springBootAutoConfiguration,
    springBootStarterFlutterAutoConfiguration,
    springBootStarterFlutterNavigationAutoConfiguration,
    // ...
  ],
  // ...
);
```

スターターの `spring_auto_configuration.dart` の他の何も使われない場合は、そのライブラリのインポートもなくなります。ジェネレーターのテストは、`false` の出力に、モジュールへの参照、その Bean のプロキシクラス、それらの `source` 文字列、スターターのインポートがないことをチェックしています (`library_proxies_test.dart`)。

### 未設定、デフォルトの `whenMissing: notInRelease`

モジュールはコレクション `if` の下に列挙されます。

```dart
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    springBootAutoConfiguration,
    springBootStarterCacheAutoConfiguration,
    springBootStarterFeignAutoConfiguration,
    springBootStarterFlutterAutoConfiguration,
    if (!const bool.fromEnvironment('dart.vm.product'))
      springBootStarterFlutterDebugAutoConfiguration,
    springBootStarterFlutterNavigationAutoConfiguration,
    // ...
  ],
  // ...
);
```

そのようなモジュールが `order`、`before`、`after` を持つとき、`autoConfigurationMetadata` のそのエントリーは同じ `if` の下にあるので、順序付けはモジュールと一緒にリリースから外れます。

## リリースでコンパイラーが取り除くものと、その理由

`dart.vm.product` はコンパイル時の環境定数です。Flutter は `flutter build --release` でそれを `true` に、デバッグとプロファイルのビルドでは `false` に設定します (Flutter の `kReleaseMode` は同じ定数です)。`dart compile exe` も `true` に設定しますが、`dart run` は設定しません。

`dart.vm.product` が `true` のとき、コンパイラーは `!const bool.fromEnvironment('dart.vm.product')` を定数 `false` と見なします。順を追うと:

1. コレクション `if` の条件が定数 `false` なので、要素はリストから落とされます。
2. するとモジュール変数 (`springBootStarterFlutterDebugAutoConfiguration`) はどこからも参照されなくなります。
3. ツリーシェイキングは、どこからも参照されないものを取り除きます。変数、その Bean 定義、それらの `create` クロージャー、そしてそれらを通してだけ到達できるすべてのクラス、ウィジェット、文字列です。
4. デバッグとプロファイルのビルドでは条件は `true` です。要素はリストにあり、モジュールは通常どおり動きます。

これは実際のビルドで確認されています。デバッグパネルを持つアプリのリリースの Web ビルドにはパネルの文字列が一切含まれず、プロファイルビルドには含まれます。`dart compile js -Ddart.vm.product=true` と `dart compile exe` でコンパイルした小さなプログラムでも同じで、そのような `if` を通してだけ到達できる文字列は出力に含まれません。

コンパイラーが何を取り除けるかは、他に何がそのコードを参照しているかによります。モジュールが使うクラスをアプリケーションが別の場所でも使っていれば、別の経路で到達できるので残ります。

## モジュールの Bean のプロキシ

スターターの生成されたモジュールは、その Bean の AOP プロキシクラスを含みません。`AopProxyFactory.deferred` のプレースホルダーでアプリケーションに任せ、アプリケーションのビルドがそのアスペクトが必要とするプロキシクラスを書き出します ([AOP プロキシ](aop-proxies.md) を参照)。これらのプロキシは、そのモジュールのビルドに従います。

| Bean を定義するもの | アプリケーションでのそのプロキシ |
|---|---|
| `never` と判定されたモジュールだけ | 書き出されない: プロキシクラスなし、`aopProxies` のエントリーなし、Bean のライブラリのインポートなし |
| `notInRelease` と判定されたモジュールだけ (または `never` と `notInRelease`) | 同じ `if` の下に登録されるので、リリースではコンパイル時に取り除かれる |
| 一つのプラットフォームだけのモジュールだけ ([一つのプラットフォームだけのモジュール](#一つのプラットフォームだけのモジュール) を参照) | そのプラットフォームの `if` の下に登録される |
| 常に含まれるモジュールが一つ以上 | 通常どおり書き出される |

`notInRelease` のモジュールにだけある Bean では、アプリケーションのモジュールは次のようになります (ジェネレーターのテストから。プレフィックスは外し、ファクトリーの引数は短縮しています)。

```dart
BeanModule get $application => BeanModule(
  r'application',
  [
    // アプリケーションの Bean
  ],
  aopProxies: {
    if (!const bool.fromEnvironment('dart.vm.product'))
      r'package:starter/task.dart#Task': AopProxyFactory(
        signatures: const [/* ... */],
        create: (target, invoker) => _$TaskProxy(target as Task, invoker),
      ),
  },
);
```

クラス `_$TaskProxy` はそのエントリーからだけ参照されるので、リリースではそれと一緒に取り除かれます。

## 一つのプラットフォームだけのモジュール

モジュールは、同じアノテーションの `platform:` で、そのコードが動くプラットフォームだけに留めることもできます。

```dart
// スターターのサーバー側の半分: サーバーが動ける場所でだけ。
@AutoConfigurationModule(platform: ModulePlatform.native)
final BeanModule neonInspectorServerAutoConfiguration = $neonInspectorServerBeans;
```

| `ModulePlatform` | モジュールが含まれるもの | 生成コードでの条件 |
|---|---|---|
| `native` | `dart:io` が存在するビルド: Dart VM、AOT 実行ファイル、スマートフォンやデスクトップの Flutter アプリ | `const bool.fromEnvironment('dart.library.io') \|\| const bool.fromEnvironment('SPRING_ALL_PLATFORMS')` |
| `web` | ブラウザービルド。JavaScript または WebAssembly | `const bool.fromEnvironment('dart.library.js_interop') \|\| const bool.fromEnvironment('SPRING_ALL_PLATFORMS')` |
| `server` | Dart VM と AOT 実行ファイル: `dart:io` が存在し、Flutter の `dart:ui` は存在しない。Flutter アプリではなく、ブラウザーでもない | `(const bool.fromEnvironment('dart.library.io') && !const bool.fromEnvironment('dart.library.ui')) \|\| const bool.fromEnvironment('SPRING_ALL_PLATFORMS')` |

プロパティは読まれません。プラットフォームはアプリケーションが選ぶものではないからです。ジェネレーターはモジュールを定数の下に列挙し、それぞれのコンパイラーが自分のプラットフォームについて判定します。以下は `example/server_guide` の実際の出力から、インポートのプレフィックスを外したものです。

```dart
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    springBootAutoConfiguration,
    springBootStarterCacheAutoConfiguration,
    springBootStarterFeignAutoConfiguration,
    springBootStarterLoggingAutoConfiguration,
    springBootStarterOauth2ClientAutoConfiguration,
    springBootStarterSchedulingAutoConfiguration,
    if ((const bool.fromEnvironment('dart.library.io') ||
        const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))
      springBootStarterSecurityAutoConfiguration,
    if ((const bool.fromEnvironment('dart.library.io') ||
        const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))
      springBootStarterSecurityOAuth2ClientAutoConfiguration,
    if ((const bool.fromEnvironment('dart.library.io') ||
        const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))
      springBootStarterWebAutoConfiguration,
    springBootStarterWebsocketAutoConfiguration,
    if ((const bool.fromEnvironment('dart.library.io') ||
        const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))
      springBootStarterWebsocketServerAutoConfiguration,
    springSecurityCoreAutoConfiguration,
  ],
  autoConfigurationMetadata: {
    if ((const bool.fromEnvironment('dart.library.io') ||
        const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))
      springBootStarterSecurityAutoConfiguration:
          const AutoConfigurationModule(
            after: ['springBootStarterOauth2ClientAutoConfiguration'],
          ),
    // ...
  },
  // ...
);
```

サーバーでは `dart.library.io` は `true` で、すべてのモジュールが含まれます。ブラウザー向けにコンパイルすると `false` です。要素は落とされ、モジュール変数はどこからも参照されなくなり、ツリーシェイキングが、それらだけが到達するすべてのクラスと一緒に取り除きます。リリースについての [上記](#リリースでコンパイラーが取り除くものとその理由) と同じです。そのため、同じ生成ファイルが両方のプラットフォームで使え、依存関係が Web スターターを持ち込む Flutter の Web アプリはサーバーを持ちません。

意図して別のプラットフォームでサーバーのモジュールを動かすプログラム（たとえばリポジトリの、サーバーのコードをミニファイした JavaScript として Node で確かめるチェック）は、`-DSPRING_ALL_PLATFORMS=true` を付けてコンパイルします。すべてのモジュールが残ります。

ルール:

- **`build:` があれば、両方の条件が成り立つ必要があります。** ビルドプロパティが未設定で `platform: ModulePlatform.native` を持つモジュールは、`if (!const bool.fromEnvironment('dart.vm.product') && (const bool.fromEnvironment('dart.library.io') || const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))` の下に列挙されます。ビルドプロパティが `false` (または `never`) と判定されると、プラットフォームが何であってもモジュールは外されます。
- **順序は残ります。** `autoConfigurationMetadata` のモジュールのエントリーは、上の出力のとおり、同じ `if` の下にあります。
- **プロキシは従います。** そのようなモジュールだけが定義する Bean のプロキシは同じ条件の下に登録されるので、モジュールと一緒にもう一方のプラットフォームのビルドから外れます。
- **実行時の条件ではありません。** 起動時にスキップされる Bean はありません。もう一方のプラットフォームでは、コードがそこにありません。

### どのモジュールに指定があるか

ファミリーのすべての自動構成モジュールと、それが含まれる場所:

| パッケージ | モジュール | プラットフォーム | ビルドプロパティ |
|---|---|---|---|
| `spring_boot_dart` | `springBootAutoConfiguration` | すべて | |
| | `springBootObservedAnnotationsAutoConfiguration` | すべて | `spring.observations.annotations.enabled` (未設定: 含めない) |
| `spring_boot_starter_logging` | `springBootStarterLoggingAutoConfiguration` | すべて | |
| `spring_boot_starter_scheduling` | `springBootStarterSchedulingAutoConfiguration` | すべて | |
| `spring_boot_starter_cache` | `springBootStarterCacheAutoConfiguration` | すべて | |
| | `springBootStarterCacheStartupChecksAutoConfiguration` (`cacheOperationValidator`) | すべて | `spring.main.startup-checks.enabled` |
| `spring_boot_starter_feign` | `springBootStarterFeignAutoConfiguration` | すべて | |
| `spring_boot_starter_data` | `springBootStarterDataAutoConfiguration` | すべて | |
| | `springBootStarterDataStartupChecksAutoConfiguration` (`transactionValidator`、`dataFailureAnalyzer`) | すべて | `spring.main.startup-checks.enabled` |
| | `springBootStarterDataSqlLoggingAutoConfiguration` (文のログ、`jdbcLogSettings`) | すべて | `spring.data.jdbc.show-sql` |
| `spring_boot_starter_oauth2_client` | `springBootStarterOauth2ClientAutoConfiguration` | すべて | |
| `spring_boot_starter_edge` | `springBootStarterEdgeAutoConfiguration` (fetch サーバー、ランタイム) | すべて | |
| | `springBootStarterEdgeStartupChecksAutoConfiguration` (`edgeWarnings`) | すべて | `spring.main.startup-checks.enabled` |
| `spring_security_core` | `springSecurityCoreAutoConfiguration` | すべて | |
| `spring_search_dart` | `springSearchDartAutoConfiguration` | すべて | |
| `spring_boot_starter_websocket` | `springBootStarterWebsocketAutoConfiguration` (クライアント) | すべて | |
| | `springBootStarterWebsocketServerAutoConfiguration` (サーバーのエンドポイント) | **native** | |
| `spring_boot_starter_supabase` | `springBootStarterSupabaseDataAutoConfiguration` (データストアのデフォルト) | すべて | |
| | `springBootStarterSupabaseAutoConfiguration` (Bean) | すべて | |
| | `springBootStarterSupabaseAdminAutoConfiguration` (`supabaseAuthAdmin`) | **server** | |
| | `springBootStarterSupabaseServerAutoConfiguration` (リソースサーバーのデフォルト) | **server** | |
| `spring_boot_starter_web` | `springBootStarterWebAutoConfiguration` | **native** | |
| | `springBootStarterWebRateLimitAutoConfiguration` (レートリミッター) | **native** | |
| | `springBootStarterWebDebugQpsAutoConfiguration` | **native** | `spring.web.debug.qps.enabled` (未設定: 含めない) |
| `spring_boot_starter_security` | `springBootStarterSecurityAutoConfiguration` | **native** | |
| | `springBootStarterSecurityOAuth2ClientAutoConfiguration` | **native** | |
| `spring_boot_starter_actuator` | `springBootStarterActuatorAutoConfiguration` | **native** | |
| | `springBootStarterActuatorQpsAutoConfiguration` | **native** | `spring.web.debug.qps.enabled` (未設定: 含めない) |
| `spring_boot_starter_flutter` | `springBootStarterFlutterAutoConfiguration` | すべて | |
| | `springBootStarterFlutterDebugAutoConfiguration` | すべて | `spring.flutter.debug.enabled` |
| | `springBootStarterFlutterDebugFrameMeterAutoConfiguration` | すべて | `spring.flutter.debug.frame-meter.enabled` |
| | `springBootStarterFlutterDebugMotionAutoConfiguration` | すべて | `spring.flutter.debug.motion.enabled` |
| | `springBootStarterFlutterDebugTimelineAutoConfiguration` | すべて | `spring.flutter.debug.timeline.enabled` |
| | `springBootStarterFlutterDebugIsolatesAutoConfiguration` | すべて | `spring.flutter.debug.isolates.enabled` |
| | `springBootStarterFlutterDebugDragAutoConfiguration` | すべて | `spring.flutter.debug.drag.enabled` (未設定: 含めない) |
| `spring_boot_starter_flutter_scene` | `springBootStarterFlutterSceneAutoConfiguration` | すべて | `spring.flutter.scene.enabled` (未設定: 含める) |
| | `springBootStarterFlutterSceneDebugAutoConfiguration` (デバッグパネルのシーンのタブ) | すべて | `spring.flutter.scene.debug.enabled` |
| `spring_boot_starter_flutter_signals` | `springBootStarterFlutterSignalsAutoConfiguration` | すべて | |
| | `springBootStarterFlutterSignalsDebugAutoConfiguration` (デバッグパネルの状態のタブ) | すべて | `spring.flutter.signals.debug.enabled` |
| `spring_boot_starter_flutter_material` | `springBootStarterFlutterMaterialAutoConfiguration` | すべて | |
| `spring_boot_starter_flutter_cupertino` | `springBootStarterFlutterCupertinoAutoConfiguration` | すべて | |
| `spring_boot_starter_flutter_navigation` | `springBootStarterFlutterNavigationAutoConfiguration` | すべて | |
| `spring_boot_starter_flutter_security` | `springBootStarterFlutterSecurityAutoConfiguration` | すべて | |

注記のないビルドプロパティは、未設定のとき「リリースには含まれない」です。データ、キャッシュ、edge の各スターターの起動チェックのモジュールは `spring.main.startup-checks.enabled` を共有します。一つのキーで三つとも外せます。データスターターの SQL 文のログは独立したモジュールで、`spring.data.jdbc.show-sql` で決まります。各スターターのページ「ビルドに含まれるもの」は、そのスターター自身のモジュールと、ジェネレーターがそのために書くものを挙げています。たとえば [データスターターのページ](../../spring-boot-starter-data/optimizations.md) です。

`native` なのは、サーブするものです。Web サーバー、そのセキュリティ、その上の Actuator のエンドポイント、WebSocket のサーバーのエンドポイントです。`server` は、アプリに入れてはならない、つまり誰でも読めるものに入れてはならないコードのためのものです。サービスロールキーを使う Supabase スターターの管理 API と、リソースサーバーのデフォルトです。Flutter アプリ (スマートフォン、デスクトップ、Web) はどちらも持ちません。ファミリーに `web` だけのモジュールはありません。どこにでも含まれるモジュールは、プラットフォーム固有の部分を条件付きインポートで自分で選びます。WebSocket のトランスポート、タスクエグゼキューター、Flutter セキュリティスターターのシークレットストアです。

ブラウザーアプリの依存関係であるパッケージは、それでもブラウザーでコンパイルできなければなりません。`platform:` はモジュールをプログラムから取り除きますが、ブラウザー向けにまったくコンパイルできないライブラリを許すものではありません。[WebAssembly](../../../docs/webassembly.md) を参照してください。

## キーで決まるジェネレーターのパート

パッケージのジェネレーターのパート ([パッケージのパート](../how-it-works.md#パッケージのパート) を参照) も、同じようにキーに従えます。`PackageBuild('some.property', whenMissing: ...)` は `AutoConfigurationBuild` と同じように読まれます。そうすると、一つのキーで、パッケージのモジュールと、ジェネレーターがそのために書くものすべてを外せます。

- `true`: パートはキーのないパートと同じように動きます。
- `false`: パートは動かず、その生成物は何もありません。
- 未設定で `BuildInclusion.notInRelease` (デフォルト): パートが書くもの (Bean 定義、モジュールの文、イントロスペクションのリスト、リソース) は `if (!const bool.fromEnvironment('dart.vm.product'))` の下に置かれます。パートのクラスとトップレベルの宣言は条件の下に置けませんが、何も使わなければリリースビルドが捨てます。

組み込みのパートでキーを取るものはまだなく、パートに分けたことで、例の生成コードは変わっていません。

## すべてのビルドに残るもの

意図して、またはまだ切り替えられないコードがあります。

- **`spring_security_core` の `methodSecurityValidator`** は、意図してすべてのビルドに残ります。プロキシのないまま残った保護された Bean で起動を止める、セキュリティの安全網だからです。
- **データスターターの遅いクエリのログ** (`jdbcSlowQueryLogSettings`) はメインのモジュールにあり、遅い文はすべてのビルドで warn で記録されます。切り替えられるのは、`spring.data.jdbc.show-sql` の文のログだけです。
- **データスターターのスキーマのステップ** (`create`、`validate`) と **メモリ上のストア** はメインのモジュールにあり、まだ切り替えられません。

## JavaScript や WebAssembly にコンパイルするとき

`dart compile js` と `dart compile wasm` は `dart.vm.product` を定義しないので、その出力は `notInRelease` の意味でのリリースビルドではありません。edge function は、キーが `false` でない限り、`notInRelease` のモジュール (edge スターターの警告の一覧など) を残します。Flutter のリリースビルドと AOT 実行ファイル (`dart compile exe`) はそれらを外します。

## 警告

ビルド条件がビルドを失敗させるのは、ビルドがプロパティを読めない場合だけです。環境変数や `--dart-define` だけが解決するデフォルトなしの `${...}` プレースホルダー、または解析できない設定ファイルです。エラーはモジュールとプロパティを示し、修正方法を伝えます。

```text
neon_inspector.neonInspectorToolsAutoConfiguration: the build reads
neon.inspector.enabled to decide whether the module is built, and could not:
PlaceholderResolutionException: Could not resolve placeholder 'FLAG' in value
"${FLAG}"
Give neon.inspector.enabled a value the build can read in application.yml or
application.properties, or a placeholder with a default (${FLAG:true}):
environment variables and --dart-define values do not exist at build time.
```

それ以外の場合は、モジュールを `<package>.<variable>` として示して警告します。

**プロパティがプロファイルのファイルでだけ設定されている。**

```text
neon_inspector.neonInspectorToolsAutoConfiguration: neon.inspector.enabled is
set only in application-dev.yml, which the build does not read: it decides by
application.yml or application.properties without a profile. The module is
built as when it is not set.
```

設定を `application.yml` か `application.properties` に移すか、実行時のスイッチとしてプロファイルのファイルに残します (次の節を参照)。

**値が `true` でも `false` でもない。**

```text
neon_inspector.neonInspectorToolsAutoConfiguration: neon.inspector.enabled is
'yes', not true or false; the module is built as when it is not set.
```

## ビルド条件と実行時の条件

二種類の条件は異なる仕事をし、一緒に働きます。

| | ビルド条件 (`build:`) | 実行時の条件 (`@ConditionalOnProperty`、`@Profile` など) |
|---|---|---|
| 決めるもの | モジュールのコードがアプリに存在するかどうか | アプリの起動時に Bean が登録されるかどうか |
| 評価される時 | `build_runner` の実行時、そして `notInRelease` ではコンパイラーによって | 起動のたび |
| 読むもの | 外部のプロファイルなしの `application.yml` / `application.properties` | 実行中のアプリのすべてのプロパティソース: プロファイル、環境変数、引数、`--dart-define` |
| アプリのサイズへの効果 | コードを取り除く | なし: コードはコンパイルに含まれる |
| もう一方が無効にしたものを有効にできるか | できない | できない |

つまり、ビルド条件はコードを取り除くことができ、コードが存在する場所では実行時の条件が引き続きその Bean を無効にできます。逆は不可能です。ビルドが外したモジュールを実行時のプロパティで呼び戻すことはできません。そのコードがそこにないからです。

両方を望むスターターは、デバッグパネルと同じく両方を宣言します。モジュールに `build:` を付け、その Bean に同じプロパティで `matchIfMissing: true` の `@ConditionalOnProperty` を付けます。

## 実例: デバッグパネル

`spring_boot_starter_flutter` はデバッグパネルを次のように宣言しています (短縮)。

```dart
// spring_boot_starter_flutter/lib/spring_auto_configuration.dart

// 実行中のアプリのパネル: ビルドに含まれていても、プロファイルの
// spring.flutter.debug.enabled=false で無効になる。
const _debugOn = ConditionalOnProperty(
  'spring.flutter.debug.enabled',
  havingValue: 'true',
  matchIfMissing: true,
);

@AutoConfigurationModule(
  build: AutoConfigurationBuild('spring.flutter.debug.enabled'),
)
final BeanModule springBootStarterFlutterDebugAutoConfiguration = BeanModule(
  'springBootStarterFlutterDebugAutoConfiguration',
  [
    BeanDefinition<DebugPanel>(
      name: 'debugPanel',
      conditions: const [_debugOn],
      create: (_) => DebugPanel(),
      // ...
    ),
    // セクション: ログ、フレーム、設定、Bean、テーマ、起動。
    // そしてパネルをアプリの上に置く debugPanelCustomizer
  ],
);
```

`application.yml` (または `application.properties`) の `spring.flutter.debug.enabled` の値によって、アプリが受け取るもの:

| `spring.flutter.debug.enabled` | デバッグとプロファイルのビルド | リリースビルド |
|---|---|---|
| 未設定 | パネルのコードが含まれる。実行中のアプリが `false` を読まない限り (プロファイルのファイル、引数)、パネルは有効 | コードなし |
| `true` | コードが含まれる。実行中のアプリが `false` を読まない限り、パネルは有効 | コードが含まれる。実行中のアプリが `false` を読まない限り、パネルは有効 |
| `false` | コードなし | コードなし |

ほとんどのアプリは何も設定しません。開発者はパネルを得て、ユーザーには決して出荷されません。リリースビルドに残すには `true` を (社内テスト用のビルド)、どのビルドにも含めないには `false` を設定します。

## ビルド時間のコスト

ビルド条件がビルドに加えるものはほとんどなく、スターターがそれを使わないアプリケーションには何も加えません。

- **設定は遅延して一度だけ読まれます。** `lib/resources/` のファイルは、すべてのアプリケーションですでに読まれています (埋め込まれるからです。[埋め込みリソース](../resources.md) を参照)。それらが環境に解析されるのは、`build:` を持つ最初のモジュールのときだけで、その環境は同じビルドステップの他のモジュールのために保持されます。そのようなモジュールがなければ、プロパティの検索は一度も行われません。
- **プロファイルのファイルは必要なときだけ見られます。** `application-<profile>.*` でだけ設定された値のチェックは、プロパティが設定されていない場合にだけ行われます。
- **モジュールのコードは、何かが取り除かれるときだけたどられます。** どのプロキシがモジュールと一緒に外れるかを知るため、ジェネレーターはモジュールの宣言と、それが読むトップレベル変数とゲッターをたどり、`AopProxyFactory.deferred` の Bean を探します。それを行うのは、モジュールが `never` または `notInRelease` と判定された場合だけです。常に含まれるモジュールをたどるのは、取り除かれたモジュールがそのような Bean を一つ以上定義する場合だけで、たどった宣言はそれぞれ記憶されます。

## テストされていること

ジェネレーターのテストは、偽のスターターに対してアプリケーションをビルドし、生成コードをチェックします。

- `starter_compatibility_test.dart`: `true` はモジュールを列挙し、`dart.vm.product` を書かない。`false` はモジュールの何も書かない。未設定は `if (!const bool.fromEnvironment('dart.vm.product'))` の要素を書く。`whenMissing: BuildInclusion.never` は何も書かない。`application-web.yml` (入れ子またはドット区切りの YAML) や `application-web.properties` でだけ設定された値は警告し、未設定としてビルドする。プロファイルなしで設定された値は警告しない。
- `starter_compatibility_test.dart`、`platform:` について: `native` はモジュールを `dart.library.io` の下に、`web` は `dart.library.js_interop` の下に列挙し、`dart.vm.product` は書かない。ビルドプロパティが未設定なら両方の条件が結合される。プロパティが `false` ならモジュールは書かれない。`order` は残り、そのエントリーは同じ条件の下にある。
- `library_proxies_test.dart`: 遅延されたプロキシを持つ Bean について、`false` はプロキシクラス、`source`、スターターのインポート、モジュールを残さない。未設定は `if` の下にプロキシを登録する。`true` はそのまま登録する。常に含まれるモジュールにも Bean がある場合の `false` はプロキシを保つ。

## 関連項目

- [自動構成](../auto-configurations.md)
- [AOP プロキシ: 刈り込みと遅延](aop-proxies.md)
- [ビルドが読むプロパティ](../build-properties.md)
- [最適化の概要](index.md)
- [条件](../../spring-core-dart/beans/conditional.md)
- [プロファイル](../../spring-core-dart/config/profiles.md)
