
# 設定ファイル

アプリケーションは設定を `lib/resources/` の `application.yml`、`application.yaml`、`application.properties` に置きます。このフォルダーは Spring が*クラスパス*と呼ぶもので、`resources:` プレフィックスはその中を指します。有効な [プロファイル](profiles.md) ごとに `application-{profile}.*` も読まれ、その値は通常のファイルより優先されます。

`pubspec.yaml` に宣言するものは何もありません。ジェネレーターは `lib/resources/` のすべてのファイルを生成コードに埋め込むため、ファイルは Dart VM でも、AOT の実行ファイルでも、Flutter でも、Web でも同じように動きます。1 MB を超えるファイルは埋め込まれません (ビルドが警告します)。Flutter のアセットとして、またはプログラムの隣のファイルとして配布してください。

## 使う理由

アプリケーションごとに一つのファイルと、プロファイルごとに一つのファイルにすれば、デフォルトは一か所にまとまり、差分は小さく保てます。プログラムの隣のファイル (`./application.yml`、`./config/`) を使えば、運用担当者は新しいビルドなしでサーバーやデスクトップアプリの設定を変えられます。Spring Boot と同じく、それらはパッケージに含まれたものより優先されます。

## 例

```text
lib/
  main.dart
  resources/
    application.yml               # 常に読まれる
    application-dev.yml           # dev プロファイルで読まれる
    application-prod.properties   # prod で読まれる (形式は混在できる)
    config/
      application.yml             # これもパッケージに含まれ、resources:/ より優先される
```

2 つの形式は同じことを表します。

```yaml
# lib/resources/application.yml
spring:
  application:
    name: shop
shop:
  title: NEON Books
  url: http://localhost:8080
  max-basket-size: 20
```

```properties
# lib/resources/application.properties
spring.application.name=shop
shop.title=NEON Books
shop.url=http://localhost:8080
shop.max-basket-size=20
```

好きな方を使うか、両方を使ってください。一つのロケーションに両方がある場合、`.properties` が `.yml` より、`.yml` が `.yaml` より優先されます。

## 値の形

どちらの形式も、最終的には同じフラットなキーと値のリストになります。

| 形 | YAML | `.properties` |
|---|---|---|
| ネストしたキー | `shop:` / `  payment:` / `    provider: stripe` | `shop.payment.provider=stripe` |
| リスト | `hosts:` / `  - eu.neon.books` / `  - us.neon.books`、または `hosts: [eu, us]` | `shop.hosts[0]=eu.neon.books`、`shop.hosts=eu,us`、または `shop.hosts[]=eu, us` |
| オブジェクトのリスト | `servers:` / `  - name: eu` / `    url: https://eu.neon.books` | `shop.servers[0].name=eu` |
| マップ | `prices:` / `  book: 12` / `  e-book: 8` | `shop.prices.book=12` |
| ドットを含むマップのキー | `"[X-Shop.Id]": neon` (引用符付き) | `shop.headers[X-Shop.Id]=neon` |
| 空の値 | `banner:`、`motto: ~`、または `null` | `shop.banner=` |

- YAML のリストはインデックス付きのキー (`shop.hosts[0]`、`shop.hosts[1]`) になります。単なるキー `shop.hosts` は設定されないため、`@Value(r'${shop.hosts}')` は何も見つけません。一つのキーを読むコードには、カンマ区切りのリスト (`hosts: eu,us`) を書いてください。Spring Boot も同じ動作です。
- インデックスは 0 から始まり、抜けはありません。
- `String` でない対象では、空の値は「設定されていない」とみなされ、デフォルトが適用されます。

## 一つのファイル内の複数のドキュメント

一つのファイルに複数のドキュメントを入れられます。YAML は `---` で、`.properties` は `#---` (または `!---`) の行で区切ります。後のドキュメントが前のドキュメントを上書きします。ドキュメントは一部のプロファイルやクラウドプラットフォームに限定できるため、一つのファイルに開発用の値と本番用の上書きを入れられます。

```yaml
shop:
  url: http://localhost:8080
---
spring:
  config:
    activate:
      on-profile: prod
shop:
  url: https://neon.books
```

```properties
shop.url=http://localhost:8080
#---
spring.config.activate.on-profile=prod
shop.url=https://neon.books
```

`.properties` の区切りは行全体です。行頭の `#---` または `!---` で、ハイフンはちょうど 3 つ、その後には空白かタブしか置けません。同じプレフィックスのコメントの直後では区切りとみなされません (空行を入れるか、`!---` を使ってください)。前の行が `\` で続いている場合も同様です。コメントは区切りの直後ではなく、`on-profile` の行の下に置いてください。Spring Boot はそうしたドキュメントを前のドキュメントに結合しますが、このローダーは結合しません。

`on-profile` の式と `on-cloud-platform` については [プロファイル](profiles.md#一部のプロファイルやプラットフォーム用のドキュメント) を参照してください。

## `.properties` だけのもの

```properties
# キーと値の区切りは =、:、または空白。
shop.name=NEON
shop.city: Berlin
shop.country Germany

# \ で終わる行は続く。次の行の先頭の空白は取り除かれる。
shop.welcome=Welcome to NEON Books, \
             the shop of books.

# エスケープ: \t \n \r \f \uXXXX。キーの中では \=、\:、"\ " がそれらの文字を保つ。
shop.key\=with\:colon=yes

# コメントは行頭の # または ! で始まる。途中の # は値の一部。
shop.color=#673AB7
```

- ファイルは **UTF-8** として読まれるため、`Grüße` はそのまま書けます。Spring Boot は ISO-8859-1 で読みます。正しい UTF-8 でないファイルは、そのファイルを示す `ConfigDataLoadException` で起動を失敗させます。別のエンコーディングは、ファイルを指定する場所で指定します: `resources:legacy.properties[encoding=iso-8859-1]` (UTF-8、ISO-8859-1、US-ASCII が使え、Java の名前と `latin1` のような別名も使えます)。
- キーが二度現れた場合は、最後の値が使われます。値の末尾の空白は保たれます。

## YAML だけのもの

```yaml
# アンカーはブロックを共有する。マッピング自身のキーは、マージされたキーより優先される。
defaults: &defaults
  timeout: 5s
  retries: 3
shop:
  eu:
    <<: *defaults
    url: https://eu.neon.books
  us:
    <<: *defaults
    retries: 5
  color: '#673AB7'   # 引用符付き: 空白の後の # はコメントを始める
```

YAML は YAML 1.2 として読まれます (Spring Boot の SnakeYAML は 1.1 で読みます)。

- `on`、`off`、`yes`、`no` は文字列のままです。`bool` が期待される場所では `bool` に変換でき、`off` 定数を持つ列挙型にも `off` が使えます (`spring.main.banner-mode: off`)。
- `0777` は 8 進数ではなく数値の 777 です。
- 重複したキーや不正な YAML は、その行と列を示して起動を失敗させます。

## ファイルが検索される場所

ロケーションは 2 つのグループに分かれます。2 番目のグループは最初のグループを完全に上書きします。

| グループ | ロケーション (優先度の低い順) | 内容 |
|---|---|---|
| 1、パッケージに含まれるもの | `resources:/`、`resources:/config/` | `lib/resources/` と `lib/resources/config/`。ジェネレーターが埋め込む |
| 2、プログラムの隣 | `file:./`、`file:./config/`、`file:./config/*/` | 作業ディレクトリ、`./config/`、そのサブディレクトリ (アルファベット順) |

そのため、サーバーのバイナリの隣の `./application.properties` は、パッケージに含まれた `application-prod.properties` より優先されます。グループの中では、後のロケーションが優先され、プロファイルのファイルが通常のファイルより優先され、最後に有効になったプロファイルが優先されます。デフォルトのロケーションはすべて任意です。

テスト (`springBootTest`) では、`test/resources/` が `lib/resources/` より前に来るため、`test/resources/application-test.yml` が見つかり、そこにあるファイルはパッケージ内の同じパスのファイルを置き換えます。

## 検索を変える

次のキーは、どのファイルを検索するかを変えます。これらは、ファイルが読まれる前から存在するソースからだけ読まれます: コマンドライン、`--dart-define`、環境変数、`SPRING_APPLICATION_JSON`、デフォルトプロパティ。設定ファイルでは設定できません。

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.config.name` | カンマ区切りのリスト | `application` | ファイルのベース名。`application,shop` は `application*.*` と `shop*.*` を読む。後の名前が優先される |
| `spring.config.location` | ロケーション | 上記の 2 つのグループ | デフォルトのロケーションを置き換える。`,` はグループを区切り、`;` はロケーションを一つのグループにまとめる |
| `spring.config.additional-location` | ロケーション | なし | ロケーションの後に検索されるグループ。そのためそれらより優先される |
| `spring.config.on-not-found` | `fail` / `ignore` | `fail` | `ignore` はすべてのロケーションを任意にする。それ以外の値は起動を失敗させる |

```bash
# パッケージ内のファイルと、それより優先される /etc/shop/ だけ。
dart run bin/main.dart --spring.config.location=optional:resources:/,file:/etc/shop/

# 通常のロケーションに加えて、その上にもう一つのファイル。
dart run bin/main.dart --spring.config.additional-location=file:./override.yml

# application.yml の代わりに shop.yml を読む。
SPRING_CONFIG_NAME=shop dart run bin/main.dart
```

ここに書くロケーションには、[インポート](imports.md#ロケーションの形式) のすべての形式が使えます: `optional:`、`/` で終わるディレクトリ、ワイルドカード、拡張子のヒント (`file:./conf[.yml]`)、エンコーディングのヒント、`configtree:`。

## ファイルがない場合

- 存在しない必須のファイルは起動を失敗させます: `Config data resource 'file [./override.yml]' via location 'file:./override.yml' does not exist`。対処は `prefix it with 'optional:'` です。
- 存在しない必須のディレクトリや、一致するもののないワイルドカードも失敗させます。
- `optional:` は一つのロケーションを任意にします。`spring.config.on-not-found=ignore` はすべてを任意にします。
- 名前で検索されるプロファイル版 (`application-dev.yml`) は常に任意です。
- Spring Boot と同じく、プロファイル版のどれかが見つかれば、そのロケーションは見つかったものとみなされます。

## SpringApplication を使わずに

この作業を行うクラスは `ConfigDataEnvironment` です。`spring_core_dart` だけを使うプログラムやツールは、これを自分で実行します。

```dart
// lib/resources/application.yml、./application.properties、プロファイル、インポートを読む。
Future<void> main(List<String> args) async {
  final environment = StandardEnvironment()
    ..propertySources.addFirst(SimpleCommandLinePropertySource(args));
  await ConfigDataEnvironment(environment).processAndApply();
  print(environment.getProperty('shop.url'));
}
```

そのコンストラクターは、`resourceLoader` (アセットやメモリ上のファイル用)、`loaders` (形式。デフォルトは `PropertiesPropertySourceLoader` と `YamlPropertySourceLoader`。独自の `PropertySourceLoader` で形式を追加できます)、`defaultLocations`、`additionalProfiles` を受け取ります。`processAndApplySync()` は同期版です。

## Spring (Java) との対応

ファイル名、ロケーション、ルールは Spring Boot と同じです。ただし:

- `classpath:` の代わりに `resources:` を使い、設定ロケーションでの `resources*:` やワイルドカード検索はありません。
- `.properties` ファイルは UTF-8 です。`PropertiesPropertySourceLoader(encoding: latin1)` で Spring Boot の ISO-8859-1 になります。
- YAML は 1.1 ではなく 1.2 です。
- `application.xml` はありません: `spring.config.import=x.xml` は起動を失敗させます ("XML properties files are not supported")。
- `;` のグループでは、エントリーの前後の空白は取り除かれ、空のエントリーはスキップされます。

## 関連項目

- [プロファイル](profiles.md)
- [インポート](imports.md)
- [概要: どのソースが優先されるか](index.md)
- [ジェネレーター: リソース](../../spring-core-dart-generator/resources.md)
- [リソース](../../spring-core-dart/resources/index.md)
