
# 条件

条件は、Bean、`@Bean` メソッド、あるいは構成クラス全体を、そもそも登録するかどうかを決めます。`spring_boot_dart` は Spring Boot の `@ConditionalOn...` アノテーションを提供します。アプリケーションが独自の Bean を宣言したときに自動構成が身を引くのも、プロパティで機能を有効・無効にできるのも、これらのおかげです。

## 使う理由

スターターは、デフォルトを強制せずに提供しなければなりません。アプリケーションが持っていないときだけ `Cache` を登録し、レジストリがあるときだけメトリクスのエクスポーターを登録し、プロパティが指定したときだけ機能を登録します。アプリケーションも同じアノテーションを使い、コードに `if` を書かずに環境ごとの Bean を選べます。

## 例

```dart
@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](../spring-core-dart/beans/conditional.md) を参照)。Actuator は `@ConditionalOnEnabledHealthIndicator` と `@ConditionalOnEnabledInfoContributor` を追加します。

Java の `@ConditionalOnClass` に対応するものはありません。Dart のプログラムは実行時にクラスが存在するかを調べられず、スターターの依存関係は常に存在するためです。

## @ConditionalOnProperty

| パラメーター | デフォルト | 意味 |
|---|---|---|
| `name` (位置引数) または `.names([...])` | 必須 | プロパティ。または、すべて一致しなければならない複数のプロパティ |
| `prefix` | `''` | 各名前の前に付ける。`.` がなければ追加される |
| `havingValue` | `null` | 必要な値。大文字小文字を区別せずに比較する。`null` または空: `false` 以外の任意の値 |
| `matchIfMissing` | `false` | 設定されていないプロパティを一致とみなすかどうか |

```dart
// 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` | 設定されていないプロパティを一致とみなすかどうか |

```dart
// デフォルトで有効。app.audit.enabled=false で無効になる。
@Bean()
@ConditionalOnBooleanProperty('app.audit.enabled', matchIfMissing: true)
Audit audit() => Audit();
```

## @ConditionalOnExpression

`#{...}` の有無にかかわらず SpEL 式を受け取ります。`${...}` のプレースホルダーは先に置き換えられます。`environment` と、それまでに登録された Bean を参照できます。`null` の結果は `false` とみなされ、それ以外の真偽値でない結果は起動を止めます。引数がなければ常に一致します。

```dart
// キャッシュが有効 (デフォルト) で、ショップが EU で運営されている場合だけ。
@Bean()
@ConditionalOnExpression(r"${app.cache:true} and '${app.mode}' == 'eu'")
Cache cache() => Cache();
```

## @ConditionalOnResource

すべてのロケーションが存在しなければなりません。ロケーションは、プレースホルダーが置き換えられた後、他のリソースと同じように解決されます (`resources:` は `lib/resources/`、`file:` はファイルシステム)。

```dart
// 運用担当者が証明書をマウントした場所でだけ 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` は検出を無効にします)。検出の表は [プロファイル](configuration/profiles.md#クラウドプラットフォーム) にあります。

## @ConditionalOnPrimaryIsolate

Bean をアプリケーションのプライマリ isolate にだけ登録します。プライマリ isolate は最初の isolate で、Web サーバーが [isolate のプール](../spring-boot-starter-web/server/isolates.md) を動かす (`server.isolates.count`) のでなければ、唯一の isolate です。

プールでは、すべての isolate が自分の Bean でアプリケーション全体を実行します。この条件は、isolate ごとに一つではなく、アプリケーションに一つだけ存在しなければならないものに付けてください。キューをポーリングする Bean、夜間レポートを送る Bean、データを移行する Bean などです。

```dart
@Component()
@ConditionalOnPrimaryIsolate()
class NightlyReport { /* ... */ }
```

- プールがなければ常に一致するので、アプリケーションがプールを持つ前に Bean に付けておいてもコストはかかりません。
- **この条件の付いた Bean は、他の isolate には存在しません。** それをコンストラクターで受け取る Bean はそこで失敗し、その isolate は起動しません。両方に条件を付けるか、依存を null 許容型で受け取ってください。
- この条件の付いた `@RestController` は、最初の isolate でだけマッピングされます。別の isolate が受け取ったリクエストは、ハンドラーが見つかりません。
- すべての isolate が必要とする Bean の中の一つのステップには、`IsolateInfo` を注入して `isolate.primary` を調べます ([isolate](../spring-core-dart/isolates/index.md#isolateinfo) を参照)。
- 他の isolate がその Bean の知っていることを必要とするときは、それを `PrimaryIsolateHandler` にして、`primaryIsolate.ask(...)` で問い合わせます ([最初の isolate に問い合わせる](../spring-core-dart/isolates/primary-isolate.md) を参照)。
- `@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 以降と同じく、どちらにも数えられません。

```dart
@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. 自動構成。[その順序](auto-configuration.md#登録の順序) で。

その時点で、それより前のすべてのクラスは `@Bean` メソッドを登録し、インポートした `BeanRegistrar` や `ImportBeanDefinitionRegistrar` を実行し終えているため、そのいずれの方法で登録された Bean も数えられます。これが、Bean の条件を自動構成に置くべき理由です。そこでは常にアプリケーションの Bean が見えます。アプリケーションのクラスでは、Spring と同じく、探している Bean を持つクラスより前に宣言されたコンポーネントが先に判断されます。

## クラスに付ける

構成クラスに付けた条件は、そのクラス、その `@Bean` メソッド、そのインポートをまとめて、全部か無しかで判断します。スキップされたクラスはレジストラーを実行せず、それが選択するものも登録されません。自分がインポートしたクラスが定義する Bean を探す条件を持つクラスは、登録されたままです (Spring Boot の `PooledDataSourceConfiguration` のパターン)。その `@PropertySource` は、Spring と同じく解析中に読まれるため、いずれにせよ読み込まれます。

## 条件評価レポート

Bean がなぜあるのか、あるいはないのかを知るには、`--debug` (または `debug=true`、`DEBUG=true`) 付きで起動します。

```bash
dart run bin/main.dart --debug
```

`ConditionEvaluationReport` が、リフレッシュの後、または起動の失敗の後に INFO でログに出されます。一致したもの (登録された。一致した条件付き) と一致しなかったもの (スキップされた。一致しなかった条件付き) が列挙されます。構成クラスの条件は、そのキーのもとに列挙されます。`--debug` はフレームワークのロガーも debug にします ([ログレベル](logging-levels.md) を参照)。

## Spring (Java) との対応

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

- `@ConditionalOnBean(annotations: [Service])` は、メタアノテーションではなく、まさにそのアノテーションクラスに一致します。
- `@ConditionalOnClass`、`@ConditionalOnWebApplication`、`@ConditionalOnJava` はありません。
- `@ConditionalOnPrimaryIsolate` は、このフレームワーク独自のものです。
- レポートは各条件とそれが一致したかどうかを示しますが、Spring Boot の詳しいメッセージ (`found bean 'x'`) はありません。

## 関連項目

- [自動構成とスターター](auto-configuration.md)
- [isolate](../spring-core-dart/isolates/index.md)
- [@Conditional](../spring-core-dart/beans/conditional.md)
- [@Profile](../spring-core-dart/beans/profile.md)
- [プロファイル](configuration/profiles.md)
