条件

条件は、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 { /* ... */ }

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 は数えない
@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 と同じく、構成クラスが読まれるときに、クラスごとに次の順序で判断されます。

  1. アプリケーション自身のクラス (スキャンされた @Component や @Import されたクラスも、それぞれの位置で数えられます)。
  2. 自動構成。その順序 で。

その時点で、それより前のすべてのクラスは @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) との対応

名前もパラメーターも同じです。違い:

関連項目