@ComponentScan モジュール

@ComponentScan() を付けたトップレベル変数は スキャンルート を示します。ジェネレーターは、そのファイルのディレクトリとその下のすべての Bean を集め、一つの BeanModule に書き出します。それを返すゲッターの名前は、変数名の先頭に $ を付けたものです。

// lib/src/beans.dart
import 'package:spring_core_dart/spring_core_dart.dart';
import 'package:my_app/spring_gen/src/beans.spring.dart'; // ジェネレーターが書き出す

@ComponentScan()
final BeanModule appBeans = $appBeans;

生成ファイルは lib/spring_gen/src/beans.spring.dart で、BeanModule get $appBeans を宣言します。

使う理由

Spring では、@ComponentScan("com.example.app") が、起動時にどのパッケージを検索するかをコンテナに伝えます。Dart にはその意味でのパッケージがなく、実行時にクラスを検索する方法もありません。そこでジェネレーターがビルド時に検索し、検索範囲はディレクトリ、つまりアノテーションを付けたファイルのディレクトリになります。

変数によって、モジュールは普通の Dart の値になります。コンテキストに渡したり、別のモジュールからインポートしたり、@SpringBootApplication に見つけさせたりできます。変数が読むゲッターは生成されるので、ビルドのたびに変数は現在のコードの Bean を保持します。

ほとんどのアプリケーションには @ComponentScan はまったく不要です。main に付けた @SpringBootApplication() がパッケージ全体をスキャンします (@SpringBootApplication を参照)。@ComponentScan を使うのは次の場合です。

生成されるモジュール

lib/src/ にあり、Bean クラスが二つあるスキャンルートの場合:

// lib/src/beans.dart
@ComponentScan()
final BeanModule appBeans = $appBeans;

// lib/src/info_controller.dart
@RestController()
@RequestMapping('/api')
class InfoController {
  InfoController(@Value(r'${spring.application.name}') this.name);

  final String name;

  @GetMapping('/info')
  Map<String, dynamic> info() => {'name': name};
}

ジェネレーターは次のように書き出します (リポジトリの example/static_site/server から簡略化したもの。_i1. のようなインポートのプレフィックスを外し、メソッドのメタデータと長いリソースのテキストを短くしています)。

// lib/spring_gen/src/beans.spring.dart
// GENERATED CODE - DO NOT MODIFY BY HAND
// Generated by spring_core_dart_generator from @ComponentScan.

/// Beans found by `@ComponentScan` in `lib/src`.
BeanModule get $appBeans => BeanModule(
  r'appBeans',
  [
    BeanDefinition<InfoController>(
      name: r'infoController',
      source: r'package:my_app/src/info_controller.dart#InfoController',
      dependencies: const [Dependency.value(r'${spring.application.name}')],
      create: (r) => InfoController(r.value<String>(r'${spring.application.name}')),
      annotatedMethods: [
        IntrospectedMethod<InfoController>(r'info', /* ... */ annotations: [GetMapping(r'/info')]),
      ],
      annotations: const [RestController(), RequestMapping(r'/api')],
      aopProxy: const AopProxyFactory.pruned(/* ... */),
    ),
  ],
  resources: const {
    r'application.yml': EmbeddedResource.text('spring:\n  application:\n    name: static-site\n...'),
  },
);

ファイルの各部分:

部分 内容
ゲッター名 $ + 変数名: appBeans → $appBeans。
最初の引数 モジュールの名前で、変数名と同じ: r'appBeans'。ログとエラーに現れます。
リスト Bean ごとに一つの BeanDefinition。ファイルの順 (パスでソート) と、各ファイル内の宣言の順に並びます。Bean 定義 を参照してください。
imports: 入れ子のスキャンルートのモジュール (下記 を参照)。
resources: パッケージの lib/resources/ のファイル (埋め込みリソース を参照)。
その他の引数 必要な場合のみ: propertySources: (@PropertySource)、registrars: (レジストラーの @Import)、introspections:、configurers: (@Configurable)、aopProxies:、typeTests: と typeDepths: (型で照合されるアノテーション向け)。

ゲッターの後には、生成された @Log の拡張と、Flutter では BuildContext の拡張が続きます。ゲッターの前には、生成されたクラス (AOP プロキシ、@Configuration と @Lookup のサブクラス、データリポジトリ) が来ます。

ゲッターが変数ではなくゲッターなのは、ホットリロードがその本体を置き換えたとき、次の呼び出しが新しいコードの Bean を返すようにするためです。

モジュールを使う

変数をコンテキストに渡します。

import 'package:spring_core_dart/spring_core_dart.dart';
import 'package:my_app/src/beans.dart';

void main() {
  final context = ApplicationContext.run([appBeans]);
  final controller = context.getBean<InfoController>();
}

main に @SpringBootApplication() を付けたアプリケーションでは、lib/ の下のスキャンルートはアプリケーションのスキャンで見つけられ、その imports: に追加されます (@SpringBootApplication を参照)。スターターは代わりに lib/spring_auto_configuration.dart にモジュールを列挙します (自動構成 を参照)。

スキャンされるファイル

スキャンルートは、アノテーションを付けたファイルのディレクトリです。ジェネレーターは、その下にあるすべての .dart ファイルを深さに関係なく取り込みます。

lib/src/
  beans.dart              @ComponentScan() appBeans    ← スキャンルート
  greeter.dart            appBeans がスキャン
  shop/
    basket.dart           appBeans がスキャン
    payment/
      card.dart           appBeans がスキャン

ルール:

各ライブラリで、ジェネレーターは次のものを見ます。

抽象クラスはスキップされます。ただし @Lookup メソッドを持つ場合は別です (その場合、ジェネレーターは具象サブクラスを書き出します。Bean 定義 を参照)。

入れ子のスキャン

スキャンルートの下で自身の @ComponentScan を宣言するファイルは、そのディレクトリを所有します。そのファイル群は外側のモジュールから除外され、代わりにそのモジュールがインポートされます。

lib/src/
  beans.dart                @ComponentScan() appBeans
  greeter.dart              → appBeans
  shop/
    shop_beans.dart         @ComponentScan() shopBeans
    basket.dart             → shopBeans
    payment/
      payment_beans.dart    @ComponentScan() paymentBeans
      card.dart             → paymentBeans
// lib/spring_gen/src/beans.spring.dart (簡略化)
BeanModule get $appBeans => BeanModule(
  r'appBeans',
  [
    BeanDefinition<Greeter>(/* ... */),
  ],
  imports: [shopBeans],
);

// lib/spring_gen/src/shop/shop_beans.spring.dart (簡略化)
BeanModule get $shopBeans => BeanModule(
  r'shopBeans',
  [
    BeanDefinition<Basket>(/* ... */),
  ],
  imports: [paymentBeans],
);

一つのディレクトリにスキャンルートは一つです。同じディレクトリに二つの @ComponentScan ファイルがあるとビルドが失敗します。

Two @ComponentScan roots in lib/src/: lib/src/beans.dart and lib/src/more_beans.dart.
A directory has one scan root; remove one, or move it into a subdirectory (which the
other then imports).

スキャンオプション

@ComponentScan は Spring のスキャンオプションを受け取ります。これらはアノテーションから定数として読まれ、ジェネレーターが評価するので、実行中のプログラムに届くことはありません。フィルターが拒否したクラスには、単に BeanDefinition がありません。

オプション 型 デフォルト 効果
includeFilters List<Filter> [] これらのいずれかに一致するクラスは、@Component がなくても Bean になります。
excludeFilters List<Filter> [] これらのいずれかに一致するクラスは、他に何が一致しても Bean になりません。その @Bean メソッドも一緒にスキップされます。
useDefaultFilters bool true @Component (とそれを継承するアノテーション) が Bean を示すかどうか。false では、includeFilters だけが Bean を作ります。
lazyInit bool false モジュールのすべての Bean (コンポーネントとその @Bean メソッド) が、@Lazy(false) と書かれていない限り、最初の使用時に生成されます。

クラスがモジュールの Bean になるのは次の場合です。

  1. どのエクスクルードフィルターにも一致しない (エクスクルードは常に優先される)。
  2. かつ、useDefaultFilters が true で、クラスが @Component またはステレオタイプを持つ。
  3. または、クラスが抽象ではなく、インクルードフィルターに一致する。

Filter には三つの種類があります。

type 使うもの 一致するクラス
FilterType.annotation (デフォルト) classes いずれかのクラス、またはそのサブクラスのアノテーションを持つ (Spring のメタアノテーションの Dart での形)
FilterType.assignableType classes いずれかのクラスである、それを継承する、実装する、または mixin する
FilterType.regex pattern クラス名の中でいずれかの正規表現が一致する。式は単純なクラス名 (BookRepository) に対して検査され、^ と $ で固定しない限りどこに一致してもかまいません。

例

@Component を使わず、独自のアノテーションで示すプラグイン:

class Plugin {
  const Plugin();
}

@ComponentScan(includeFilters: [Filter(classes: [Plugin])])
final BeanModule plugins = $plugins;

// lib/src/plugins/pdf_export.dart: `plugins` の Bean
@Plugin()
class PdfExport {}

あるインターフェースのすべての実装だけ:

@ComponentScan(
  useDefaultFilters: false,
  includeFilters: [
    Filter(type: FilterType.assignableType, classes: [Handler]),
  ],
)
final BeanModule handlers = $handlers;

名前が Stub で終わるクラス以外のすべてを、すべて遅延で:

@ComponentScan(
  excludeFilters: [
    Filter(type: FilterType.regex, pattern: [r'Stub$']),
  ],
  lazyInit: true,
)
final BeanModule appBeans = $appBeans;

lazyInit: true でも、Bean を即座に起動させることはできます。

@Service()
@Lazy(false)
class Warmup {}

エラー

すべてのエラーは、その原因となる宣言を指します。

間違い メッセージ
クラス、関数、フィールド、メソッド、ゲッターなどに付けた @ComponentScan @ComponentScan on class AppConfig of package:my_app/src/config.dart: put it on a top-level variable holding the generated module, e.g. @ComponentScan() final BeanModule appBeans = $appBeans;
一つのファイルに二つの @ComponentScan 変数 Only one @ComponentScan is allowed per file.
private な変数、または名前が $ で始まる変数 @ComponentScan variable must be public and must not start with $.
一つのディレクトリに二つのスキャンルート Two @ComponentScan roots in lib/src/: ... (上記)
種類が使うものがない、引数が間違っている、または正規表現が不正なフィルター 下記を参照
名前やエイリアスが同じ二つの無条件の Bean Bean name 'clock' is used by both clock and SystemClock.

フィルターのエラーは、オプションとリスト内のフィルターの位置を示します。

@ComponentScan includeFilters[0]: a FilterType.regex filter needs `pattern`.
@ComponentScan excludeFilters[0]: a FilterType.annotation filter uses `classes`, not `pattern`.
@ComponentScan includeFilters[1]: invalid pattern '[': ...
@ComponentScan includeFilters[0]: `classes` must list classes.

条件付きの Bean (@Profile('dev') と @Profile('prod') で、どちらも dataSource という名前) は名前を共有できます。コンテナは条件に一致するほうを登録し、本当の衝突はコンテキストの起動時に報告します。

スキャンされる宣言のその他のビルドエラーは ビルド時のチェック にあります。

Spring (Java) との対応

@Configuration
@ComponentScan(
    basePackages = "com.example.shop",
    includeFilters = @Filter(type = FilterType.ANNOTATION, classes = Plugin.class),
    excludeFilters = @Filter(type = FilterType.REGEX, pattern = ".*Stub"),
    lazyInit = true)
class ShopConfig {}

違い:

関連項目