
# @ConfigurationProperties

`@ConfigurationProperties` クラスは、あるプレフィックスの下のすべてのプロパティを、型付きの一つのオブジェクトにまとめます。各フィールドは、フィールド名をケバブケースにしたキーからバインドされ (`maxBasketSize` は `shop.max-basket-size` を読みます)、フィールドの型に変換され、オブジェクトは他の Bean と同じように注入されます。

アノテーションは `spring_core_dart` にあり、`spring_boot_dart` が起動時にバインドとバリデーションを行います。

## 使う理由

`@Value` は一つのキーを読みます。10 個の設定を持つ機能には、それらを列挙し、型を付け、チェックする場所が必要です。

- キーは、デフォルトと `///` コメント (エディターが補完として表示します) とともに、一つのクラスにまとまります。
- 値は起動時に一度だけ変換されます。`30s` は `Duration` に、`10MB` は `DataSize` になります。
- 誤った値は、本番で後から失敗するのではなく、キーの名前とともに起動を止めます。
- クラスは Bean なので、サービス、コントローラー、ウィジェットがそれを注入できます。

## 例

```yaml
# lib/resources/application.yml
shop:
  title: NEON Books
  max-basket-size: 20
  checkout-timeout: 30s
  currencies: [EUR, USD]
  payment:
    provider: stripe
    timeout: 5s
  servers:
    - name: eu
      url: https://eu.neon.books
    - name: us
      url: https://us.neon.books
  headers:
    X-Shop: neon
  warehouses:
    berlin:
      capacity: 5000
      open: true
```

```dart
@ConfigurationProperties('shop')
@Validated()
class ShopProperties {
  /// The shop's name, shown in the header.
  @NotBlank()
  String title = 'Shop';                              // shop.title

  /// The most books in one basket.
  @Min(1)
  @Max(100)
  int maxBasketSize = 10;                             // shop.max-basket-size

  Duration checkoutTimeout = const Duration(minutes: 1);
  List<String> currencies = ['EUR'];                  // カンマ区切りのリスト、または [0]、[1]
  Payment payment = Payment();                        // ネストしたオブジェクト
  List<Server> servers = [];                          // オブジェクトのリスト
  Map<String, String> headers = {};                   // 値のマップ
  Map<String, Warehouse> warehouses = {};             // オブジェクトのマップ
}

class Payment {
  String provider = 'none';
  Duration timeout = const Duration(seconds: 10);
}

class Server {
  String name = '';
  String url = '';
}

class Warehouse {
  int capacity = 0;
  bool open = false;
}

@Service()
class Shipping {
  Shipping(this.shop);

  final ShopProperties shop;

  int capacityOf(String city) => shop.warehouses[city]?.capacity ?? 0;
}
```

`@EnableConfigurationProperties` も `@ConfigurationPropertiesScan` も不要です。アノテーションがクラスを Bean にし、ジェネレーターがそのイントロスペクションを書き出します。フィールドはゲッターやセッターなしで直接バインドされます。

## パラメーター

| パラメーター | デフォルト | 意味 |
|---|---|---|
| `prefix` | 必須 | キーに共通する先頭部分。正規形で書く: `shop`、`my-app`、`spring.main`。`''` はプレフィックスのないキーをバインドする |
| `name` | クラスから | Bean の名前 |
| `ignoreUnknownFields` | `true` | `false` にすると、プレフィックスの下で何にもバインドされないキーがあれば起動を止める: `The elements [db.urll] were left unbound.` OS の環境変数はチェックされない |
| `ignoreInvalidFields` | `false` | `true` にすると、値を変換できないとき、失敗する代わりにフィールドのデフォルトを保つ |

## バインドのルール

- キーが設定されていなければ、**フィールドはデフォルトを保ちます**。
- **緩い名前:** `shop.max-basket-size`、`shop.maxBasketSize`、`--shop.max-basket-size=...`、`SHOP_MAX_BASKET_SIZE` はどれも `maxBasketSize` をバインドします。
- **ネストしたオブジェクト**は、より深いキー (`shop.payment.timeout`) からバインドされます。nullable なネストしたオブジェクトは、そのキーが一つも設定されていなければ `null` のままです。
- **リストは丸ごと**、それを持つ最も優先度の高いソースから来ます。カンマ区切りの値、YAML のリスト、またはインデックス付きのキー (変数では `APP_HOSTS_0_`) です。`--app.hosts[0]=x` は、ファイルの 3 要素のリストを置き換えます。最初の要素を変更するのではありません。インデックスは 0 から始まり、抜けがあってはいけません。
- **マップのエントリーは**ソースをまたいで**マージされ**、キーごとに優先度の高いソースが勝ちます。キーは書かれた形のまま保たれます (`X-Shop`)。`[x.y]` はドットを保ちます。スカラー値では、名前の残りの部分がキーになります (`app.headers.a.b=1` はキー `a.b` になります)。
- **要素、キー、値は**変換サービスを通して**変換されます**: `List<Duration>`、`Map<String, int>`、緩い名前による列挙型。変換できない値は起動を止めます: `app.ports[0]: failed to convert to int (was "x")`。
- 値の中の**プレースホルダー**は解決されます。解決できないものは書いたとおりに残ります。`String` フィールドに `@RawValue()` を付けると、`${...}` を書いたとおりに保ちます (受け取り側が自分で解決するテンプレート用)。

## イミュータブルなクラス: コンストラクターバインド

唯一のコンストラクターがパラメーターを持つクラスは、そのコンストラクターを通してバインドされます。ネストしたクラスも同様です。これはイミュータブルなクラスに対する Spring Boot 3 のデフォルトです。

```dart
@ConfigurationProperties('pool')
class PoolProperties {
  const PoolProperties(
    this.url, {                                   // 必須: pool.url を設定しなければならない
    @DefaultValue('10') required this.maxSize,    // 設定されていなければ 10
    this.timeout = const Duration(seconds: 5),    // Dart のデフォルトも使える
    this.owner,                                   // nullable: 設定されていなければ null
    this.replicas = const [],                     // pool.replicas[0].host=...
  });

  final String url;
  final int maxSize;
  final Duration timeout;
  final String? owner;
  final List<Endpoint> replicas;
}
```

プロパティのないパラメーターは、`@DefaultValue`、なければ Dart のデフォルト、それもなければ nullable の場合は `null` を取ります。そのどれもない必須の非 nullable パラメーターは起動を止めます: `pool.url: no value bound for the required constructor parameter 'url' of PoolProperties`。ないコレクションは空になり、ないネストしたオブジェクトはそれ自身のデフォルトで生成されます。

## その他のアノテーション

| アノテーション | 付ける場所 | 効果 |
|---|---|---|
| `@Name('import')` | フィールドまたはコンストラクターのパラメーター | 別のキーからバインドする。キーが Dart のキーワード (`import`、`default`) の場合に必要 |
| `@DefaultValue('10')` | コンストラクターのパラメーター | キーが設定されていないときに使う値。プロパティの値として書く |
| `@DurationUnit(ChronoUnit.seconds)` | `Duration` フィールド | 単なる数値をその単位で読む (`app.timeout=60` は 60 秒)。月と年はない |
| `@DataSizeUnit(DataUnit.megabytes)` | `DataSize` フィールド | 単なる数値をその単位で読む |
| `@RawValue()` | `String` フィールド | プレースホルダーを解決しない |
| `@Range(min, max)`、`@WarnValues([...], 'why')`、`@PropertyValues([...])` | フィールド | エディター用のメタデータのための範囲、警告する値、許可する値 |

## @Bean メソッドに付ける

`@Bean` メソッドに `@ConfigurationProperties('pool')` を付けると、メソッドが返すオブジェクトをバインドします。他のパッケージのクラスでもかまいません (ジェネレーターがそのイントロスペクションを書き出します)。メソッドに `@Validated()` を付けると、それを検証します。

```dart
@Configuration()
class PoolConfiguration {
  // Spring について何も知らないライブラリのクラスに pool.* をバインドする。
  @Bean()
  @ConfigurationProperties('pool')
  PoolSettings poolSettings() => PoolSettings();
}
```

## 起動時のバリデーション

`@Validated()` を付けると、値がバインドされた後に制約アノテーションがチェックされます。不正な値は、キーを示すレポートとともに起動を止めます。

```text
Binding to target properties under 'shop' failed:

  - shop.max-basket-size: must be greater than or equal to 1 (was "0")
```

バインドされたオブジェクトを検証する方法は 3 つあります。

- クラスに `@Validated()`: その制約 (`@NotBlank()`、`@Min`、`@Size`...) がチェックされます。
- `configurationPropertiesValidator` という名前の `Validator` Bean は、それが対応するすべてのバインド済みオブジェクトをチェックします。
- それ自身が `Validator` であるプロパティクラスは、自分自身を検証します。

`@ConfigurationProperties` クラスの `@Validated()` は、メソッドバリデーションではなく「バインド後に検証する」ことを意味します。Flutter アプリでは `@Size` は `@SizeConstraint` という名前です。[バリデーション](../spring-core-dart/validation/index.md) を参照してください。

## Binder: クラスのない構造

`Binder` は、設定の一部を必要に応じてある型にバインドします。ルールは同じです。設定を読むスターターのように、リストやマップを一度だけ必要とするコードのためのものです。

```dart
final binder = Binder.get(environment);

// YAML のリスト、インデックス付きのキー、カンマ区切りのリスト: どれも List になる。
final hosts = binder
    .bind('shop.hosts', const ListType(ClassType<String>()))
    .orElse(const []);

final limits = binder
    .bind('shop.limits', const MapType(ClassType<String>(), ClassType<int>()))
    .orElse(const {});
```

`BindResult` には `get`、`isBound`、`orElse`、`orElseGet`、`orElseThrow`、`ifBound`、`map` があります。`bind` に渡した `BindHandler` は、各プロパティについて通知を受けます (`onStart`、`onSuccess`、`onFailure`、`onFinish`)。その `onFailure(name, error)` は失敗を数えるかどうかを返します (`false` はプロパティをバインドしないままにします)。

## エディター用のメタデータ

ジェネレーターは、クラスのキー、型、デフォルト、`///` コメントを `lib/spring_gen/spring_metadata.json` に書き出します。`spring-configuration-metadata.json` に当たるものです。手で書くものは何もありません。マップのフィールドは `headers.*`、クラスのリストは `servers[*].url` として列挙されます。[メタデータ](../spring-core-dart-generator/metadata.md) を参照してください。

## Spring (Java) との対応

```java
@ConfigurationProperties("shop")
@Validated
public class ShopProperties {
  @NotBlank private String title = "Shop";
  @Min(1) @Max(100) private int maxBasketSize = 10;
  // getters and setters
}

@SpringBootApplication
@ConfigurationPropertiesScan
class NeonBooks { ... }
```

違い:

- `@EnableConfigurationProperties` も `@ConfigurationPropertiesScan` もなく、ゲッターもセッターもありません。
- コンストラクターで非 nullable のスカラーがないと起動が止まります。Spring は `null` を渡します。
- コンストラクターバインドは、public な生成的コンストラクターが一つだけで、それがパラメーターを持つクラスに限られます。複数の中から一つを選ぶ `@ConstructorBinding` はありません。
- `BindHandler.onFailure` は、代わりの値ではなく、失敗を数えるかどうかを返します。エラーは集められ、まとめて報告されます。

## 関連項目

- [spring_core_dart の @ConfigurationProperties](../spring-core-dart/config/configuration-properties.md)
- [コマンドライン、環境変数、--dart-define](configuration/sources.md)
- [バリデーション](../spring-core-dart/validation/index.md)
- [型変換](../spring-core-dart/conversion/index.md)
- [@Value](../spring-core-dart/config/value.md)
