
# 自動構成

スターターは、アプリケーションにコードを書かせることなく、それに依存するすべてのアプリケーションに Bean を追加します。そのために使うのが **自動構成モジュール** です。スターターの `lib/spring_auto_configuration.dart` にある、`@AutoConfigurationModule()` を付けた `BeanModule` 変数です。ジェネレーターは、アプリケーションの `@SpringBootApplication` の出力を書き出すとき、アプリケーションが依存するすべてのパッケージでこれらのモジュールを探し、生成された `springApplication` に渡します。

## 使う理由

Spring Boot は起動時に自動構成を見つけます。クラスパスの `META-INF/spring/...AutoConfiguration.imports` ファイルを読むのです。Dart には実行時に読むクラスパスがなく、Flutter、Web、AOT 実行ファイルにはリフレクションもありません。そこでジェネレーターはこの手順をビルド時に行います。各依存関係の決まった名前のファイルを読み、見つけたモジュールへの素の参照を書き出します。

その結果、スターターを `pubspec.yaml` に追加するだけで十分ですが、スターターのモジュールが現れるにはアプリケーションを再ビルド (`dart run build_runner build`) する必要があります。

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

スターターはモジュールを `lib/spring_auto_configuration.dart` に置きます。ファイル名は決まっています。各モジュールは、`@AutoConfigurationModule()` を付けた `BeanModule` 型の **public なトップレベル変数** です。通常、モジュールはスターター自身の `lib/` の `@ComponentScan` から来ます。

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

// lib/src/ の下のすべての Bean クラスがこのモジュールに入る。
@ComponentScan()
final BeanModule neonCacheBeans = $neonCacheBeans;
```

```dart
// lib/src/cache_auto_configuration.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';

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

```dart
// lib/spring_auto_configuration.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';
import 'package:neon_cache/src/cache_beans.dart';

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

手書きの `BeanModule(...)` でもかまいません。`spring_boot_starter_flutter` はモジュールを手で書いています。

`before`、`after`、`excludeName` で使われるモジュールの名前は、その `BeanModule` の名前です。`@ComponentScan` モジュールでは、`spring_auto_configuration.dart` の変数が何という名前であっても、スキャン変数の名前 (上の `neonCacheBeans`) になります。Spring for Dart のスターターは両方に同じ名前 (`springBootStarterCacheAutoConfiguration`) を付けています。

`@AutoConfigurationModule` は次の引数を受け取り、すべて省略可能です。

| 引数 | 型 | デフォルト | 意味 |
|---|---|---|---|
| `order` | `int` | `0` | 自動構成モジュールの中での位置。小さいものが先です (Spring Boot の `@AutoConfigureOrder`)。 |
| `before` | `List<String>` | `[]` | このモジュールより後に登録されるモジュール、または短い名前による `@AutoConfiguration` クラス。それらの条件はこのモジュールの Bean を見ます。未知の名前は無視されます。 |
| `after` | `List<String>` | `[]` | このモジュールより前に登録されるモジュール、または短い名前による `@AutoConfiguration` クラス。未知の名前は無視されます。 |
| `requires` | `String?` | `null`: 任意のバージョン | スターターが動作する `spring_boot_dart` のバージョン。pub のバージョン範囲 (`^0.7.0`、`'>=0.7.0 <0.9.0'`) で書きます。ビルド時にチェックされます。 |
| `build` | `AutoConfigurationBuild?` | `null`: 常に | モジュールをビルドに含めるかどうかを、アプリケーションのプロパティに決めさせます。[ビルドから外されるモジュール](optimizations/build-conditions.md) を参照してください。 |
| `platform` | `ModulePlatform?` | `null`: どこでも | `native`、`web`、`server` のいずれか: モジュールはそのプラットフォームの定数の下に列挙され、ほかのプラットフォームのコンパイラーはそれを落とします。[一つのプラットフォームだけのモジュール](optimizations/build-conditions.md#一つのプラットフォームだけのモジュール) を参照してください。 |
| `factories` | `List<Object>` | `[]` | Bean が一つも存在しないうちにアプリケーションが型で見つける定数。生成されるアプリケーションにコピーされます。[ファクトリー](#ファクトリー) を参照してください。 |

## アプリケーションがモジュールを見つける方法

ジェネレーターはアプリケーション (`main` に `@SpringBootApplication()` を持つライブラリ) を組み立てるとき、次のことを行います。

1. **到達可能なパッケージを列挙します。** アプリケーションの `pubspec.yaml` を読みます。その `dependencies` (エントリーポイントが `example/` や `tool/` のように `lib/` と `bin/` の外にある場合は `dev_dependencies` も) です。次に、それらの各パッケージの `pubspec.yaml` の `dependencies` を読み、これを繰り返します。pub ワークスペースではパッケージ設定にワークスペースのすべてのメンバーが列挙されますが、数えられるのはこの方法で到達したパッケージだけなので、アプリが依存していない兄弟パッケージのモジュールを受け取ることはありません。`pubspec.yaml` を読めない場合、ジェネレーターはモジュールを見落とすより、設定のすべてのパッケージを対象にします。
2. **到達可能な各パッケージの `lib/spring_auto_configuration.dart` を読みます** (ある場合)。アプリケーション自身のパッケージはスキップされますが、`example/` の下のエントリーポイントは例外です。スターターのサンプルは、それに依存する任意のアプリケーションと同じく、スターター自身のモジュールを使います。
3. **`@AutoConfigurationModule` を付けたすべてのトップレベル変数を取ります。** それぞれについて `requires` をチェックし (下記)、`build` を判定します ([ビルドから外されるモジュール](optimizations/build-conditions.md) を参照)。
4. **パッケージ名、次に変数名でソートします**。そのため出力はどのマシンでも同じです。
5. **それらを `springApplication` に書き込みます**。`order`、`before`、`after`、`factories` のいずれかを設定しているモジュールにはその値も書きます。

インポートのプレフィックス (`_i63.`) を外して簡略化した出力です。

```dart
// bin/spring_gen/main.spring.dart (生成)
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    neonCacheAutoConfiguration,                // パッケージ neon_cache
    springBootAutoConfiguration,               // パッケージ spring_boot_dart
    springBootStarterLoggingAutoConfiguration, // パッケージ spring_boot_starter_logging
  ],
  autoConfigurationMetadata: {
    neonCacheAutoConfiguration: const AutoConfigurationModule(
      order: 5,
      after: ['springBootAutoConfiguration'],
    ),
  },
  // dartDefines, fingerprint (デバッグとプロファイルのビルド)
);
```

`order`、`before`、`after`、`factories` のないモジュールは `autoConfigurationMetadata` にエントリーを持ちません。どのモジュールもそれらを設定していなければ、マップは省略されます。

## 登録の順序

ジェネレーターが書くリストは、パッケージと名前でソートされているだけです。モジュールが **登録される** 順序は、Spring Boot の `AutoConfigurationSorter` と同じく、起動のたびに `SpringApplication` が決めます。

1. `order` (エントリーがなければ `0`)、次に名前の順。
2. その後、`before` と `after` がモジュールを移動させます。それらの間に循環があると起動が失敗します。

自動構成モジュールはアプリケーション自身の Bean の後に登録されるので、スターターの `@ConditionalOnMissingBean` はアプリケーションの Bean を見て身を引きます。

## `requires` のチェック

`requires` は、スターターが想定している `spring_boot_dart` のバージョンの範囲です。ジェネレーターはそれを使用中のバージョン (`spring_boot_dart` の定数 `springBootVersion`) と比べ、一致しなければ、後で生成コードや実行時のコードのエラーで失敗する代わりに、ビルドを止めます。これは Java で Spring Boot の BOM や Spring Cloud の互換性検証機能が担う仕事です。

チェックは見つかったすべてのモジュールに対して行われ、ビルド条件で外されるモジュールも対象です。

| 状況 | ビルドエラー |
|---|---|
| 範囲が使用中のバージョンを許さない | `Incompatible starter: neon_cache requires spring_boot_dart ^0.8.0, but 0.7.1 is used.` に続けて `Upgrade spring_boot_dart to a version in ^0.8.0, or use a version of neon_cache made for spring_boot_dart 0.7.1 (see its CHANGELOG / pub.dev versions).` |
| 範囲を解析できない | `neon_cache: invalid requires 'not a range' (...).` |
| `spring_boot_dart` がアプリケーションの依存関係にない | `neon_cache requires spring_boot_dart ^0.7.0, but spring_boot_dart is not a dependency of this application.` |

エラーはスターターのモジュール変数を指します。

## ファクトリー

`@AutoConfigurationModule` の `factories` は、Bean が一つも存在しないうちにアプリケーションが型で見つける定数です ([ファクトリー](../spring-boot-dart/auto-configuration.md#ファクトリー) を参照)。Spring Boot は、そうしたエントリーを実行時にクラスパス上の `META-INF/spring.factories` から `SpringFactoriesLoader.loadFactories(type, classLoader)` で読みます。Dart にはスキャンするクラスパスがないため、ジェネレーターは各ファクトリーを、書かれたとおりの定数として、それ自身のパッケージからインポートして、生成される `springApplication` の `autoConfigurationMetadata` にコピーします。

```dart
// spring_boot_starter_flutter_material の lib/spring_auto_configuration.dart
@AutoConfigurationModule(factories: [MaterialThemeDesign()])
final BeanModule springBootStarterFlutterMaterialAutoConfiguration = BeanModule(/* ... */);
```

```dart
// アプリの lib/spring_gen/main.spring.dart (生成されたもの。インポートのプレフィックスは省略)
autoConfigurationMetadata: {
  springBootStarterFlutterMaterialAutoConfiguration: const AutoConfigurationModule(
    factories: [MaterialThemeDesign()],
  ),
},
```

ファクトリーは、生成されるファイルが名前で指せる public な定数でなければなりません。

| ファクトリー | 書き出される形 |
|---|---|
| リテラルの引数 (`null`、bool、数値、テキスト)、またはそれ自体がこうした定数である引数による `const` コンストラクターの呼び出し | 同じ呼び出し: `MaterialThemeDesign()` |
| 名前付きコンストラクターの呼び出し | 同じ呼び出し: `OceanThemeDesign.dark()` |
| トップレベルの `const` 変数 | その名前: `oceanThemeDesign` |
| `static const` フィールド | クラスとフィールド: `OceanThemeDesign.standard` |

それ以外はビルドを止めます: private なクラスや定数、パッケージの `lib/` の外で宣言されたもの、こうした定数ではない値。エラーは、ファクトリーに何が使えるかを示します: `AutoConfigurationModule.factories: OceanThemeDesign cannot be written into the generated application. A factory is a public constant: a const constructor call with literal arguments, a top-level const variable or a static const field.`

アプリケーションがスターターのファクトリーを持つのは、再び生成されてからです。ファクトリーを持つスターター (Flutter のデザインのスターター、`spring_boot_starter_flutter_material` と `spring_boot_starter_flutter_cupertino` はそれぞれ一つ持ちます) を追加したら、`build_runner` を実行してください。

## `exclude` と `excludeName`

アプリケーションは `@SpringBootApplication` の引数で自動構成を無効にします。

```dart
// bin/main.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';
import 'package:neon_cache/neon_cache.dart'; // CacheAutoConfiguration をエクスポートする

import 'spring_gen/main.spring.dart';

@SpringBootApplication(
  // 型による @AutoConfiguration クラス。
  exclude: [CacheAutoConfiguration],
  // BeanModule の名前によるモジュール全体。
  excludeName: ['springBootStarterCacheAutoConfiguration'],
)
void main(List<String> args) => runApplication(args);
```

ジェネレーターは両方のリストをそのまま引き渡します。

```dart
// 生成
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [/* ... */],
  exclude: [CacheAutoConfiguration],
  excludeName: ['springBootStarterCacheAutoConfiguration'],
  // ...
);
```

`SpringApplication` は起動のたびに、プロパティ `spring.autoconfigure.exclude` とともにそれらを適用します。

- `excludeName` は、`BeanModule` の名前でモジュールに一致するか (スターターが追加するすべてを取り除きます)、短い名前または完全な名前で `@AutoConfiguration` クラスに一致します。未知の名前は無視されるので、スターターを取り除いた後も名前を残しておけます。
- `exclude` は `@AutoConfiguration` クラスを指定します。自動構成クラスでない型は起動を失敗させます。

除外は実行時に働きます。除外されたモジュールのコードも、アプリにはコンパイルされます。モジュールのコードをアプリから外すには、スターターが [ビルド条件](optimizations/build-conditions.md) を宣言する必要があります。

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

スターターは、モジュールをそもそもアプリに含めるかどうかを、ビルド時にアプリケーションに決めさせることができます。

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

プロパティが `true` ならモジュールは上記のように列挙され、`false` なら列挙されず、生成コードに痕跡を残しません。設定されていなければ `if (!const bool.fromEnvironment('dart.vm.product'))` の下に列挙されるので、リリースビルドではコンパイル時に取り除かれます。詳しくは [ビルドから外されるモジュール](optimizations/build-conditions.md) にあります。

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

`platform: ModulePlatform.native` を持つモジュールは `if (const bool.fromEnvironment('dart.library.io'))` の下に、`ModulePlatform.web` を持つモジュールは `if (const bool.fromEnvironment('dart.library.js_interop'))` の下に列挙されます。もう一方のプラットフォームのコンパイラーは定数 `false` を見て、モジュールを、それだけが到達するすべてのものと一緒に落とします。同じ生成ファイルがサーバーのモジュールを列挙していても、ブラウザービルドはサーバーのコードを持ちません。Web スターター、セキュリティスターター、Actuator スターター、WebSocket スターターのサーバー側の半分が `native` です。完全な表は [一つのプラットフォームだけのモジュール](optimizations/build-conditions.md#どのモジュールに指定があるか) にあります。 `ModulePlatform.server` を持つモジュール (アプリに入れてはならないコード。Supabase スターターの管理 API など) は `if (const bool.fromEnvironment('dart.library.io') && !const bool.fromEnvironment('dart.library.ui'))` の下に列挙されるので、Flutter アプリもそれを落とします。

## 関連項目

- [アプリケーション: @SpringBootApplication](spring-boot-application.md)
- [ビルドから外されるモジュール](optimizations/build-conditions.md)
- [AOP プロキシ: 刈り込みと遅延](optimizations/aop-proxies.md)
- [ビルド時のチェック](checks.md)
- [Bean モジュール](../spring-core-dart/beans/bean-module.md)
- [条件](../spring-core-dart/beans/conditional.md)
