@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 を使うのは次の場合です。
- スターターやワークスペースの共有モジュールなど、Bean を提供するライブラリパッケージ。
spring_boot_dartを使わず、ApplicationContextだけで組み立てるアプリケーション。- 大きなアプリケーションを、それぞれ独自の スキャンオプション を持つモジュール (機能のディレクトリごとに一つ) に分ける場合。
test/の下のテスト用アプリケーション。
生成されるモジュール
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 がスキャン
ルール:
- ファイルはパスでソートされるので、定義はどのマシンでも同じ順序で出力されます。
- 生成された
.spring.dartファイルはスキャンされません。 - part ファイルはそのライブラリを通して読まれます。
- スキャンルートの上や横にあるファイルは、スキャンされるファイルがインポートしていてもスキャンされません。
lib/util.dartの Bean は、lib/src/をルートとするモジュールには含まれません。
各ライブラリで、ジェネレーターは次のものを見ます。
@Componentまたはそれを継承するアノテーション (@Service、@Repository、@Controller、@RestController、@Configurationなど) を持つクラスと、インクルードフィルター に一致するクラス。- それらのクラスの
@Beanメソッド。 - スターターが
@Componentなしで Bean として定義するもの。DataRepositoryを継承するインターフェース (spring_boot_starter_data)、Feign クライアントのような@InterfaceProxyインターフェースです。 - Bean ではないが生成コードを必要とするクラス。
@Configurable、@Introspected、@Log、Bean を持つ Flutter ウィジェットです。
抽象クラスはスキップされます。ただし @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],
);
- インポートされるのは最も外側の入れ子のスキャンだけです。
appBeansはshopBeansを、shopBeansはpaymentBeansをインポートします。appBeansがpaymentBeansを直接インポートすることはありません。 - インポートされるのは生成されたゲッターではなく、自分の変数 (
shopBeans) です。トップレベルのfinal変数は一度だけ生成されるので、インポートされる場所がどこでも同じモジュールオブジェクトが使われ、コンテキストはそれを一度だけ読み込みます。 - インポートされたモジュールは、それをインポートするモジュールより前に読み込まれます。
- 各 Bean はちょうど一つのモジュールに属します。
appBeansとshopBeansを一つのコンテキストで一緒に使っても、Basketが二度登録されることはありません。Spring のスキャナーも同様に、重なり合うスキャンがすでに登録した候補をスキップします。 - 各モジュールは独自の スキャンオプション を保ちます。
appBeansのオプションはshopBeansには適用されません。
一つのディレクトリにスキャンルートは一つです。同じディレクトリに二つの @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 になるのは次の場合です。
- どのエクスクルードフィルターにも一致しない (エクスクルードは常に優先される)。
- かつ、
useDefaultFiltersがtrueで、クラスが@Componentまたはステレオタイプを持つ。 - または、クラスが抽象ではなく、インクルードフィルターに一致する。
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 {}
違い:
- 検索範囲は、アノテーションを付けたファイルのディレクトリとその下です。
basePackagesやbasePackageClassesはありません。 @ComponentScanは@Configurationクラスではなく、生成されたモジュールを保持するトップレベル変数に付けます。- フィルターはビルド時に評価されます。
FilterType.ASPECTJとFilterType.CUSTOMは、ビルド中にコードを実行する必要があるため存在しません。 - 正規表現フィルターは単純なクラス名に対して検査され、その中のどこに一致してもかまいません。Spring は完全修飾クラス名全体と照合します。
- 入れ子のスキャンルートはインポートされるので、各 Bean は一つのモジュールに属します。
関連項目
- @ComponentScan: ランタイム側から見たアノテーション。
- BeanModule
- @Lazy
- Bean 定義