条件
条件は、Bean、@Bean メソッド、あるいは構成クラス全体を、そもそも登録するかどうかを決めます。spring_boot_dart は Spring Boot の @ConditionalOn... アノテーションを提供します。アプリケーションが独自の Bean を宣言したときに自動構成が身を引くのも、プロパティで機能を有効・無効にできるのも、これらのおかげです。
使う理由
スターターは、デフォルトを強制せずに提供しなければなりません。アプリケーションが持っていないときだけ Cache を登録し、レジストリがあるときだけメトリクスのエクスポーターを登録し、プロパティが指定したときだけ機能を登録します。アプリケーションも同じアノテーションを使い、コードに if を書かずに環境ごとの Bean を選べます。
例
@AutoConfiguration()
class SearchAutoConfiguration {
// アプリケーションが独自のものを宣言しない限り、デフォルトのインデックス。
@Bean()
@ConditionalOnMissingBean(SearchIndex)
SearchIndex searchIndex() => InMemoryIndex();
// search.enabled=false でない限り有効。
@Bean()
@ConditionalOnBooleanProperty('search.enabled', matchIfMissing: true)
SearchService searchService(SearchIndex index) => SearchService(index);
// 注入できる DataSource をアプリケーションがちょうど一つ持つときだけ。
@Bean()
@ConditionalOnSingleCandidate(DataSource)
SqlIndexer sqlIndexer(DataSource source) => SqlIndexer(source);
// Kubernetes の上でだけ。
@Bean()
@ConditionalOnCloudPlatform(CloudPlatform.kubernetes)
ClusterSync clusterSync() => ClusterSync();
}
条件の一覧
| アノテーション | 登録される条件 |
|---|---|
@ConditionalOnProperty |
プロパティが false 以外の値、または havingValue に設定されている |
@ConditionalOnBooleanProperty |
プロパティが true (または havingValue: false) |
@ConditionalOnExpression |
SpEL 式が true になる |
@ConditionalOnResource |
列挙したすべてのリソースが存在する |
@ConditionalOnCloudPlatform |
アプリケーションがあるプラットフォーム上で動いている |
@ConditionalOnPrimaryIsolate |
コードがアプリケーションの最初の isolate で動いている |
@ConditionalOnBean |
ある Bean がすでに登録されている |
@ConditionalOnMissingBean |
そうした Bean がまだ登録されていない |
@ConditionalOnSingleCandidate |
ある型の Bean をちょうど一つ注入できる |
spring_core_dart は @Profile と、独自の Condition を使う @Conditional を追加します (@Conditional を参照)。Actuator は @ConditionalOnEnabledHealthIndicator と @ConditionalOnEnabledInfoContributor を追加します。
Java の @ConditionalOnClass に対応するものはありません。Dart のプログラムは実行時にクラスが存在するかを調べられず、スターターの依存関係は常に存在するためです。
@ConditionalOnProperty
| パラメーター | デフォルト | 意味 |
|---|---|---|
name (位置引数) または .names([...]) |
必須 | プロパティ。または、すべて一致しなければならない複数のプロパティ |
prefix |
'' |
各名前の前に付ける。. がなければ追加される |
havingValue |
null |
必要な値。大文字小文字を区別せずに比較する。null または空: false 以外の任意の値 |
matchIfMissing |
false |
設定されていないプロパティを一致とみなすかどうか |
// feature.search=false でない限り、検索は有効。
@Service()
@ConditionalOnProperty('feature.search', matchIfMissing: true)
class SearchService {}
// app.feature.a と app.feature.b が両方とも "on" でなければならない。
@Bean()
@ConditionalOnProperty.names(['a', 'b'], prefix: 'app.feature', havingValue: 'on')
Feature feature() => Feature();
@ConditionalOnBooleanProperty
オン/オフのスイッチを書く素直な方法です。@ConditionalOnProperty と異なり、値は真偽値として読まれます。真偽値でない値は、「設定されている」とみなされるのではなく、起動を止めます。
| パラメーター | デフォルト | 意味 |
|---|---|---|
name または .names([...]) |
必須 | プロパティ。または、すべて一致しなければならない複数のプロパティ |
prefix |
'' |
各名前の前に付ける |
havingValue |
true |
一致する値。機能が無効のときにそれを置き換える Bean には false |
matchIfMissing |
false |
設定されていないプロパティを一致とみなすかどうか |
// デフォルトで有効。app.audit.enabled=false で無効になる。
@Bean()
@ConditionalOnBooleanProperty('app.audit.enabled', matchIfMissing: true)
Audit audit() => Audit();
@ConditionalOnExpression
#{...} の有無にかかわらず SpEL 式を受け取ります。${...} のプレースホルダーは先に置き換えられます。environment と、それまでに登録された Bean を参照できます。null の結果は false とみなされ、それ以外の真偽値でない結果は起動を止めます。引数がなければ常に一致します。
// キャッシュが有効 (デフォルト) で、ショップが EU で運営されている場合だけ。
@Bean()
@ConditionalOnExpression(r"${app.cache:true} and '${app.mode}' == 'eu'")
Cache cache() => Cache();
@ConditionalOnResource
すべてのロケーションが存在しなければなりません。ロケーションは、プレースホルダーが置き換えられた後、他のリソースと同じように解決されます (resources: は lib/resources/、file: はファイルシステム)。
// 運用担当者が証明書をマウントした場所でだけ TLS を使う。
@Bean()
@ConditionalOnResource(['file:./config/tls/cert.pem'])
TlsSettings tls() => TlsSettings.fromDirectory('./config/tls');
@ConditionalOnCloudPlatform
CloudPlatform.kubernetes、heroku、cloudFoundry、azureAppService、amazonEcs、nomad、sap のいずれかです。Spring Boot と同じく環境変数から検出されるか、spring.main.cloud-platform で強制されます (none は検出を無効にします)。検出の表は プロファイル にあります。
@ConditionalOnPrimaryIsolate
Bean をアプリケーションのプライマリ isolate にだけ登録します。プライマリ isolate は最初の isolate で、Web サーバーが isolate のプール を動かす (server.isolates.count) のでなければ、唯一の isolate です。
プールでは、すべての isolate が自分の Bean でアプリケーション全体を実行します。この条件は、isolate ごとに一つではなく、アプリケーションに一つだけ存在しなければならないものに付けてください。キューをポーリングする Bean、夜間レポートを送る Bean、データを移行する Bean などです。
@Component()
@ConditionalOnPrimaryIsolate()
class NightlyReport { /* ... */ }
- プールがなければ常に一致するので、アプリケーションがプールを持つ前に Bean に付けておいてもコストはかかりません。
- この条件の付いた Bean は、他の isolate には存在しません。 それをコンストラクターで受け取る Bean はそこで失敗し、その isolate は起動しません。両方に条件を付けるか、依存を null 許容型で受け取ってください。
- この条件の付いた
@RestControllerは、最初の isolate でだけマッピングされます。別の isolate が受け取ったリクエストは、ハンドラーが見つかりません。 - すべての isolate が必要とする Bean の中の一つのステップには、
IsolateInfoを注入してisolate.primaryを調べます (isolate を参照)。 - 他の isolate がその Bean の知っていることを必要とするときは、それを
PrimaryIsolateHandlerにして、primaryIsolate.ask(...)で問い合わせます (最初の isolate に問い合わせる を参照)。 @Scheduledメソッドに条件は要りません。デフォルトでは最初の isolate でだけ実行されます (spring.task.scheduling.isolates)。
Spring に対応するものはありません。JVM のスレッドは Bean を共有します。
@ConditionalOnBean と @ConditionalOnMissingBean
| 形式 | 必要とするもの (または、ないことを必要とするもの) |
|---|---|
@ConditionalOnBean() |
アノテーションを付けた @Bean メソッドの戻り値の型の Bean |
@ConditionalOnBean(DataSource) |
その型の Bean |
@ConditionalOnBean.named('dataSource') |
その名前の Bean |
@ConditionalOnBean.where(types: [...], names: [...], annotations: [...], search: ...) |
記述されたすべて: 各型の Bean を一つ、各名前、各アノテーションを持つ Bean を一つ |
@ConditionalOnMissingBean.where(..., ignored: [TestClock]) |
上と同じ。ただし ignored の型の Bean は数えない |
@ConditionalOnBeanは記述された Bean のすべてを必要とします。@ConditionalOnMissingBeanは、それらが一つも存在しないときに一致します。annotations:は、Bean のクラスまたは@Beanメソッドに付いた、まさにそのアノテーションクラスに一致します。メタアノテーションを付けた Bean は数えられません。search:はSearchStrategyです:all(このコンテキストとその親。デフォルト)、current(このコンテキストのみ)、ancestors(親のみ)。autowireCandidate: falseまたはdefaultCandidate: falseで宣言された Bean は、Spring Boot 3.4 以降と同じく、どちらにも数えられません。
@AutoConfiguration()
class HttpAutoConfiguration {
// アプリケーションが HttpClientSettings を持つ場合は登録されない。
@Bean()
@ConditionalOnMissingBean()
HttpClientSettings httpSettings() => HttpClientSettings();
// ここでは TestClock の Bean は Clock として数えない。
@Bean()
@ConditionalOnMissingBean.where(ignored: [TestClock])
Clock clock() => SystemClock();
}
@ConditionalOnSingleCandidate
@ConditionalOnBean は、ある型の Bean が複数あっても満たされますが、そのうち一つを注入しようとすると曖昧さで失敗します。@ConditionalOnSingleCandidate(DataSource) は注入がうまくいくことを確認します。候補が一つ、または複数の中に @Primary() が一つ、または @Fallback() でないものが一つ、のいずれかです。
Bean の条件が判断されるタイミング
Bean の条件は、それより前に登録されたものに依存します。Spring Boot の OnBeanCondition と同じく、構成クラスが読まれるときに、クラスごとに次の順序で判断されます。
- アプリケーション自身のクラス (スキャンされた
@Componentや@Importされたクラスも、それぞれの位置で数えられます)。 - 自動構成。その順序 で。
その時点で、それより前のすべてのクラスは @Bean メソッドを登録し、インポートした BeanRegistrar や ImportBeanDefinitionRegistrar を実行し終えているため、そのいずれの方法で登録された Bean も数えられます。これが、Bean の条件を自動構成に置くべき理由です。そこでは常にアプリケーションの Bean が見えます。アプリケーションのクラスでは、Spring と同じく、探している Bean を持つクラスより前に宣言されたコンポーネントが先に判断されます。
クラスに付ける
構成クラスに付けた条件は、そのクラス、その @Bean メソッド、そのインポートをまとめて、全部か無しかで判断します。スキップされたクラスはレジストラーを実行せず、それが選択するものも登録されません。自分がインポートしたクラスが定義する Bean を探す条件を持つクラスは、登録されたままです (Spring Boot の PooledDataSourceConfiguration のパターン)。その @PropertySource は、Spring と同じく解析中に読まれるため、いずれにせよ読み込まれます。
条件評価レポート
Bean がなぜあるのか、あるいはないのかを知るには、--debug (または debug=true、DEBUG=true) 付きで起動します。
dart run bin/main.dart --debug
ConditionEvaluationReport が、リフレッシュの後、または起動の失敗の後に INFO でログに出されます。一致したもの (登録された。一致した条件付き) と一致しなかったもの (スキップされた。一致しなかった条件付き) が列挙されます。構成クラスの条件は、そのキーのもとに列挙されます。--debug はフレームワークのロガーも debug にします (ログレベル を参照)。
Spring (Java) との対応
名前もパラメーターも同じです。違い:
@ConditionalOnBean(annotations: [Service])は、メタアノテーションではなく、まさにそのアノテーションクラスに一致します。@ConditionalOnClass、@ConditionalOnWebApplication、@ConditionalOnJavaはありません。@ConditionalOnPrimaryIsolateは、このフレームワーク独自のものです。- レポートは各条件とそれが一致したかどうかを示しますが、Spring Boot の詳しいメッセージ (
found bean 'x') はありません。