
# Spring との違い

Spring (Java) はアプリケーションの起動時に Bean を見つけます。クラスパスをスキャンしてアノテーション付きのクラスを探し、リフレクションでそのアノテーションとコンストラクターを読み、メモリー上に新しいクラスとしてプロキシを作ります。Spring for Dart はプログラミングモデル (同じ意味を持つ同じアノテーション) を保ちつつ、その発見をビルド時に移します。`spring_core_dart_generator` は `build_runner` の実行中にアノテーションを読み、オブジェクトを生成して結び付ける素の Dart コードを書き出します。このページでは、それによって何が変わり、なぜ変わり、何が同じままかを列挙します。

## 使う理由

Dart には、アプリが動く場所でのリフレクションがありません。`dart:mirrors` は Flutter、AOT コンパイルされた実行ファイル、Web では使えず、Dart はプログラムの実行中にクラスを作れません。そのため、Spring が起動時にクラスを見て知ることは、すべてプログラムのコンパイル前にわかっていなければなりません。

以下の違いのほとんどはこの一つの事実から来ています。コストになるものもあります (ビルドを実行しなければならない、ビルドはソースにあるものしか見ない)。利点になるものもあります (アプリの実行前にエラーがわかる、起動時のスキャンがない、ミニファイやツリーシェイキングに耐えるコード)。

## 例

両方での同じサービスです。

```java
// Spring (Java): 起動時にクラスパスのスキャンで見つかり、リフレクションで生成される。
@Service
class Greeter {
  Greeter(@Value("${greeting.suffix:!}") String suffix, Clock clock) { ... }
}
```

```dart
// Spring for Dart: 同じアノテーション...
@Service()
class Greeter {
  Greeter(@Value(r'${greeting.suffix:!}') this.suffix, this.clock);
  final String suffix;
  final Clock clock;
}
```

...そしてビルドは、Spring がリフレクションで実行するコードを書き出します (簡略化。実際のファイルは `_i1.` のようなインポートのプレフィックスを使います)。

```dart
// lib/spring_gen/beans.spring.dart (生成)
BeanModule get $appBeans => BeanModule(r'appBeans', [
  BeanDefinition<Greeter>(
    name: r'greeter',
    types: const [Greeter],
    dependencies: const [
      Dependency.value(r'${greeting.suffix:!}'),
      Dependency(Clock, name: r'clock'),
    ],
    create: (r) => Greeter(
      r.value<String>(r'${greeting.suffix:!}'),
      r.dependency<Clock>(name: r'clock'),
    ),
  ),
]);
```

コンテキストは起動時にこのリストを読みます。値の解決、`Clock` Bean の検索、条件のチェック、ライフサイクルの実行は、Spring と同じく実行時に行われます。生成されるのは、発見と生成のコードだけです。

## 一覧

| 項目 | Spring (Java) | Spring for Dart |
|---|---|---|
| Bean の発見 | 起動時のクラスパスのスキャン | トップレベル変数の `@ComponentScan()`: ビルドがそのファイルのディレクトリとその下をスキャンする |
| Bean の生成 | コンストラクター、フィールド、セッターへのリフレクション | 生成されたコンストラクター呼び出しとクロージャー |
| AOP プロキシ | 起動時に作られる JDK 動的プロキシまたは CGLIB サブクラス | ビルド時に生成されるプロキシクラス |
| フルモードの `@Configuration` クラス、`@Lookup` | 起動時の CGLIB サブクラス | 生成されたサブクラス |
| イントロスペクション (JSON、バリデーション、SpEL) | 任意のクラスへのリフレクション | ビルドが使われると見たものについての生成された記述 |
| 自動構成 | クラスパス上の `META-INF/spring/...AutoConfiguration.imports` | 各依存関係の `lib/spring_auto_configuration.dart`。パッケージ設定を通して見つける |
| Bean より前に必要なスターターのファクトリー | クラスパス上の `META-INF/spring.factories`。`SpringFactoriesLoader.loadFactories(type, classLoader)` が読む | `@AutoConfigurationModule` の `factories`: ジェネレーターが生成される `springApplication` にコピーする public な定数 |
| バイナリーからモジュールを外す | 不要: JVM では未使用のクラスのコストは小さい | `AutoConfigurationBuild`: プロパティによるビルド時の判定 |
| リソース | クラスパス上のファイル | 生成コードに埋め込まれる `lib/resources/` |
| `--dart-define` / システムプロパティ | 実行時に任意のキー | 生成された定数キーのリスト |
| 設定のメタデータ | アノテーションプロセッサー `spring-boot-configuration-processor` | `spring_metadata` ビルダー |
| 間違ったアノテーション | 主に起動時に見つかる | ビルドがソースの場所とともに見つける |

## 発見: クラスパスの代わりにビルド時のスキャン

Spring は起動時にクラスパスのパッケージをスキャンします。ここでは、スキャンルートは `@ComponentScan()` を付けたトップレベル変数です。ビルドはそのファイルのディレクトリとその下のすべてのクラスをスキャンし、Bean ごとに一つの `BeanDefinition` を持つ `BeanModule` を書き出します。独自の `@ComponentScan` を持つサブディレクトリはそのスキャンに任されます。[@ComponentScan モジュール](component-scan.md) を参照してください。

Spring のスキャンオプションは、ビルド時に評価されて動きます。`includeFilters`、`excludeFilters` (アノテーション、代入可能な型、クラス名に対する正規表現による)、`useDefaultFilters`、`lazyInit` です。`FilterType.ASPECTJ` と `FilterType.CUSTOM` は存在しません。独自のフィルターはスキャン中に実行されるコードであり、スキャンとはビルドのことだからです。

これによって得られるもの:

- **起動時のスキャンがない。** Bean のリストはプログラムの定数です。起動時間はクラスの数に応じて増えず、これは Flutter アプリの最初のフレームにとって重要です。
- **コンパイラーに耐えるコード。** 生成されたコンストラクター呼び出しは AOT、Flutter、Web で動き、ミニファイの影響を受けません。実行時に名前で検索されるものはありません。

そのコスト:

- **ビルドの手順。** アノテーションを変更するたびに `dart run build_runner build` を実行するか、`watch` を動かしておく必要があります。それがなければアノテーションは何もしません。
- **Bean の集合はソースが宣言したもの。** JAR がクラスパスに現れたからといってクラスが Bean になることはありません。スキャンされるディレクトリ、`@Bean` メソッド、インポートされたモジュール、依存関係の自動構成のいずれかになければなりません。

## プロキシ: 実行時に作るのではなく生成する

Spring は起動時に AOP プロキシを作ります。インターフェースには JDK 動的プロキシ、クラスには CGLIB サブクラスです。Dart は実行時にクラスを作れないため、ジェネレーターはプロキシを必要としうる Bean ごとにプロキシクラスを書き出します。実装プロキシ、または継承しかできないクラスにはサブクラスプロキシです。起動時には、コンテキストがポイントカットにどの Bean が一致するかを引き続き判断し、何にも一致しない Bean はラップされません。[AOP プロキシ](../spring-core-dart/aop/proxies.md) を参照してください。

Spring が CGLIB を使う他の場所も同じです。フルモードの `@Configuration` クラス (ある `@Bean` メソッドが別のものを呼ぶと共有の Bean を返すため) と、`@Lookup` メソッドを持つ Bean は、生成されたサブクラスを受け取ります。

そのコストと、ジェネレーターがそれを抑える方法:

- **コードサイズ。** プロキシクラスは、どのアドバイスも一致しなくてもコードです。`aop_prune` (デフォルトで有効) により、アプリケーションのビルドは、アプリケーションのどのアドバイスも一致しえない Bean のプロキシクラスを省き、それ以外ではアドバイスされるメンバーだけを残します。[AOP プロキシ: 刈り込みと遅延](optimizations/aop-proxies.md) を参照してください。
- **クラスの形。** プロキシは Bean の代わりになれなければなりません。インターフェースのない `final` クラスはプロキシ化できず、それに一致するアドバイスは理由と変更点を示して起動を失敗させます。Spring にも CGLIB での `final` クラスに同様の制限があります。
- **ビルドから見えずに追加されるアドバイス。** 刈り込みが有効な場合、ビルドが読めない方法で実行時に登録されたアドバイザーは、省かれたものには適用されません。ジェネレーターは、ポイントカットを読めないアドバイザーを見つけると、すべてのプロキシを残します。

## イントロスペクション: ビルドが使われると見たものだけ

Spring の `ObjectMapper`、バリデーション、SpEL は任意のオブジェクトにリフレクションを使います。ここでは、それらは生成された記述 (`Introspection`) を読みます。プログラムを小さく保つため、クラスはアプリケーションがそれに対して行うことについてだけ記述されます。JSON として書かれるならゲッター、読まれるならコンストラクターとセッター、バリデーションされるなら制約付きのプロパティのゲッター、SpEL 式が呼びうるならメソッドです。[実行されるものだけ: イントロスペクション](optimizations/introspection.md) を参照してください。

コスト: `Object` にキャストしてから JSON として書かれる値のように、ビルドから見えない使い方は、必要な部分のない記述を見つけることになります。それは空のオブジェクトではなく、クラス、足りない部分、修正方法を示すメッセージで失敗します。

```text
Bad state: Book is described without its getters, but it is written out as
JSON. The build described only what it saw used, and did not see that: add
@Introspected() to Book.
```

クラスに `@Introspected()` を付けると、リフレクションと同じくすべてが残ります。

## 自動構成: `META-INF` の代わりにパッケージ設定

Spring Boot は、クラスパス上のすべての JAR から `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` を読みます。ここでは、`@SpringBootApplication` ライブラリのビルドが、アプリケーションが直接または間接に依存するすべてのパッケージ (`pubspec.yaml` ファイルから読まれるので、pub ワークスペースの兄弟パッケージは含まれません) を見て、その `lib/spring_auto_configuration.dart` を読みます。そこにある `@AutoConfigurationModule` を付けた各トップレベル変数が自動構成です。生成された `springApplication` はそれらを列挙します。

```dart
// lib/spring_gen/main.spring.dart (生成、簡略化)
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    springBootAutoConfiguration,
    springBootStarterFlutterAutoConfiguration,
    if (!const bool.fromEnvironment('dart.vm.product'))
      springBootStarterFlutterDebugAutoConfiguration,
    springBootStarterFlutterNavigationAutoConfiguration,
  ],
  // ...
);
```

リストはパッケージ順、次に名前順です。`SpringApplication` は起動時に、Spring Boot の `AutoConfigurationSorter` が `@AutoConfigureOrder`、`@AutoConfigureBefore`、`@AutoConfigureAfter` で行うのと同じく、`order`、`before`、`after` でそれをソートします。`@SpringBootApplication` の `exclude` と `excludeName`、プロパティ `spring.autoconfigure.exclude` も起動時に引き続き動きます。スターターは受け付ける `spring_boot_dart` のバージョンを宣言することもでき (`requires:`)、範囲外のバージョンはビルドを失敗させます。スターターが Bean より前に追加するもの、Spring の `META-INF/spring.factories` にあたるものは、そのモジュールの `factories` です。ジェネレーターはその定数を `springApplication` にコピーし、public な定数でないものはビルドを止めます。[自動構成](auto-configurations.md) を参照してください。

## ビルド条件: 条件のビルド時版

Spring は `@Conditional`、`@Profile`、`@ConditionalOnProperty` を起動時に評価し、Spring for Dart も同様です。条件は Bean 定義に書き込まれ、完全な設定、プロファイル、`--dart-define` の値、環境変数を使って、コンテキストの起動時に判定されます。

Spring に対応するもののない追加が一つあります。JVM では、条件によって無効になる自動構成のコストは、使われない数個のクラスです。Flutter アプリでは、コンパイルに含まれたすべての行がユーザーに届けられます。そこで `@AutoConfigurationModule` は `build: AutoConfigurationBuild('<property>')` を受け取ることができ、ジェネレーターはビルド中に設定ファイルから読んだそのプロパティで判定します。

- `true`: モジュールはすべてのビルドに含まれます。
- `false`: モジュールはプログラムにまったく含まれず、それだけが到達するものも含まれません。
- 設定なし: デフォルトではデバッグとプロファイルのビルドにのみ含まれる (上の `if (!const bool.fromEnvironment('dart.vm.product'))`) ので、リリースビルドではコンパイル時に取り除かれます。

`spring_boot_starter_flutter` のデバッグパネルは、`spring.flutter.debug.enabled` でこれを使っています。プロパティはファイルからだけ読まれ、環境変数や `--dart-define` からは読まれません。[ビルドから外されるモジュール](optimizations/build-conditions.md) と [ビルドが読むプロパティ](build-properties.md) を参照してください。

Spring 自身のビルド時の処理であるネイティブイメージ向けの Spring AOT は、さらに先まで進みます。条件とプロファイルをビルド時に評価し、Bean の集合を固定します。Spring for Dart はそうしません。`AutoConfigurationBuild` を除き、条件は実行時に残るので、アプリの起動時に選ばれたプロファイルは引き続きその Bean を変えます。

## リソース: クラスパスではなく埋め込み

Spring は JAR から `classpath:` リソースを読み込みます。Dart のプログラムにはクラスパスがなく、Web 上の Flutter アプリにはファイルシステムがありません。そこでジェネレーターは `lib/resources/` のファイルを生成コードに埋め込みます。テキストはテキストとして、その他のファイルは base64 として埋め込み、1 MB を超えるファイルは警告とともにスキップします。そうすると、設定ファイルを含む `resources:` の場所は、Flutter のアセットを宣言することなく、すべてのプラットフォームで動きます。[埋め込みリソース](resources.md) を参照してください。

## `--dart-define`: 定数のキー

Java のプログラムは、実行時に任意のシステムプロパティや環境変数を名前で読みます。Web や AOT 向けにコンパイルされた Dart のプログラムは、定数のキー (`const String.fromEnvironment('KEY')`) でしか `--dart-define` の値を読めません。そこで `@SpringBootApplication` の出力は、アノテーションのプレースホルダー、`@ConditionalOnProperty` の名前、`@ConfigurationProperties` のフィールド、設定ファイルのキーから、アプリケーションが読みうるすべてのプロパティ名を両方の形 (`shop.currency` と `SHOP_CURRENCY`) で列挙します。

```dart
// lib/spring_gen/main.spring.dart (生成、簡略化)
dartDefines: {
  if (const bool.hasEnvironment('LOGGING_LEVEL_ROOT'))
    'LOGGING_LEVEL_ROOT': const String.fromEnvironment('LOGGING_LEVEL_ROOT'),
  // ...
},
```

コスト: 実行時に文字列から組み立てられたキーのように、ビルドから見えなかったキーは `--dart-define` で設定できません。設定ファイル、環境変数、コマンドラインでは引き続き設定できます。[--dart-define キー](dart-defines.md) を参照してください。

## ビルド時のエラー

Spring はほとんどの間違いをコンテキストの起動時に報告します。ジェネレーターは、ビルド中にソースから見えるものをソースの場所とともに報告し、一つのビルドの独立した問題をすべてまとめて列挙します。

- 解析できないポイントカット式。エラーの位置を示します。
- チェックできない型 (`int` に付けた `@Size`) や不正な属性を持つバリデーションの制約。
- 名前がエンティティに一致しない派生クエリ (`findByTitel`: もしかして `title`?)、パラメーター、プレースホルダー、テーブル、カラムが一致しない `@Query`。
- 設定できない注入フィールド、nullable な `@Lazy` の依存、生成コードが名前を書けない private な型。
- アセットが `pubspec.yaml` で宣言されていないリテラルの `@Value('asset:...')`。
- ファイル間で一致しない型付きのテーマキーとメッセージキー。

[ビルド時のチェック](checks.md) を参照してください。

アプリケーション全体に依存するため、Spring と同じく起動時に行われるチェックもあります。足りない Bean や曖昧な Bean、依存の循環は、コンテキストの起動時、自分のオブジェクトが一つも生成される前に報告されます。

ソースのエラーが生成ファイルを削除することはありません。`build_runner watch` は最後の正常な出力を残すので、それをインポートするファイルが入力中に赤くなることはありません。[エラーと生成ファイル](errors.md) を参照してください。

## エディター向けのメタデータ

Spring Boot はアノテーションプロセッサーで `META-INF/spring-configuration-metadata.json` を書き出し、エディターは JAR からそれを読みます。`spring_metadata` ビルダーは、同種のソース (`@ConfigurationProperties` クラス、その `///` コメントとリテラルのデフォルト、そして Bean とプロファイル) から `lib/spring_gen/spring_metadata.json` を書き出します。これはパッケージとともに公開されるので、エディターはアプリとそのすべての依存関係のメタデータを読めます。[エディター向けのメタデータ](metadata.md) を参照してください。

## Spring に対応するもののない、ビルドが追加するもの

ジェネレーターはすでにビルド時に設定を読んでいるので、Spring には書く理由のないファイルも書き出します。

- テーマキーとメッセージキーの型付きアクセサー (`context.theme.colors.primary`)。名前を変えたキーはコンパイルエラーになります: [型付きキー](flutter/typed-keys.md)
- Flutter の Web 開発サーバーの `web_dev_config.yaml`: [Web 開発サーバー](flutter/web-dev-server.md)
- `web/index.html` のページローダー: [ページローダー](flutter/page-loader.md)
- 検索エンジン向けのページ、サイトマップ、`llms.txt`: [検索エンジン向けのページ](flutter/seo.md)
- iOS、macOS、Android のディープリンクのエントリー: [ディープリンク](flutter/deep-links.md)
