アプリケーション: @SpringBootApplication

main に付ける @SpringBootApplication() (spring_boot_dart のもの) は、アプリケーションに必要な唯一のアノテーションです。それを宣言するライブラリに対して、ジェネレーターはアプリケーションの起動に必要なすべてを含む .spring.dart ファイルを書き出します。

// bin/main.dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

import 'spring_gen/main.spring.dart'; // ジェネレーターが書き出す

@SpringBootApplication()
void main(List<String> args) => runApplication(args);

dart run build_runner build は bin/spring_gen/main.spring.dart を書き出します。Flutter アプリでは、main は lib/main.dart にあり、ファイルは lib/spring_gen/main.spring.dart です。

使う理由

Spring Boot では、メインクラスに付けた @SpringBootApplication が、そのクラスのパッケージからのコンポーネントスキャンと、クラスパス上のすべてのスターターからの自動構成を有効にします。その後、SpringApplication.run が起動時に両方を見つけます。

Dart はどちらも実行時には見つけられません。検索するクラスパスも、読む META-INF/spring/...AutoConfiguration.imports もないからです。そこでジェネレーターは両方の検索をビルド時に行い、その結果を一つの値 springApplication として書き出します。main はそれを実行するだけです。他には何も要りません。@ComponentScan も、モジュールのリストも、スターターの登録も不要です。pubspec.yaml にスターターを追加して build_runner を実行すれば十分です。

スキャンされるもの

スキャンはパッケージ全体に及びます。

main の場所 スキャンされるディレクトリ
bin/main.dart lib/ と bin/
lib/main.dart (Flutter) lib/
test/app/main.dart lib/ と test/app/
example/main.dart、example/shop/bin/main.dart example/ のみ

生成された $application ゲッターのドキュメントコメントがそれらを示します: "Beans found by @ComponentScan in lib/ and bin/."

example/ の下のエントリーポイントは、ライブラリやスターターのサンプルです。スキャンされるのは example/ だけで、パッケージ自身の自動構成は他の依存関係のものと同じように追加されます。パッケージの lib/ は、それに依存する任意のアプリケーションに届くのと同じ方法でサンプルに届きます。

それらのディレクトリの下のすべての .dart ファイルが、パスでソートされ、生成ファイルを除いてスキャンされます。Bean は application という名前の一つのモジュールに入り、ゲッター $application として宣言されます。

入れ子の @ComponentScan ルート

スキャンされるディレクトリの中の @ComponentScan ファイルは、そのディレクトリを所有します。その Bean は独自のモジュールにとどまり、$application は代わりにそのモジュールをインポートします (最も外側のスキャンのみ。入れ子のスキャン を参照)。リポジトリのサーバーガイドは、すべての Bean を一つのスキャンルートの背後の lib/src/ に置いているので、そのアプリケーションモジュールは空で、それをインポートするだけです。

// lib/src/app.dart
@ComponentScan()
final BeanModule appBeans = $appBeans;
// bin/spring_gen/main.spring.dart (抜粋、プレフィックスはそのまま)
/// Beans found by `@ComponentScan` in `lib/ and bin/`.
_i1.BeanModule get $application => _i1.BeanModule(
  r'application',
  [],
  imports: [_i2.appBeans],
  resources: const { /* lib/resources/ のファイル */ },
);

生成されるファイル

ファイルには、次の順で、生成されたクラス (AOP プロキシとその他のサブクラス)、$application、springApplication、四つの起動とリロードの関数、そして @Log と Flutter の拡張が含まれます。

springApplication

サーバーガイドの bin/spring_gen/main.spring.dart の抜粋です。Web、セキュリティ、WebSocket、Feign、キャッシュ、スケジューリングのスターターを使うアプリケーションです (153 個の --dart-define エントリーを二つに短縮しています)。

/// The `@SpringBootApplication` of the current code (a getter, so it is
/// up to date after a hot reload).
_i3.SpringApplication get springApplication => _i3.SpringApplication(
  [$application],
  autoConfigurations: [
    _i4.springBootAutoConfiguration,
    _i5.springBootStarterCacheAutoConfiguration,
    _i6.springBootStarterFeignAutoConfiguration,
    _i7.springBootStarterLoggingAutoConfiguration,
    _i8.springBootStarterOauth2ClientAutoConfiguration,
    _i9.springBootStarterSchedulingAutoConfiguration,
    _i10.springBootStarterSecurityAutoConfiguration,
    _i10.springBootStarterSecurityOAuth2ClientAutoConfiguration,
    _i11.springBootStarterWebAutoConfiguration,
    _i12.springBootStarterWebsocketAutoConfiguration,
    _i13.springSecurityCoreAutoConfiguration,
  ],
  autoConfigurationMetadata: {
    _i10.springBootStarterSecurityAutoConfiguration:
        const _i3.AutoConfigurationModule(
          after: ['springBootStarterOauth2ClientAutoConfiguration'],
        ),
    _i10.springBootStarterSecurityOAuth2ClientAutoConfiguration:
        const _i3.AutoConfigurationModule(
          before: ['springBootStarterOauth2ClientAutoConfiguration'],
        ),
  },
  dartDefines: {
    if (const bool.hasEnvironment('DEBUG'))
      'DEBUG': const String.fromEnvironment('DEBUG'),
    if (const bool.hasEnvironment('LOGGING_FILE_NAME'))
      'LOGGING_FILE_NAME': const String.fromEnvironment('LOGGING_FILE_NAME'),
    // ...
  },
  fingerprint: !const bool.fromEnvironment('dart.vm.product')
      ? _$fingerprint
      : null,
);

その引数:

引数 書かれる条件 内容
最初の引数 常に [$application]。パッケージの Bean のモジュールです。
autoConfigurations 依存関係に自動構成がある すべての依存関係の lib/spring_auto_configuration.dart の @AutoConfigurationModule 変数。パッケージ順、次に名前順にソートされます。自動構成 を参照してください。
autoConfigurationMetadata モジュールが order、before、after を設定している そのようなモジュールごとの値。ランタイムはそれでモジュールをソートします。
exclude、excludeName @SpringBootApplication が設定している 除外する自動構成 (下記 を参照)。
dartDefines 実際には常に --dart-define が設定しうるプロパティごとに一つのエントリー。--dart-define キー を参照してください。
fingerprint デバッグとプロファイルのビルド ホットリロードのための、生成コードのハッシュ (デバッグ用 part にあります)。リリースビルドでは null (下記 を参照)。

springApplication は変数ではなくゲッターです。ホットリロードがその本体を置き換えた後、次の呼び出しは新しいコードからアプリケーションを組み立てます。

アプリケーションがビルドから、またはリリースビルドから外すことをスターターが許しているモジュールは、アプリケーションの application.properties や application.yml からビルド時に決められます (ビルドから外されるモジュール を参照)。リリースビルド以外でだけ残されるモジュールは定数の条件の背後に書かれるので、リリースビルドはそれと、それだけが使うすべてをコンパイル時に取り除きます。

// seo_site サンプルの lib/spring_gen/main.spring.dart (抜粋)
autoConfigurations: [
  _i5.springBootAutoConfiguration,
  _i6.springBootStarterFlutterAutoConfiguration,
  if (!const bool.fromEnvironment('dart.vm.product'))
    _i6.springBootStarterFlutterDebugAutoConfiguration,
  _i7.springBootStarterFlutterNavigationAutoConfiguration,
  _i8.springBootStarterLoggingAutoConfiguration,
],

数えられるのは、pubspec.yaml ファイルから読まれる、アプリケーションの依存関係 (直接、または他のパッケージを通して) だけです。pub ワークスペースではパッケージ設定にワークスペースのすべてのメンバーが列挙されますが、アプリケーションは依存していない兄弟パッケージの自動構成を受け取りません。

スターターは、動作する spring_boot_dart のバージョンを宣言できます (requires)。使われているバージョンがその範囲外なら、ビルドはスターター、範囲、バージョン、アップグレードすべきものを示して失敗します。

runApplication と runApplicationAsync

/// Starts the application: config files, environment, context, runners
/// (asynchronous runners go on one after another after it returns;
/// [runApplicationAsync] waits for them).
ConfigurableApplicationContext runApplication(List<String> args) =>
    springApplication.run(args, hotReload: () => springApplication);

/// Like [runApplication], reading config files asynchronously (Flutter assets)
/// and completing once every runner has finished.
Future<ConfigurableApplicationContext> runApplicationAsync(
  List<String> args,
) => springApplication.runAsync(args, hotReload: () => springApplication);

main からどちらかを呼びます。これらは hotReload: () => springApplication を渡すので、ランタイムはホットリロードの後に現在のコードからアプリケーションを組み立て直せます。

Flutter アプリは、代わりにゲッターをルートウィジェットに渡します。

// lib/main.dart
@SpringBootApplication()
void main() => runApp(SpringApplicationWidget(application: () => springApplication));

同じパッケージの他のエントリーポイントも、独自のアノテーションなしで生成ファイルをインポートし、これらの関数を使えます。サーバーガイドの bin/advanced.dart は spring_gen/main.spring.dart をインポートし、別の引数で runApplicationAsync([...]) を呼びます。

ホットリロード

ホットリロードだけが使うものは、専用の part lib/spring_gen/main.spring.debug.dart にあり、ライブラリは !const bool.fromEnvironment('dart.vm.product') の下でだけそれを参照します。リリースビルド (dart compile exe、AOT、Flutter のリリース) はそれを一切コンパイルしません。デバッグとプロファイルの実行は、ホットリロードも含めて従来どおり動きます。

// lib/spring_gen/main.spring.debug.dart (generated)
const _$fingerprint = '3ada566f';

/// For hot reload: [running] if the generated code is unchanged, else a
/// restarted application with the new beans and the same arguments;
/// [runners]: whether ApplicationRunner / CommandLineRunner beans run again.
ConfigurableApplicationContext reloadApplication(
  ConfigurableApplicationContext running, {
  bool runners = true,
}) => springApplication.reload(running, runners: runners);

/// Like [reloadApplication], reading config files asynchronously.
Future<ConfigurableApplicationContext> reloadApplicationAsync(
  ConfigurableApplicationContext running, {
  bool runners = true,
}) => springApplication.reloadAsync(running, runners: runners);

ホットリロードはメソッドの本体を置き換えますが main を再実行しないので、リロード前に組み立てられたコンテキストは古い Bean を持ち続けます。それが問題になるかを判断するため、ジェネレーターは フィンガープリント を書き出します。生成コード (ライブラリとそのファイル) の FNV-1a ハッシュで、デバッグ用 part に書き込まれ、デバッグとプロファイルのビルドで springApplication が渡します。リロードの後、reload は新しいコードのフィンガープリントを、実行中のコンテキストが起動されたときのものと比べます。

あえてすべてのビルドに残るものがあります。runApplication の hotReload: () => springApplication (コンテキストが同じアプリケーションを別のアイソレートで起動する方法でもあり、Web サーバーの server.isolates.count が使います)、ゲッター springApplication と $application、Bean の source: 文字列 (起動時のエラーとアクチュエーターが読みます) です。

ハッシュは生成されたテキストそのものから計算されるので、コードが同じである限り、どのマシンでも、ビルドごとにも同じです。これらの関数を呼ぶことはまれです。Flutter のホットリロードでは SpringApplicationWidget が呼び、Dart VM では、開発ツールが求めたときに runApplication で起動されたコンテキストをランタイムが再起動します。

exclude と excludeName

@SpringBootApplication は、自動構成を無効にする二つのリストを受け取ります。

@SpringBootApplication(
  exclude: [CacheAutoConfiguration],
  excludeName: ['springBootStarterFeignAutoConfiguration'],
)
void main(List<String> args) => runApplication(args);

ジェネレーターはそれらを、クラスへの参照と文字列として springApplication にコピーします。

SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [/* ... */],
  exclude: [CacheAutoConfiguration],
  excludeName: [r'springBootStarterFeignAutoConfiguration'],
  // ...
);

残りはランタイムが行います。exclude は @AutoConfiguration クラスを列挙します。そうでない型は起動を失敗させます。excludeName は @AutoConfiguration クラスの名前か、モジュール全体の名前 (スターターが追加するすべてを取り除く) を受け取ります。未知の名前は無視されます。プロパティ spring.autoconfigure.exclude を使うと、再ビルドなしで名前を追加できます。

埋め込みリソース

lib/resources/ のファイルは resources: として $application に埋め込まれるので、application.properties、メッセージバンドル、テンプレートはどのプラットフォームでも見つかります。main が lib/ の外にあるアプリケーションは、パッケージのルートから main までの間にある各ディレクトリの lib/resources/ も受け取り、最も近いものが優先されます。アクチュエーターを使うアプリケーションは build-info.properties も受け取ります。埋め込みリソース を参照してください。

--dart-define キー

Flutter、Web、AOT 向けにコンパイルされたプログラムは、定数のキーを持つ --dart-define しか読めません。そこで springApplication は、アプリケーションが読みうるすべてのプロパティを両方の形 (greeting.punctuation と GREETING_PUNCTUATION) で、それぞれ if (const bool.hasEnvironment(...)) の背後に列挙します。マップに入るのはビルド時に与えられた define だけで、コマンドライン引数のすぐ下のプロパティソースになります。--dart-define キー を参照してください。

ルールとエラー

Spring (Java) との対応

@SpringBootApplication(exclude = CacheAutoConfiguration.class)
public class ShopApplication {
  public static void main(String[] args) {
    SpringApplication.run(ShopApplication.class, args);
  }
}

違い:

関連項目