
# 自動構成とスターター

スターターとは、出来上がった Bean を持ち込むライブラリです。`pubspec.yaml` に追加して `build_runner` を実行すれば、自分でコードを書かなくてもその機能が使えます。スターターはそれらを*自動構成*として提供します。アプリケーション自身の Bean の後に登録され、[条件](conditions.md) で守られているため、自分の Bean が常に優先されます。

## 使う理由

Web サーバー、キャッシュ、ロギングの設定には、正しく結び付けた十数個の Bean が必要です。それをアプリケーションごとに書くのは繰り返しが多く、間違いやすい作業です。自動構成なら、ライブラリがそれを一度だけ書き、各アプリケーションは必要なものだけを上書きします。独自の `Cache` Bean を宣言すれば、スターターの `@ConditionalOnMissingBean(Cache)` が身を引きます。

## 例

スターター `neon_cache`:

```dart
// パッケージ neon_cache の lib/spring_auto_configuration.dart (ファイル名は固定)
import 'package:spring_boot_dart/spring_boot_dart.dart';

import 'spring_gen/src/cache.spring.dart';

@AutoConfigurationModule(requires: '^0.7.0')
final BeanModule neonCacheAutoConfiguration = $neonCacheBeans;
```

```dart
// neon_cache の lib/src/cache.dart
@AutoConfiguration()
class CacheAutoConfiguration {
  @Bean()
  @ConditionalOnMissingBean(Cache)                       // アプリケーション自身の Cache が優先される
  @ConditionalOnProperty('neon.cache.enabled', matchIfMissing: true)
  Cache cache(@Value(r'${neon.cache.size:100}') int size) => InMemoryCache(size);
}
```

`neon_cache` に依存するアプリケーションは、コードなしで `Cache` Bean を得ます。独自のものを宣言するアプリケーションは、自分のものだけを得ます。

```dart
// アプリケーションの Bean: スターターの cache() は登録されない。
@Bean()
Cache cache() => RedisCache();
```

## スターターの見つけ方

`@SpringBootApplication()` を持つアプリケーションをビルドすると、ジェネレーターは依存関係グラフのすべてのパッケージ (直接のものと推移的なもの) をたどり、`lib/spring_auto_configuration.dart` があればそれを読み、アノテーションの付いたモジュールを生成される `springApplication` に列挙します。

```dart
// アプリケーションの bin/spring_gen/main.spring.dart (生成されたもの)
SpringApplication get springApplication => SpringApplication(
      [$application],
      autoConfigurations: [
        neonCacheAutoConfiguration,   // neon_cache で見つかったもの
        springBootAutoConfiguration,  // spring_boot_dart
      ],
      // スターターが order、before、after、factories を設定している場合のみ
      autoConfigurationMetadata: {
        neonCacheAutoConfiguration: AutoConfigurationModule(order: 10),
      },
    );
```

- 検出は、起動時にクラスパスをスキャンするのではなく、ビルド時に行われます。スターターを追加したら、`build_runner` を再実行してください。
- モジュールを検出するのは `@SpringBootApplication` のアプリケーションだけです。コンテキストを手で生成するアプリケーションは、モジュールを自分で列挙します。

## @AutoConfigurationModule

`lib/spring_auto_configuration.dart` の public なトップレベルの `BeanModule` 変数に付けます。

| パラメーター | デフォルト | 意味 |
|---|---|---|
| `order` | `0` | モジュール間での位置。小さいものが先 (Spring Boot の `@AutoConfigureOrder`) |
| `before` | `[]` | このモジュールの後に登録しなければならないモジュール、または短い名前で指定した `@AutoConfiguration` クラス |
| `after` | `[]` | このモジュールの前に登録しなければならないモジュールまたはクラス: `['springBootAutoConfiguration']` |
| `requires` | `null`: 任意 | スターターが動作する `spring_boot_dart` のバージョン。pub の範囲で指定する (`^0.7.0`)。一致しないとビルドが止まる ([バージョン](compatibility.md) を参照) |
| `build` | `null`: 常に | `AutoConfigurationBuild`: アプリケーションの設定のプロパティが、そもそもモジュールをビルドに含めるかどうかを決める |
| `platform` | `null`: どこでも | `ModulePlatform`: `native`、`web`、`server` のいずれか。ほかのプラットフォームでは、コンパイラーがモジュールと、そのモジュールだけが到達するすべてを取り除く |
| `factories` | `[]` | Bean が一つも存在しないうちに、アプリケーションが型で見つける定数。[ファクトリー](#ファクトリー) を参照 |

`@AutoConfiguration()` はスターターの構成クラスを示します。`@Configuration` の一種で、その `@Bean` メソッドは自動構成として登録されます。

## 登録の順序

1. 最初にアプリケーション自身のクラス。
2. 自動構成モジュール。Spring Boot の `AutoConfigurationSorter` と同じく並べ替えます。`order` で並べ、同じ順序のモジュールは名前で並べ、その後 `before` と `after` で移動します。循環があると `AutoConfigure cycle detected between ...` で起動が止まります。不明な名前は無視されます。

```dart
@AutoConfigurationModule(
  order: 10,
  after: ['springBootAutoConfiguration'],    // モジュールまたは @AutoConfiguration クラス
  before: ['neonMetricsAutoConfiguration'],
)
final BeanModule neonCacheAutoConfiguration = $neonCacheBeans;
```

Bean の条件はその順序でクラスごとに判断されるため、`@ConditionalOnMissingBean` は、アプリケーションが宣言したもの (`@Import` したレジストラーの Bean を含む) を認識します。[条件](conditions.md#bean-の条件が判断されるタイミング) を参照してください。

## 自動構成を除外する

スターターの Bean が不要な場合は、その条件が実行される前に除外します。

```dart
@SpringBootApplication(
  exclude: [CacheAutoConfiguration],                     // クラスで
  excludeName: ['springBootStarterCacheAutoConfiguration'], // モジュール名またはクラス名で
)
void main(List<String> args) => runApplication(args);
```

```properties
# 実行時にアノテーションに追加される: カンマ区切りのリストまたは YAML のリスト
spring.autoconfigure.exclude=JacksonAutoConfiguration,CacheAutoConfiguration
```

- `exclude` の `Type` は単純名で比較されるため、別々のライブラリにある同じ名前のクラスはまとめて除外されます。
- `excludeName` とプロパティは、モジュール名 (`springBootAutoConfiguration`)、短いクラス名、または `package:x/src/y.dart#CacheAutoConfiguration` を受け取ります。
- クラスを除外すると、その Bean、インポートしたレジストラーとセレクター、条件付きの `@PropertySource` が取り除かれます。それが `@Import` する構成クラスは残ります。モジュールを除外すると、そのすべてが取り除かれます。
- 自動構成でない型を除外すると起動が止まります。不明な名前は無視されます。

組み込みのものは `JacksonAutoConfiguration`、`ValidationAutoConfiguration`、`MessageSourceAutoConfiguration`、`LifecycleAutoConfiguration`、`ApplicationAvailabilityAutoConfiguration`、`JsonSchemaAutoConfiguration`、`ObservationAutoConfiguration` です ([組み込みの Bean](built-in-beans.md) を参照)。

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

開発者だけが使う機能 (デバッグパネル) は、リリースに含めるべきではありません。`build:` を使うと、ジェネレーターの実行時に、アプリケーションの設定がそもそもモジュールをアプリケーションに含めるかどうかを決められます。

```dart
@AutoConfigurationModule(
  build: AutoConfigurationBuild('spring.flutter.debug.enabled'),
)
final BeanModule debugAutoConfiguration = BeanModule(/* ... */);
```

プロパティは、`build_runner` の実行時に、プロファイルなしの `application.yml` と `application.properties` から読まれます。

| プロパティ | モジュール |
|---|---|
| `true` | すべてのビルドに含まれる |
| `false` | どのビルドにも含まれない: コードはまったくない |
| 未設定 | `whenMissing` |

`whenMissing` は `BuildInclusion` です。

| 値 | 意味 |
|---|---|
| `notInRelease` (デフォルト) | debug と profile のビルドに含まれる。リリースではコンパイル時に取り除かれる (`dart.vm.product`) |
| `always` | すべてのビルドに含まれる |
| `never` | どのビルドにも含まれない |

ビルドが条件付きで含めるモジュールも、その `order`、`before`、`after` を保ちます。ビルドはプロファイルのファイルを読まないため、プロファイルのファイルでだけ設定されたビルドプロパティには警告が出ます。[ビルドから除かれるモジュール](../spring-core-dart-generator/optimizations/build-conditions.md) を参照してください。

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

一つのプラットフォームでしか動かないコードがあります。Web サーバーには `dart:io` が必要ですが、ブラウザーにはありません。`dart:js_interop` を通してブラウザーに到達するコードは、サーバーでは動きません。`platform:` は、モジュールをそのコードが動く場所に限定します。

```dart
@AutoConfigurationModule(platform: ModulePlatform.native)
final BeanModule neonServerAutoConfiguration = BeanModule(/* ... */);
```

| `ModulePlatform` | モジュールがある場所 |
|---|---|
| `native` | `dart:io` が存在する場所: Dart VM、AOT 実行ファイル、スマートフォンやデスクトップの Flutter アプリ。ブラウザーは含まない |
| `web` | ブラウザー。JavaScript または WebAssembly にコンパイルされたもの |
| `server` | Dart VM または AOT 実行ファイル: `dart:io` が存在し、Flutter の `dart:ui` は存在しない。Flutter アプリではなく、ブラウザーでもない。アプリに入れてはならないコード、つまり誰でも読めるものに入れてはならないコードのため: 秘密鍵が必要な API など |
| 指定なし | どこでも |

生成されるアプリケーションは、そうしたモジュールを、コンパイラーが知っている定数 (`dart.library.io`、`dart.library.js_interop`、`dart.library.ui`) のもとに列挙します。ほかのプラットフォームではその定数は `false` で、コンパイラーはモジュールと、そのモジュールだけが到達するすべてを取り除きます。そのため、依存関係が `spring_boot_starter_web` を持ち込む Flutter の Web アプリはサーバーのコードを持たず、手作業で除外するものもありません。

- 実行時の条件ではありません。もう一方のプラットフォームでは、モジュールの Bean はスキップされるのではなく、プログラムの中にありません。
- `platform:` は `build:` と組み合わせられます。両方がそう言うとき、モジュールは含まれます。
- `-DSPRING_ALL_PLATFORMS=true` を付けてコンパイルしたプログラムは、プラットフォームに関係なくすべてのモジュールを残します。意図してサーバーのコードを Node 上の JavaScript として動かす場合のためです。
- モジュール全体に使ってください。どこにでもあるモジュールの中でプラットフォームによって異なる Bean は、ほとんどのスターターがしているように、条件付きインポートで選びます。
- ファミリーのどのモジュールに指定があるかは、[一つのプラットフォームだけのモジュール](../spring-core-dart-generator/optimizations/build-conditions.md#どのモジュールに指定があるか) に列挙されています。

Spring に対応するものはありません。JVM のアプリケーションは一つのプラットフォームで動きます。

## ファクトリー

Bean が存在するのは、コンテキストが作られてからです。スターターが追加するもののうち、いくつかはそれより前、環境が準備されている間や Flutter アプリがスプラッシュを表示している間に動かなければなりません。Flutter のテーマを読むときに使うデザインライブラリーがその一つです。テーマはスプラッシュのために、Bean が一つも存在しないうちに読まれます。スターターは、そうしたものを定数として `factories` に列挙します。

```dart
@AutoConfigurationModule(factories: [OceanThemeDesign()])
final BeanModule oceanAutoConfiguration = $oceanBeans;
```

それを必要とするコードは、型を指定して求めます。

```dart
// ApplicationEnvironmentPreparedEvent のリスナーの中で
final designs = event.springApplication.factories.load<ThemeDesign>();
```

- `SpringApplication.factories` は、アプリケーションのすべてのモジュールのファクトリーを持つ `SpringFactories` です。`load<T>()` は型 `T` のものを返します。`Ordered` を実装しているものはその順に、そうでなければモジュールの順に並びます。どのスターターも持っていなければ空です。
- コンテキストは、同じオブジェクトを `springFactories` Bean として持ちます。
- ファクトリーはそれぞれ public な定数です: リテラルの引数による `const` コンストラクターの呼び出し (名前付きコンストラクターも可)、トップレベルの `const` 変数、または `static const` フィールド。ジェネレーターはそれを生成される `springApplication` にコピーします。それ以外の形のファクトリーは、説明とともにビルドを止めます。
- アプリケーションがスターターのファクトリーを得るのは、生成されたときです。ファクトリーを持つスターターを追加したら、`build_runner` を再実行してください。

ファクトリーは、Bean より前に存在しなければならないものにだけ使ってください。それ以外はすべて Bean のままにします。Bean ならアプリケーションが置き換えられます。

## 独自のスターターを書く

どのパッケージもスターターになれます。

1. **モジュールを宣言します。** `lib/spring_auto_configuration.dart` に、`@AutoConfigurationModule` を付けた public なトップレベルの `BeanModule` 変数を置きます。
2. **Bean を記述します。** ジェネレーターで (`@AutoConfiguration`、`@Bean`、条件。スターターの `@ComponentScan` でスキャンされる)、または手書きの `BeanDefinition` で記述します。手書きの定義は、その Bean の条件が順序どおりに判断されるよう、`source` (`library#Class`) か `factoryMethodName` を必要とします。どちらもないものは即座に判断されます。
3. **生成されたコードを公開します。** ジェネレーターはビルド中のパッケージにだけファイルを書き、依存関係には決して書きません。スターターで `dart run build_runner build` を実行し、その `*.spring.dart` ファイルを公開してください。
4. **テストします。** `spring_boot_starter_test` の `ApplicationContextRunner` で、単独の場合、スターターを身を引かせるアプリケーションの Bean がある場合、スターターを無効にするプロパティがある場合をテストします。

```dart
// test/cache_auto_configuration_test.dart
test('backs off when the application has a Cache', () {
  const ApplicationContextRunner()
      .withAutoConfiguration(neonCacheAutoConfiguration)
      .withBean<Cache>(RedisCache.new)
      .run((context) {
    expect(context, hasSingleBean<Cache>());
    expect(context.getBean<Cache>(), isA<RedisCache>());
  });
});
```

アプリケーションが他のスターターと一緒に解決できるよう、スターターのサードパーティーの制約は広く保ってください (`dio: '>=5.0.0 <7.0.0'`)。

## ファミリーのスターター

| スターター | 依存関係を追加すると得られるもの |
|---|---|
| `spring_boot_starter_logging` | パターン付きのコンソール出力、ロールオーバー付きのログファイル、`logging.*` プロパティ、`LogBuffer` |
| `spring_boot_starter_web` | HTTP サーバー: `@RestController`、JSON ボディ、`@Valid`、`ProblemDetail` のエラー、SSE、フィルター、CORS |
| `spring_boot_starter_security` | セキュリティフィルターチェーン、HTTP Basic、フォームログイン、セッション、CSRF、JWT リソースサーバー |
| `spring_boot_starter_feign` | アノテーションを付けたインターフェースからの HTTP クライアント |
| `spring_boot_starter_websocket` | WebSocket のクライアントとエンドポイント |
| `spring_boot_starter_cache` | `@Cacheable`、`@CachePut`、`@CacheEvict`、`CacheManager` |
| `spring_boot_starter_scheduling` | `@Scheduled` メソッドと `TaskScheduler` |
| `spring_boot_starter_data` | リポジトリと SQL データベース |
| `spring_boot_starter_actuator` | ヘルス、情報、メトリクス、その他の管理エンドポイント |
| `spring_boot_starter_flutter` | Flutter アプリ: `SpringApplicationWidget`、ウィジェット内の Bean、テーマ、プラットフォームのプロファイル |
| `spring_boot_starter_test` (dev) | `springBootTest`、`ApplicationContextRunner`、Bean のオーバーライド、`captureLogs` |

## Spring (Java) との対応

```text
# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.neon.cache.CacheAutoConfiguration
```

```java
@AutoConfiguration(after = JacksonAutoConfiguration.class)
@AutoConfigureOrder(10)
class CacheAutoConfiguration { ... }
```

違い:

- 単位はクラスではなくモジュールです。`order`、`before`、`after` は `@AutoConfigurationModule` にあり、そこではクラスを短い名前で指定できます。
- スターターはビルド時に検出されます。新しいスターターには再ビルドが必要です。
- `exclude` の `Type` は単純名で比較されます。
- `build:` (リリースから除かれるモジュール) に対応するものは Spring にはありません。
- `factories` は Spring の `META-INF/spring.factories` のエントリーにあたり、Spring では `SpringFactoriesLoader.loadFactories(type, classLoader)` がクラスパス上からそれを見つけます。Dart にはスキャンするクラスパスがないため、ジェネレーターが定数を生成されるアプリケーションにコピーします。

## 関連項目

- [条件](conditions.md)
- [組み込みの Bean](built-in-beans.md)
- [バージョンと互換性](compatibility.md)
- [ジェネレーター: 自動構成](../spring-core-dart-generator/auto-configurations.md)
- [spring_boot_starter_test](../spring-boot-starter-test/index.md)
