
# @ComponentScan モジュール

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

```dart
// 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](spring-boot-application.md) を参照)。`@ComponentScan` を使うのは次の場合です。

- スターターやワークスペースの共有モジュールなど、Bean を提供するライブラリパッケージ。
- `spring_boot_dart` を使わず、`ApplicationContext` だけで組み立てるアプリケーション。
- 大きなアプリケーションを、それぞれ独自の [スキャンオプション](None#スキャンオプション) を持つモジュール (機能のディレクトリごとに一つ) に分ける場合。
- `test/` の下のテスト用アプリケーション。

## 生成されるモジュール

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

```dart
// 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.` のようなインポートのプレフィックスを外し、メソッドのメタデータと長いリソースのテキストを短くしています)。

```dart
// 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 定義](bean-definitions.md) を参照してください。 |
| `imports:` | 入れ子のスキャンルートのモジュール ([下記](None#入れ子のスキャン) を参照)。 |
| `resources:` | パッケージの `lib/resources/` のファイル ([埋め込みリソース](resources.md) を参照)。 |
| その他の引数 | 必要な場合のみ: `propertySources:` (`@PropertySource`)、`registrars:` (レジストラーの `@Import`)、`introspections:`、`configurers:` (`@Configurable`)、`aopProxies:`、`typeTests:` と `typeDepths:` (型で照合されるアノテーション向け)。 |

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

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

## モジュールを使う

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

```dart
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](spring-boot-application.md#入れ子の-componentscan-ルート) を参照)。スターターは代わりに `lib/spring_auto_configuration.dart` にモジュールを列挙します ([自動構成](auto-configurations.md) を参照)。

## スキャンされるファイル

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

```text
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` など) を持つクラスと、[インクルードフィルター](None#スキャンオプション) に一致するクラス。
- それらのクラスの `@Bean` メソッド。
- スターターが `@Component` なしで Bean として定義するもの。`DataRepository` を継承するインターフェース (`spring_boot_starter_data`)、Feign クライアントのような `@InterfaceProxy` インターフェースです。
- Bean ではないが生成コードを必要とするクラス。`@Configurable`、`@Introspected`、`@Log`、Bean を持つ Flutter ウィジェットです。

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

## 入れ子のスキャン

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

```text
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
```

```dart
// 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 のスキャナーも同様に、重なり合うスキャンがすでに登録した候補をスキップします。
- 各モジュールは独自の [スキャンオプション](None#スキャンオプション) を保ちます。`appBeans` のオプションは `shopBeans` には適用されません。

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

```text
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` を使わず、独自のアノテーションで示すプラグイン:

```dart
class Plugin {
  const Plugin();
}

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

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

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

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

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

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

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

```dart
@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.` |

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

```text
@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` という名前) は名前を共有できます。コンテナは条件に一致するほうを登録し、本当の衝突はコンテキストの起動時に報告します。

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

## Spring (Java) との対応

```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](../spring-core-dart/beans/component-scan.md): ランタイム側から見たアノテーション。
- [BeanModule](../spring-core-dart/beans/bean-module.md)
- [@Lazy](../spring-core-dart/beans/lazy.md)
- [Bean 定義](bean-definitions.md)
