
# Bean 定義

ジェネレーターは、見つけた Bean ごとに一つの `BeanDefinition<T>` を `.spring.dart` ファイルに書き出します。Bean とは、`@Component` クラス (または `@Service`、`@Repository`、`@Controller`、`@Configuration` など `@Component` を継承するアノテーションを持つクラス)、または `@Bean` メソッドです。定義はコンテナが従うレシピです。Bean の名前、検索に使える型、フラグ、そして Bean を生成し、注入し、初期化し、破棄するクロージャーです。

このページでは、各フィールドに何が入り、どのアノテーションがそれを入れるかを示します。例は実際の生成ファイルから取っています。簡略化しており、実際のファイルで使われるインポートのプレフィックス (`_i1.BeanDefinition`、`_i2.Greeter`) は外し、長い `source` 文字列は短くしています。

## 使う理由

Spring は、コンテキストの起動時にリフレクションでアノテーションを読み、コンストラクターを呼びます。Dart には Flutter、AOT 実行ファイル、Web でリフレクションがないため、ジェネレーターがその作業をビルド時に行います。アナライザーで各クラスを読み、素の Dart を書き出します。クロージャーの中のコンストラクター呼び出し、`@PostConstruct` ごとのメソッド呼び出し、`@Autowired` フィールドごとの代入です。

そのため、コンテナがクラスの中で名前によって何かを検索することはありません。コンパイラーがチェックしたクロージャーを呼ぶだけです。だからこそ、コードは Dart VM、AOT、Flutter、Web で同じように動き、ミニファイやツリーシェイキングで壊れることもありません。

## 最初の例

```dart
// 自分で書くもの (example/main.dart):
@Component()
class EnglishGreeter implements Greeter {
  EnglishGreeter(@Value(r'${greeting.punctuation:!}') this.punctuation);

  final String punctuation;

  @override
  String greet(String name) => 'Hello, $name$punctuation';
}

@Service()
class Registration {
  Registration(this.greeter, this.events);

  final Greeter greeter;
  final ApplicationEventPublisher events;
}
```

```dart
// ジェネレーターが書き出すもの (example/spring_gen/main.spring.dart、簡略化):
BeanDefinition<EnglishGreeter>(
  name: r'englishGreeter',
  source: r'asset:spring_core_dart/example/main.dart#EnglishGreeter',
  types: const [EnglishGreeter, Greeter],
  dependencies: const [Dependency.value(r'${greeting.punctuation:!}')],
  create: (r) =>
      EnglishGreeter(r.value<String>(r'${greeting.punctuation:!}')),
  annotations: const [Component()],
  aopProxy: const AopProxyFactory.pruned(knownAdvisors: _$knownAdvisors0),
),
BeanDefinition<Registration>(
  name: r'registration',
  source: r'asset:spring_core_dart/example/main.dart#Registration',
  dependencies: const [
    Dependency(Greeter, name: r'greeter'),
    Dependency(ApplicationEventPublisher, name: r'events'),
  ],
  create: (r) => Registration(
    r.dependency<Greeter>(name: r'greeter'),
    r.dependency<ApplicationEventPublisher>(name: r'events'),
  ),
  annotations: const [Service()],
  aopProxy: const AopProxyFactory.pruned(knownAdvisors: _$knownAdvisors0),
),
```

`r` はコンテナの `DependencyResolver` です。`Registration` には `types:` 行がありません。自身の型でだけ検索され、それがデフォルトだからです。省略可能なフィールドはランタイムのデフォルトと異なる場合にだけ書かれるので、出力は短く保たれます。

## フィールドの一覧

| フィールド | 由来 | 書かれる条件 |
|---|---|---|
| `name` | lowerCamelCase にしたクラス名、`@Component('name')`、`@Bean` メソッド名、または `@Bean(name:)` | 常に |
| `source` | ライブラリの URI とクラス (とメソッド) の名前 | 常に |
| `types` | クラス (または `@Bean` メソッドが返す型) とその公開スーパータイプ | Bean 自身の型以外がある場合 |
| `factoryObjectTypes` | `FactoryBean<T>` の生成物の型 | `FactoryBean` の場合 |
| `aliases` | `@Bean(aliases: [...])` | エイリアスがある場合 |
| `scope` | `@Scope('...')` | `singleton` でない場合 |
| `scopedProxy` | `@Scope(proxyMode: ...)` | スコープ付きプロキシの場合 |
| `lazy` | `@Lazy()`、`@ComponentScan(lazyInit: true)` | `true` の場合 |
| `primary` | `@Primary()` | `true` の場合 |
| `fallback` | `@Fallback()` | `true` の場合 |
| `autowireCandidate` | `@Bean(autowireCandidate: false)` | `false` の場合 |
| `defaultCandidate` | `@Bean(defaultCandidate: false)` | `false` の場合 |
| `factoryBeanName`、`factoryMethodName` | `@Bean` メソッドのクラスとメソッド | `@Bean` メソッドの場合 (static なものには `factoryBeanName` なし) |
| `order` | `@Order(n)` | 設定されている場合 |
| `description` | `@Description('...')` | 設定されている場合 |
| `dependsOn` | `@DependsOn([...])` | 設定されている場合 |
| `qualifiers` | クラスまたは `@Bean` メソッドの `@Qualifier('...')` | 設定されている場合 |
| `conditions` | `@Profile`、`@Conditional`、`@ConditionalOnProperty` のような条件アノテーション | 条件がある場合 |
| `dependencies` | すべての注入ポイント | 一つでもある場合 |
| `create` | コンストラクター、または `@Bean` メソッド | 常に |
| `inject` | `@Autowired` と `@Value` のフィールドとセッター、`@Autowired` メソッド、`@Resource` | 一つでもある場合 |
| `postConstruct`、`preDestroy` | `@PostConstruct`、`@PreDestroy` メソッド | 一つでもある場合 |
| `initMethod`、`initMethodName` | `@Bean(initMethod:)` | 設定されている場合 |
| `destroyMethod`、`destroyMethodName` | `@Bean(destroyMethod:)`、または名前で見つかった `close`、`shutdown`、`dispose` メソッド | ある場合 |
| `eventListeners` | `@EventListener` メソッド、`ApplicationListener<E>` | 一つでもある場合 |
| `annotatedMethods` | `@Scheduled` のような、`@BeanMethodAnnotation()` で示されたアノテーションを持つメソッド | 一つでもある場合 |
| `annotations` | クラスのアノテーション (`@Bean` メソッドではメソッドのもの、次に戻り値のクラスのもの) | 一つでもある場合 |
| `aopProxy` | 生成された AOP プロキシ、またはそれがない理由 | Bean がプロキシ化されうる場合 |
| `aspect` | `@Aspect` クラスのアドバイス | アスペクトの場合 |

以下の節で各グループを説明します。

## 名前とソース

デフォルトの名前は Spring のルールに従います。クラス名の最初の文字を小文字にします (`AuthService` は `authService` になります)。ただし最初の二文字が大文字の場合はそのままです (`URLService` は `URLService` のまま)。`@Bean` メソッドの Bean にはメソッド名が付きます。

```dart
@Component('offline')       // name: r'offline'
@Fallback()
class OfflineGateway implements PaymentGateway { ... }
```

空、空白のみ、または空白で始まるか終わる明示的な名前はビルドを失敗させます。条件のない二つの Bean が名前やエイリアスを共有していても、両方の宣言を示してビルドが失敗します。条件付きの Bean は名前を共有できます (`@Profile(['dev'])` 向けの `dataSource` と `@Profile(['prod'])` 向けの `dataSource`)。本当の衝突は、コンテナが起動時にチェックします。

`source` は Bean が宣言された場所を示します。`package:app/src/shop/payments.dart#OfflineGateway`、`@Bean` メソッドなら `...#ShopConfig.clock` です。`lib/` の外のファイルは `asset:` URI を持ちます。コンテナはこれをエラーメッセージに使い、同じ名前と同じソースで再び登録された定義を無視するので、二度インポートされたモジュールが害になることはありません。

## 型

Dart は、ある `Type` が別の `Type` のサブタイプかどうかを実行時に問い合わせることができません。そのため、定義は Bean を注入できるすべての型を列挙します。そのクラスと、`Object` を除くすべての公開スーパータイプです。

```dart
@Component()
class ShippingNotifier implements ApplicationListener<OrderShipped> { ... }

// 生成されるもの:
types: const [
  ShippingNotifier,
  ApplicationListener<OrderShipped>,
  ApplicationListener<Object>,
],
```

ジェネリック型は、型引数をその境界にした raw の形でも列挙されます (上の `ApplicationListener<Object>`、`Store<User>` に対する `Store<dynamic>`)。そのため、`List<Store>` は Spring の raw 型のようにすべてのストアを受け取ります。private なスーパータイプは生成コードが名前を書けないため除外され、どの公開ライブラリもエクスポートしない SDK の型も除外されます。

ジェネリックな Bean クラスは、その raw 型で登録されます。

## スコープ、遅延、候補のフラグ

```dart
@Configuration()
class ShopConfig {
  @Bean(name: 'coverStore', aliases: ['covers'], initMethod: 'open')
  @Lazy()
  CoverStore coverStore(
    @Value(r'${neon.covers.directory:build/covers}') String directory,
    ResourceLoader resources,
  ) => CoverStore(directory, resources);

  @Bean()
  @Scope(ScopeType.prototype)
  ReceiptBuilder receiptBuilder(ShopProperties shop) =>
      ReceiptBuilder(shop.name, clock().now());
}
```

```dart
// 生成されるもの (簡略化):
BeanDefinition<CoverStore>(
  name: r'coverStore',
  source: r'package:neon_books_server/src/shop/shop_config.dart#ShopConfig.coverStore',
  aliases: const [r'covers'],
  lazy: true,
  factoryBeanName: r'shopConfig',
  factoryMethodName: r'coverStore',
  dependencies: const [
    Dependency(ShopConfig, qualifier: r'shopConfig'),
    Dependency.value(r'${neon.covers.directory:build/covers}'),
    Dependency(ResourceLoader, name: r'resources'),
  ],
  create: (r) => (r.dependency<ShopConfig>(qualifier: r'shopConfig')
      as _$ShopConfigConfiguration)._$coverStore(r),
  initMethod: (bean) {
    bean.open();
  },
  initMethodName: r'open',
  destroyMethod: (bean) {
    bean.close();
  },
  destroyMethodName: r'(inferred)',
  // ...
),
BeanDefinition<ReceiptBuilder>(
  name: r'receiptBuilder',
  scope: r'prototype',
  factoryBeanName: r'shopConfig',
  factoryMethodName: r'receiptBuilder',
  // ...
),
```

- `scope` は `@Scope` の値です。`prototype`、または独自スコープの名前です (`@Scope('import-batch')` は `scope: r'import-batch'` になります)。`@Scope(proxyMode: ...)` では、ジェネレーターは `scopedProxy:` も書き出します。これは呼び出しのたびにスコープの現在のインスタンスを見つける生成されたクラスで、シングルトンがリクエストスコープやセッションスコープの Bean を保持できるようにします。シングルトンや `FactoryBean` に付けた `proxyMode` はビルドを失敗させます。
- `lazy` は `@Lazy()` で `true` になります。`@Bean` メソッドでは、`@Lazy(false)` がクラスの `@Lazy()` より優先され、それが `@ComponentScan(lazyInit: true)` より優先されます。
- `primary` と `fallback` は `@Primary()` と `@Fallback()` から来ます。
- `autowireCandidate: false` と `defaultCandidate: false` は、同名の `@Bean` のオプションから来ます。

## 順序、説明、depends-on、修飾子

```dart
@Component()
@Order(1)
class BulkDiscount implements PriceRule { ... }

// 生成されるもの:
BeanDefinition<BulkDiscount>(
  name: r'bulkDiscount',
  types: const [BulkDiscount, PriceRule],
  order: 1,
  create: (r) => BulkDiscount(),
  annotations: const [Component(), Order(1)],
  // ...
),
```

- `order` はクラス、または `@Bean` メソッドの `@Order` の値です。注入されるリストの中で Bean を並べます。
- `description` は `@Description` のテキストです。
- `dependsOn` は `@DependsOn([...])` の名前を列挙します。この Bean より前に生成され、後に破棄される Bean です。
- `qualifiers` は、クラスまたは `@Bean` メソッドに宣言された `@Qualifier('...')` の値を保持します。修飾された注入ポイントは、これらの値、名前、またはエイリアスで Bean を選びます。

## 条件

三種類のアノテーションが条件になります。

- `@Profile([...])`、または `Profile` を継承するアノテーションクラスは、`const ProfileCondition([...])` になります。
- `@Conditional([MyCondition])` (またはそのサブクラス) は `MyCondition()` になります。その型は `Condition` を実装し、必須パラメーターのないコンストラクターを持たなければならず、そうでなければビルドが失敗します。
- クラスが `Condition` を実装するその他の定数アノテーション (`@ConditionalOnProperty` や `@ConditionalOnMissingBean` など) は、同じ定数として書き直されます。

クラスの条件は、クラスをキーとする一つの `ConditionGroup` にまとめられます。同じグループが、クラスの `@Bean` メソッド、クラスが `@Import` するクラス、その `@PropertySource` を守るので、Spring がクラスごとに決めるのと同じく、それらは一度に、すべてかゼロかで決まります。

```dart
@Component()
@ConditionalOnProperty('neon.support.bot.enabled', havingValue: 'true')
class SupportBot { ... }

// 生成されるもの:
conditions: [
  ConditionGroup(
    r'package:neon_books_server/src/support/support_bot.dart#SupportBot',
    [
      const ConditionalOnProperty(
        r'neon.support.bot.enabled',
        havingValue: r'true',
      ),
    ],
  ),
],
```

`@Bean` メソッドは、まずクラスのグループを受け取り、次に自身の条件をグループなしで受け取ります。

```dart
@Bean()
@ConditionalOnMissingBean(Clock)
Clock clock() => const SystemClock();

// 生成されるもの (クラスには条件がない):
conditions: [const ConditionalOnMissingBean(Clock)],
```

メタアノテーションも動きます。サーバーガイドでは、`@AdvancedTour()` は `Profile` を継承するアノテーションで、それを付けたすべてのクラスが `ConditionGroup(..., [const ProfileCondition([r'advanced'])])` を受け取ります。

## 生成: `create`

`create` は新しいインスタンスを返すクロージャーです。クラスでは、各引数を `r` から取ってコンストラクターを呼びます。

ジェネレーターは Spring と同じようにコンストラクターを選びます。

- `@Autowired()` を持つコンストラクター (付けられるのは一つだけ)。
- `@Autowired(required: false)` のコンストラクターが複数ある場合: 生成コードは、引数の多いものから順に、必須の Bean が存在する最初のものを呼び (`r.containsBeanOfType` で確認します)、なければ最後のものを呼びます。
- それ以外では、唯一の public コンストラクター、プライマリーコンストラクター、または引数を取らないもの。それ以外は曖昧で、ビルドが失敗します。

各パラメーターの読み方:

| パラメーター | 依存 | `create` での呼び出し |
|---|---|---|
| `Clock clock` | `Dependency(Clock, name: r'clock')` | `r.dependency<Clock>(name: r'clock')` |
| `Clock? clock` | `Dependency(Clock, optional: true, name: r'clock')` | `r.optionalDependency<Clock>(name: r'clock')` |
| `@Qualifier('offline') PaymentGateway backup` | `Dependency(PaymentGateway, qualifier: r'offline', name: r'backup')` | `r.dependency<PaymentGateway>(qualifier: r'offline', name: r'backup')` |
| `List<PriceRule> rules` | `Dependency.collection(PriceRule, optional: true)` | `r.optionalDependencyList<PriceRule>() ?? <PriceRule>[]` |
| `Map<String, PriceRule> byName` | `Dependency.map(PriceRule, optional: true)` | `r.optionalDependencyMap<PriceRule>() ?? <String, PriceRule>{}` |
| `ObjectProvider<ImportBatch> batch` | `Dependency.provider(ImportBatch, name: r'batch')` | `r.provider<ImportBatch>(name: r'batch')` |
| `@Lazy() Catalog self` | `Dependency.lazy(Catalog, name: r'self')` | `_$CatalogLazy(r.lazyDependency<Catalog>(name: r'self'))` |
| `@Value(r'${a.b}') int size` | `Dependency.value(r'${a.b}')` | `r.value<int>(r'${a.b}')` |

パラメーター名は `name:` として渡されます。その型の Bean が複数あるとき、その名前やエイリアスを持つものが選ばれます。`Set` はマップの検索から作られるので登録順を保ちます。ソートされるのはリストだけです。`ObjectFactory<T>` と Jakarta の `Provider<T>` は `ObjectProvider<T>` と同じプロバイダーを受け取ります。`Map` のキーは `String` (Bean 名) でなければなりません。

コンストラクターや `@Bean` メソッドのリスト、セット、マップのパラメーターは、表のとおり、一致する Bean がなければ空のコレクションに解決されます。Dart のデフォルト値を持つパラメーターは省略可能で、デフォルトは `??` で適用されます。

```dart
OrderService(
  this._orders, {
  @Value(r'${neon.orders.shipping-delay:5s}')
  this.shippingDelay = const Duration(seconds: 5),
});

// 生成されるもの (create の中):
shippingDelay:
    r.optionalValue<Duration>(r'${neon.orders.shipping-delay:5s}') ??
    const Duration(seconds: 5),
```

`@Value` の式は、プレースホルダー (`${...}`)、SpEL 式 (`#{...}`)、またはリソースの場所 (`Resource` に読み込まれる `resources:templates/mail.txt`) にできます。ジェネレーターは式をそのまま書き、ランタイムがそれを解決してパラメーターの型に変換します。[@Value](../spring-core-dart/config/value.md) を参照してください。

## 依存

`dependencies` は Bean のすべての注入ポイントを表します。コンストラクター、フィールド、セッター、`@Autowired` メソッドのものです。コンテナはこれを Bean の検索には使いません (それは `create` と `inject` が行います)。コンテキストの起動時、Bean を生成する前にグラフ全体をチェックするために使います。足りない Bean、区別できない二つの候補、循環があると、レポートとともに起動が止まります。

インスタンスの `@Bean` メソッドでは、最初の依存はそれを宣言するクラスで、Bean 名で指定されるので、コンテナはそれを先に生成します。

```dart
dependencies: const [
  Dependency(ShopConfig, qualifier: r'shopConfig'),
  Dependency(ShopProperties, name: r'shop'),
],
```

Bean に `@Autowired(required: false)` のコンストラクターが複数ある場合、どれか一つが必須というわけではないので、ここではすべてのポイントが省略可能とされます。

## フィールド、セッター、メソッド: `inject`

フィールドとセッターの `@Autowired`、`@Inject`、`@Value`、`@Resource`、メソッドの `@Autowired` は、一つの `inject` クロージャーにまとめられます。コンテナは `create` の直後にそれを実行します。

```dart
@Service()
class OrderService {
  OrderService(this._orders);

  final OrderRepository _orders;

  @Autowired()
  late final Checkout checkout;      // フィールド注入

  late Clock _clock;

  @Autowired()
  set clock(Clock clock) => _clock = clock;   // セッター注入
}

@Component()
class StartupAnnouncement implements CommandLineRunner {
  @Value('#{shopProperties.name.toUpperCase()}')
  late final String banner;

  @Autowired()
  void configure(Environment environment, ApplicationContext context) { ... }
}
```

```dart
// 生成されるもの (簡略化):
// OrderService
inject: (bean, r) {
  bean.checkout = r.dependency<Checkout>(name: r'checkout');
  bean.clock = r.dependency<Clock>(name: r'clock');
},

// StartupAnnouncement
inject: (bean, r) {
  bean.banner = r.value<String>(r'#{shopProperties.name.toUpperCase()}');
  bean.configure(
    r.dependency<Environment>(name: r'environment'),
    r.dependency<ApplicationContext>(name: r'context'),
  );
},
```

順序は Spring と同じです。スーパークラスのメンバーが先で、各クラスではフィールド、次にセッターとメソッドです。nullable な型のフィールドは省略可能です。Bean が見つからなければそのままにされ (`if (r.optionalDependency<T>(...) case final value?) { bean.x = value; }`)、初期化子の値を保ちます。

次の間違いはビルドを失敗させます。

- 設定できない注入フィールド。`late final` または非 final として宣言してください。
- private なフィールド、セッター、メソッド。生成ファイルは別のライブラリなので届きません。代わりにコンストラクターのパラメーターで注入してください (`this._clock` ならフィールドは private のままです)。
- フィールド、セッター、メソッドに付けた `@Autowired(required: false)`。`required` はコンストラクターの選択にだけ使われます。省略可能な依存には nullable な型を使ってください。
- `@Autowired`、`@Inject`、`@Value` と一緒に付けた `@Resource`。
- 生成コードが await しない `async` の `@Autowired` メソッド。

プライマリーコンストラクターのパラメーターで宣言されたフィールドは、フィールドとしてではなくコンストラクターを通して注入されます。[@Autowired](../spring-core-dart/beans/autowired.md) を参照してください。

## ライフサイクルのコールバック

```dart
class LifecycleProbe implements InitializingBean, DisposableBean {
  @PostConstruct()
  void postConstruct() { ... }

  @PreDestroy()
  void preDestroy() { ... }

  void customInit() { ... }
  void customDestroy() { ... }
  // インターフェースの afterPropertiesSet() と destroy() ...
}

@Configuration()
class LifecycleConfig {
  @Bean(initMethod: 'customInit', destroyMethod: 'customDestroy')
  LifecycleProbe lifecycleProbe() => LifecycleProbe();
}
```

```dart
// 生成されるもの (簡略化):
postConstruct: (bean) {
  bean.postConstruct();
},
initMethod: (bean) {
  bean.customInit();
},
initMethodName: r'customInit',
preDestroy: (bean) {
  bean.preDestroy();
},
destroyMethod: (bean) {
  bean.customDestroy();
},
destroyMethodName: r'customDestroy',
```

- `postConstruct` はすべての `@PostConstruct` メソッドを、スーパークラスのメソッドから順に呼びます。`preDestroy` はすべての `@PreDestroy` メソッドを、サブクラスのメソッドから順に呼びます。
- `initMethod` と `destroyMethod` は `@Bean(initMethod:, destroyMethod:)` から来ます。メソッドは戻り値の型に存在し、必須の引数を取ってはいけません。
- `@Bean` の `destroyMethod` のデフォルトは、Spring と同じく `'(inferred)'` です。ジェネレーターは、必須パラメーターのない public な `close`、`shutdown`、`dispose` メソッドを探し、見つかれば `destroyMethodName: r'(inferred)'` を書きます (上の `coverStore` Bean)。`destroyMethod: ''` でこれを無効にできます。
- アノテーションが付き、かつ init や destroy のメソッドとして指定されたメソッドは一度だけ実行されます。
- `Future` を返すライフサイクルメソッドは、それを await する `async` クロージャーとして書かれます (`(bean) async { await bean.open(); }`)。`refreshAsync()` と `closeAsync()` はその Future を await します。
- `InitializingBean.afterPropertiesSet` と `DisposableBean.destroy` は定義に何も必要としません。Bean がインターフェースを実装しているので、コンテナがそれらを呼びます。

コンテキストが Bean を生成するときは、`create`、`inject`、Aware のコールバック、`postProcessBeforeInitialization`、`postConstruct`、`afterPropertiesSet`、`initMethod`、`postProcessAfterInitialization` の順に呼びます。閉じるときは、`DestructionAwareBeanPostProcessor`、`preDestroy`、`DisposableBean.destroy`、`destroyMethod` の順です。[ライフサイクル](../spring-core-dart/beans/lifecycle.md) を参照してください。

## イベントリスナー

各 `@EventListener` メソッドと `ApplicationListener<E>` の `onApplicationEvent` は、それを呼ぶクロージャーを持つ `EventListenerMethod` になります。

```dart
bool isVipOrder(OrderPlaced placed) => placed.order.total >= 100;

@Component()
class VipDesk {
  @EventListener(condition: isVipOrder)
  @Order(2)
  void onVipOrder(OrderPlaced placed) { ... }
}
```

```dart
// 生成されるもの:
eventListeners: [
  EventListenerMethod.of<VipDesk, OrderPlaced>(
    r'VipDesk.onVipOrder',
    (bean, event) {
      bean.onVipOrder(event);
      return null;
    },
    order: 2,
    condition: isVipOrder,
  ),
],
```

最初の引数はリスナーの ID です。メソッドに `@Async()` があると `async: const Async()` が加わります。値を返すメソッドはクロージャーからそれを返すので、ランタイムはそれを新しいイベントとして発行できます。`PayloadApplicationEvent<P>` のリスナーは `EventListenerMethod.forPayload` で、複数のイベント型を持つもの (`@EventListener(classes: [A, B])`) はイベントの型を検査する `EventListenerMethod.matching` で書かれます。

条件は SpEL 文字列ではなく関数です。Dart はリフレクションなしで文字列をオブジェクトに対して評価できないからです。[@EventListener](../spring-core-dart/events/event-listener.md) を参照してください。

## ファクトリー Bean

`FactoryBean<T>` を継承するクラスは `factoryObjectTypes` を受け取ります。生成物の型とそのスーパータイプです。

```dart
@Component()
class ProductFactory extends FactoryBean<Product> {
  @override
  Product getObject() => Product();
}

// 生成されるもの (一部):
factoryObjectTypes: const [Product],
```

これらの型や Bean の名前での検索は生成物を返します。`&productFactory` はファクトリー自身を返します。生成物の型はクラス型でなければなりません。[FactoryBean](../spring-core-dart/beans/factory-bean.md) を参照してください。

## `@Bean` メソッド

`@Bean` メソッドは、`factoryMethodName` と、インスタンスメソッドでは `factoryBeanName` を持つ定義になります。その `create` はメソッドを呼びます。

```dart
// @Component クラス、または @Configuration(proxyBeanMethods: false) の
// インスタンスメソッド: 所有者の Bean に対して呼ばれる。
create: (r) => r.dependency<AppConfig>(qualifier: r'appConfig').pool(),

// static メソッド: クラスに対して呼ばれ、所有者の Bean は不要。
create: (r) => AppConfig.pool(),

// フルモードの @Configuration クラス: 生成されたサブクラスを通して (下記)。
create: (r) => (r.dependency<ShopConfig>(qualifier: r'shopConfig')
    as _$ShopConfigConfiguration)._$coverStore(r),
```

返されたオブジェクトは他の Bean と同じように扱われます。戻り値の型の `@Autowired` と `@Value` のメンバー、ライフサイクルメソッド、リスナーも適用されます。クラスの条件が先で、次にメソッドの条件です。`annotations` はメソッドのアノテーション、次に戻り値のクラスのアノテーションを保持します。

private またはジェネリックな `@Bean` メソッド、`async` のもの、extension type を返すもの、トップレベル関数に付けたものはビルドを失敗させます。

### 型は本体から読まれる

ジェネレーターはメソッドの本体を見るので、宣言された戻り値の型だけでなく、メソッドが実際に返すクラスで Bean を登録します。

```dart
@Bean()
@ConditionalOnMissingBean(Clock)
Clock clock() => const SystemClock();
```

```dart
// 生成されるもの (簡略化):
BeanDefinition<SystemClock>(
  name: r'clock',
  types: const [SystemClock, Clock],
  factoryBeanName: r'shopConfig',
  factoryMethodName: r'clock',
  conditions: [const ConditionalOnMissingBean(Clock)],
  dependencies: const [Dependency(ShopConfig, qualifier: r'shopConfig')],
  create: (r) => ((r.dependency<ShopConfig>(qualifier: r'shopConfig')
      as _$ShopConfigConfiguration)._$clock(r) as SystemClock),
  // ...
),
```

型は、推論されたクラスとそのスーパータイプ、次にまだ列挙されていない宣言された型とそのスーパータイプです。`create` は結果を推論されたクラスにキャストします。そのため、検索、条件、AOP は、Bean が存在する前から `SystemClock` を目にします。Spring はメソッドを呼ぶまで宣言された型しか知りません。

複数の `return` はその共通のスーパータイプになり、`throw` は無視されます。本体が nullable な型、生成コードが名前を書けない型 (private、SDK 内部、または型パラメーター付き) を返す場合や、本体を読めない場合、ジェネレーターは宣言された型を保ちます。

`@Bean` メソッドは `T?` (`null` の結果は `NullBean` として保存されます)、関数型、レコード型を返すこともできます。

## フルモードの `@Configuration`: 生成されたサブクラス

Spring では、`@Configuration` クラスは CGLIB でサブクラス化され、ある `@Bean` メソッドが別の `@Bean` メソッドを呼ぶと、新しいオブジェクトではなくコンテナのシングルトンを受け取ります。ジェネレーターは、インスタンスの `@Bean` メソッドを一つ以上持つ `@Configuration` クラス (`proxyBeanMethods: true`、デフォルト) に対して、生成された Dart のサブクラスで同じことを行います。

```dart
@Configuration()
class ShopConfig {
  @Bean()
  @ConditionalOnMissingBean(Clock)
  Clock clock() => const SystemClock();

  // clock() は Bean 間の呼び出し: コンテナの clock Bean を返す。
  @Bean()
  @Scope(ScopeType.prototype)
  ReceiptBuilder receiptBuilder(ShopProperties shop) =>
      ReceiptBuilder(shop.name, clock().now());
}
```

```dart
// 生成されるもの (簡略化):
/// `ShopConfig` whose `@Bean` methods return the beans of the container
/// (full-mode `@Configuration`).
class _$ShopConfigConfiguration extends ShopConfig {
  _$ShopConfigConfiguration(this._$beanFactory);

  final BeanFactory _$beanFactory;

  final _$arguments = <String, List<Object?>>{};

  // 自分のコードはこれを呼ぶ: コンテナの Bean を返す。
  @override
  Clock clock() => (this._$beanFactory.getBeanByName(r'clock') as Clock);

  // コンテナは Bean を生成するためにこれを呼ぶ: 元の本体。
  Clock _$clock(DependencyResolver r) => super.clock();

  @override
  ReceiptBuilder receiptBuilder(ShopProperties shop) {
    final _$args = <Object?>[shop];
    this._$arguments[r'receiptBuilder'] = _$args;
    try {
      return (this._$beanFactory.getBeanByName(r'receiptBuilder')
          as ReceiptBuilder);
    } finally {
      this._$arguments.remove(r'receiptBuilder');
    }
  }

  ReceiptBuilder _$receiptBuilder(DependencyResolver r) {
    final _$args = this._$arguments.remove(r'receiptBuilder');
    if (_$args != null) {
      return super.receiptBuilder((_$args[0] as ShopProperties));
    }
    return super.receiptBuilder(r.dependency<ShopProperties>(name: r'shop'));
  }
}

// クラスの定義がサブクラスを生成する:
BeanDefinition<ShopConfig>(
  name: r'shopConfig',
  create: (r) => _$ShopConfigConfiguration(r),
  annotations: const [Configuration()],
),
```

仕組み:

1. クラスの定義は、コンテナの `BeanFactory` と、続いてクラス自身のコンストラクター引数を渡して `_$ShopConfigConfiguration` を生成します。
2. インスタンスの各 `@Bean` メソッドはオーバーライドされ、`getBeanByName('<bean name>')` を返します (`FactoryBean` を返すメソッドでは `'&<name>'`)。ある `@Bean` メソッドから別の `@Bean` メソッドへの呼び出しはコンテナを通ります。
3. `_$<method>(r)` は元の本体を保ち、各 `@Bean` 定義の `create` がそれを呼びます。
4. コードが `@Bean` メソッドに引数を渡し、その呼び出しが Bean を生成する場合、Spring の `BeanMethodInterceptor` と同じく、その引数が生成に使われます。既存のシングルトンはそのまま返され、プロトタイプはその引数で生成されます。それ以外では、パラメーターはコンテナから解決されます。

static な `@Bean` メソッドは、Spring と同じくインターセプトされません。サブクラスを書けない場合はビルドが失敗します。`sealed`、`final`、`interface` のクラス、ライブラリの外で継承できないクラス、ファクトリーまたは private なコンストラクター、デフォルト値が定数でない `@Bean` パラメーターです。エラーは `@Configuration(proxyBeanMethods: false)` を提案します。これはメソッドを書かれたとおりに呼びます (「ライト」モード。`@Bean` メソッドを持つ `@Component` クラスでも使われます)。[@Configuration](../spring-core-dart/beans/configuration.md) を参照してください。

## `@Lookup` メソッド: 生成されたサブクラス

`@Lookup` メソッドは呼び出しのたびにコンテナから Bean を返すので、シングルトンは毎回新しいプロトタイプを受け取れます。ジェネレーターは各ルックアップメソッドをオーバーライドするサブクラスを書き出します。

```dart
@Component()
abstract class OrderMailer {
  OrderMailer(
    @Value('resources:templates/order-confirmation.txt') this.template,
    this.messages,
    this.mail,
    this.shop,
  );
  // ...

  /// 呼び出しごとに新しい ReceiptBuilder (プロトタイプ Bean)。
  @Lookup()
  ReceiptBuilder newReceipt();
}
```

```dart
// 生成されるもの (簡略化):
/// `OrderMailer` whose `@Lookup` methods return beans of the container.
class _$OrderMailerLookup extends OrderMailer {
  _$OrderMailerLookup(
    this._$beanFactory,
    super.p0,
    super.p1,
    super.p2,
    super.p3,
  );

  final BeanFactory _$beanFactory;

  @override
  ReceiptBuilder newReceipt() =>
      this._$beanFactory.getBean<ReceiptBuilder>();
}

BeanDefinition<OrderMailer>(
  name: r'orderMailer',
  dependencies: const [
    Dependency.value(r'resources:templates/order-confirmation.txt'),
    Dependency(MessageSource, name: r'messages'),
    Dependency(MailSender, name: r'mail'),
    Dependency(ShopProperties, name: r'shop'),
  ],
  create: (r) => _$OrderMailerLookup(
    r,
    r.value<Resource>(r'resources:templates/order-confirmation.txt'),
    r.dependency<MessageSource>(name: r'messages'),
    r.dependency<MailSender>(name: r'mail'),
    r.dependency<ShopProperties>(name: r'shop'),
  ),
  // ...
),
```

- オーバーライドは `getBean<T>()`、nullable な戻り値の型では `findBean<T>()`、`@Lookup('name')` では `getBeanByName('name')` を呼びます。
- `@Lookup` メソッドを持つクラスは抽象でもかまいません。それ以外の抽象クラスは Bean ではなく、ビルドを失敗させます。
- `@Lookup` メソッドは public で、static でなく、ジェネリックでもない必要があります。ゲッター、セッター、フィールドに付けた `@Lookup` はビルドを失敗させます。メソッドを宣言してください。
- Bean がサブクラスの AOP プロキシも受け取る場合、プロキシはルックアップクラスを継承します。

[@Lookup](../spring-core-dart/beans/lookup.md) を参照してください。

## アノテーション

`annotations` は Bean クラスのアノテーションを定数として書き直したものを保持するので、`findAnnotationOnBean` と `getBeansWithAnnotation` はリフレクションなしで動きます。`@Bean` メソッドでは、メソッドのアノテーション、次に戻り値のクラスのアノテーションを保持します。アノテーションが残されるのは、public で、SDK のものではなく、定数として書ける (private な値がない) 場合です。それ以外は黙って除外されます。

## `aopProxy` と `aspect`

`aopProxy` は、アスペクトが適用されるときに Bean をどうラップするかをコンテナに伝えます。

- `AopProxyFactory(...)`: Bean の型を実装し、Bean に転送する生成されたプロキシクラス。
- `AopProxyFactory.subclass(...)`: 継承しかできないクラス向けの生成されたサブクラス。Bean 自身がそれを通して生成されます。
- `const AopProxyFactory.pruned(...)`: アプリケーションのどのアドバイスも Bean に一致しえないため、プロキシクラスなし。
- `const AopProxyFactory.deferred(...)`: スターターの Bean。そのプロキシクラスはアプリケーションのビルドが書き出します。
- `AopProxyFactory.unavailable(reason: ...)`: プロキシを書けない (private なメンバー、インターフェースのない `final` クラス)。理由が何を変えるべきかを示します。

構成クラス、アスペクト、インフラストラクチャーの Bean は `aopProxy` を受け取りません。`@Aspect` クラスは `aspect:` (ビルド時に解析されたアドバイスとポイントカット) を受け取ります。[AOP プロキシ: 刈り込みと遅延](optimizations/aop-proxies.md) と [プロキシ](../spring-core-dart/aop/proxies.md) を参照してください。

## アノテーション付きメソッド

`@Scheduled` のような、`@BeanMethodAnnotation()` で示されたアノテーションを持つメソッドは、`IntrospectedMethod` として `annotatedMethods` に列挙されます。名前、パラメーター、アノテーション、それを呼ぶ関数です。スターターは実行時にこれらのメソッドを見つけて呼びます (スケジューラーはすべての `@Scheduled` メソッドを開始します)。[Bean メソッドのアノテーション](../spring-core-dart/beans/bean-method-annotation.md) を参照してください。

## Spring (Java) との対応

```java
// ClassPathBeanDefinitionScanner はコンテキストの起動時にクラスファイルを読み、
// コンポーネントごとに ScannedGenericBeanDefinition を登録する。
// ConfigurationClassBeanDefinitionReader は @Bean メソッドごとに一つ追加する。
// その後、リフレクションがインスタンスを生成し、注入する。
@Service
@Lazy
class Greeter {
  Greeter(Clock clock) {}
  @PostConstruct void init() {}
}
```

重要な違い:

- 定義はビルド時に書き出されます。アノテーションを変更したら `build_runner` を実行してください。
- Dart は実行時に `Type` のサブタイプを検査できないため、`types` はすべてのスーパータイプを列挙します。
- `@Bean` の定義は、宣言された戻り値の型だけでなく、本体が返すクラスで登録されます。
- `@EventListener` の条件は SpEL 文字列ではなく関数です。

## 関連項目

- [@ComponentScan モジュール](component-scan.md)
- [アプリケーション: @SpringBootApplication](spring-boot-application.md)
- [ビルド時のチェック](checks.md)
- [実行されるものだけ: イントロスペクション](optimizations/introspection.md)
- [spring_core_dart の Bean](../spring-core-dart/beans/index.md)
