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 で同じように動き、ミニファイやツリーシェイキングで壊れることもありません。
最初の例
// 自分で書くもの (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;
}
// ジェネレーターが書き出すもの (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 にはメソッド名が付きます。
@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 を除くすべての公開スーパータイプです。
@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 型で登録されます。
スコープ、遅延、候補のフラグ
@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());
}
// 生成されるもの (簡略化):
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、修飾子
@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 がクラスごとに決めるのと同じく、それらは一度に、すべてかゼロかで決まります。
@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 メソッドは、まずクラスのグループを受け取り、次に自身の条件をグループなしで受け取ります。
@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 のデフォルト値を持つパラメーターは省略可能で、デフォルトは ?? で適用されます。
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 を参照してください。
依存
dependencies は Bean のすべての注入ポイントを表します。コンストラクター、フィールド、セッター、@Autowired メソッドのものです。コンテナはこれを Bean の検索には使いません (それは create と inject が行います)。コンテキストの起動時、Bean を生成する前にグラフ全体をチェックするために使います。足りない Bean、区別できない二つの候補、循環があると、レポートとともに起動が止まります。
インスタンスの @Bean メソッドでは、最初の依存はそれを宣言するクラスで、Bean 名で指定されるので、コンテナはそれを先に生成します。
dependencies: const [
Dependency(ShopConfig, qualifier: r'shopConfig'),
Dependency(ShopProperties, name: r'shop'),
],
Bean に @Autowired(required: false) のコンストラクターが複数ある場合、どれか一つが必須というわけではないので、ここではすべてのポイントが省略可能とされます。
フィールド、セッター、メソッド: inject
フィールドとセッターの @Autowired、@Inject、@Value、@Resource、メソッドの @Autowired は、一つの inject クロージャーにまとめられます。コンテナは create の直後にそれを実行します。
@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) { ... }
}
// 生成されるもの (簡略化):
// 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 を参照してください。
ライフサイクルのコールバック
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();
}
// 生成されるもの (簡略化):
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)'を書きます (上のcoverStoreBean)。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 の順です。ライフサイクル を参照してください。
イベントリスナー
各 @EventListener メソッドと ApplicationListener<E> の onApplicationEvent は、それを呼ぶクロージャーを持つ EventListenerMethod になります。
bool isVipOrder(OrderPlaced placed) => placed.order.total >= 100;
@Component()
class VipDesk {
@EventListener(condition: isVipOrder)
@Order(2)
void onVipOrder(OrderPlaced placed) { ... }
}
// 生成されるもの:
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 を参照してください。
ファクトリー Bean
FactoryBean<T> を継承するクラスは factoryObjectTypes を受け取ります。生成物の型とそのスーパータイプです。
@Component()
class ProductFactory extends FactoryBean<Product> {
@override
Product getObject() => Product();
}
// 生成されるもの (一部):
factoryObjectTypes: const [Product],
これらの型や Bean の名前での検索は生成物を返します。&productFactory はファクトリー自身を返します。生成物の型はクラス型でなければなりません。FactoryBean を参照してください。
@Bean メソッド
@Bean メソッドは、factoryMethodName と、インスタンスメソッドでは factoryBeanName を持つ定義になります。その create はメソッドを呼びます。
// @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 を登録します。
@Bean()
@ConditionalOnMissingBean(Clock)
Clock clock() => const SystemClock();
// 生成されるもの (簡略化):
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 のサブクラスで同じことを行います。
@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());
}
// 生成されるもの (簡略化):
/// `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()],
),
仕組み:
- クラスの定義は、コンテナの
BeanFactoryと、続いてクラス自身のコンストラクター引数を渡して_$ShopConfigConfigurationを生成します。 - インスタンスの各
@Beanメソッドはオーバーライドされ、getBeanByName('<bean name>')を返します (FactoryBeanを返すメソッドでは'&<name>')。ある@Beanメソッドから別の@Beanメソッドへの呼び出しはコンテナを通ります。 _$<method>(r)は元の本体を保ち、各@Bean定義のcreateがそれを呼びます。- コードが
@Beanメソッドに引数を渡し、その呼び出しが Bean を生成する場合、Spring のBeanMethodInterceptorと同じく、その引数が生成に使われます。既存のシングルトンはそのまま返され、プロトタイプはその引数で生成されます。それ以外では、パラメーターはコンテナから解決されます。
static な @Bean メソッドは、Spring と同じくインターセプトされません。サブクラスを書けない場合はビルドが失敗します。sealed、final、interface のクラス、ライブラリの外で継承できないクラス、ファクトリーまたは private なコンストラクター、デフォルト値が定数でない @Bean パラメーターです。エラーは @Configuration(proxyBeanMethods: false) を提案します。これはメソッドを書かれたとおりに呼びます (「ライト」モード。@Bean メソッドを持つ @Component クラスでも使われます)。@Configuration を参照してください。
@Lookup メソッド: 生成されたサブクラス
@Lookup メソッドは呼び出しのたびにコンテナから Bean を返すので、シングルトンは毎回新しいプロトタイプを受け取れます。ジェネレーターは各ルックアップメソッドをオーバーライドするサブクラスを書き出します。
@Component()
abstract class OrderMailer {
OrderMailer(
@Value('resources:templates/order-confirmation.txt') this.template,
this.messages,
this.mail,
this.shop,
);
// ...
/// 呼び出しごとに新しい ReceiptBuilder (プロトタイプ Bean)。
@Lookup()
ReceiptBuilder newReceipt();
}
// 生成されるもの (簡略化):
/// `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 を参照してください。
アノテーション
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 プロキシ: 刈り込みと遅延 と プロキシ を参照してください。
アノテーション付きメソッド
@Scheduled のような、@BeanMethodAnnotation() で示されたアノテーションを持つメソッドは、IntrospectedMethod として annotatedMethods に列挙されます。名前、パラメーター、アノテーション、それを呼ぶ関数です。スターターは実行時にこれらのメソッドを見つけて呼びます (スケジューラーはすべての @Scheduled メソッドを開始します)。Bean メソッドのアノテーション を参照してください。
Spring (Java) との対応
// ClassPathBeanDefinitionScanner はコンテキストの起動時にクラスファイルを読み、
// コンポーネントごとに ScannedGenericBeanDefinition を登録する。
// ConfigurationClassBeanDefinitionReader は @Bean メソッドごとに一つ追加する。
// その後、リフレクションがインスタンスを生成し、注入する。
@Service
@Lazy
class Greeter {
Greeter(Clock clock) {}
@PostConstruct void init() {}
}
重要な違い:
- 定義はビルド時に書き出されます。アノテーションを変更したら
build_runnerを実行してください。 - Dart は実行時に
Typeのサブタイプを検査できないため、typesはすべてのスーパータイプを列挙します。 @Beanの定義は、宣言された戻り値の型だけでなく、本体が返すクラスで登録されます。@EventListenerの条件は SpEL 文字列ではなく関数です。