
# 外部設定

設定とは、コードは同じままで、場所によって変わる値のことです。サーバーの URL、ポート、タイムアウト、機能のスイッチ、ログレベルなどです。`spring_boot_dart` はそれらをコードの外から読むため、一つのビルドがノート PC でも、テストでも、本番でも、それぞれの値で動き、何も再コンパイルしません。

これは Spring Boot の *Externalized Configuration* です。ファイル名、キー、ルールは Spring Boot のものなので、Spring プロジェクトの設定はたいていそのまま動きます。

## 使う理由

コードに書いた設定を変えるには、新しいビルドが必要です。設定から読む値は、プログラムを実行する人が変えられます。バイナリの隣にファイルを置く運用担当者、環境変数を持つコンテナ、コマンドラインのオプションを使う CI のジョブ、`--dart-define` を使う Flutter のビルドなどです。どれが優先されるかは Spring Boot のルールが決めるため、`lib/resources/application.yml` に妥当なデフォルトを入れて出荷し、どのキーでも外から上書きできます。

## 例

同じキーを 5 つの場所から。最も優先度の高いソースが勝ちます。

```yaml
# lib/resources/application.yml: プログラムとともに出荷される
shop:
  url: http://localhost:8080
```

```yaml
# lib/resources/application-prod.yml: prod プロファイルで読まれる
shop:
  url: https://neon.books
```

```bash
dart run bin/main.dart                                   # http://localhost:8080
dart run bin/main.dart --spring.profiles.active=prod     # https://neon.books
SHOP_URL=https://staging.neon.books dart run bin/main.dart   # 環境変数はファイルより優先される
dart run bin/main.dart --shop.url=http://127.0.0.1:9000      # コマンドラインはすべてより優先される
```

```dart
// どの Bean も、ソースにかかわらず同じ方法で読む。
@Service()
class Links {
  Links(@Value(r'${shop.url}') this.url);

  final String url;
}
```

## ソース

| ソース | どこから来るか | ページ |
|---|---|---|
| 設定ファイル | `lib/resources/`、`lib/resources/config/`、`./`、`./config/`、`./config/*/` の `application.properties`、`application.yml`、`application.yaml` | [設定ファイル](config-files.md) |
| プロファイルのファイルとドキュメント | `application-{profile}.*`、および `spring.config.activate.on-profile` を持つドキュメント | [プロファイル](profiles.md) |
| インポート | `spring.config.import`: 追加のファイル、ディレクトリ、設定ツリー、HTTP、パッケージ、アセット | [インポート](imports.md) |
| コマンドライン | `--key=value` | [コマンドライン、環境変数、--dart-define](sources.md) |
| 環境変数 | `SHOP_URL=...`。緩い名前で | [コマンドライン、環境変数、--dart-define](sources.md) |
| `--dart-define` | プログラムにコンパイルされる値 | [コマンドライン、環境変数、--dart-define](sources.md) |
| `SPRING_APPLICATION_JSON` | 変数またはプロパティの中の一つの JSON オブジェクト | [コマンドライン、環境変数、--dart-define](sources.md) |
| コード | `SpringApplication(defaultProperties:)`、`run(properties:)`、`EnvironmentPostProcessor` | [コマンドライン、環境変数、--dart-define](sources.md) |
| `@PropertySource` | 構成クラスで指定したファイル | [プロパティソース](../../spring-core-dart/config/property-source.md) |

## どのソースが優先されるか

複数のソースが同じキーを設定すると、最も優先度の高いものが勝ちます。高い順に:

1. `run(properties: ...)`、テストでは `springBootTest(properties: ...)` (テストの `dynamicProperties` はさらに上)。
2. コマンドライン引数 (`--shop.url=...`)。
3. `--dart-define` の値。
4. `SPRING_APPLICATION_JSON` (または `--spring.application.json`)。
5. OS の環境変数。Flutter アプリは、ビルドで有効にしない限りこれを読みません。
6. `${random.*}` の値。
7. 設定ファイル。次の順序で (上が優先):
   - コマンドラインまたは環境変数で指定した `spring.config.import`。
   - 次に `spring.config.additional-location`。
   - 次にロケーション: `file:./config/*/`、`file:./config/`、`file:./` が `resources:/config/`、`resources:/` より上。
   - 各グループの中では、プロファイルのファイルが通常のファイルより上で、最後に有効になったプロファイルが最も上。
   - インポートされたファイルはインポート元のファイルより上で、そのプロファイル版もインポート元のプロファイル版より上。
   - 一つのロケーションの中では、`.properties` が `.yml` より、`.yml` が `.yaml` より上。
   - 一つのファイルの中では、後のドキュメントが前のドキュメントより上。
8. `@PropertySource` のファイル。
9. `SpringApplication(defaultProperties: ...)`。

リストは常に、それを持つ最も優先度の高いソースから丸ごと来ます。`--shop.hosts[0]=local` はファイルの 3 つのホストを置き換えます。最初のホストを変更するのではありません。マップのエントリーはソースをまたいでマージされ、キーごとに優先度の高いソースが勝ちます。[@ConfigurationProperties](../configuration-properties.md) を参照してください。

## 設定が読まれるタイミング

設定は起動時に一度だけ、どの Bean も生成される前に読まれます。

1. コマンドライン、`--dart-define` の値、環境変数、コードのプロパティ、`${random.*}` がプロパティソースになります。
2. `EnvironmentPostProcessor.configDataOrder` より前に順序付けられた `EnvironmentPostProcessor` が実行されます (`SPRING_APPLICATION_JSON` はその一つです)。
3. 設定ファイルが読まれます: ロケーション、プロファイル、インポート、ドキュメント。これが `ConfigDataEnvironment` です。
4. その他の `EnvironmentPostProcessor` が実行されます。[名前が変わったプロパティ](sources.md#名前が変わったプロパティ) のチェックもその一つです。
5. `ApplicationEnvironmentPreparedEvent` が発行され、ログレベルが適用され、Bean が生成されます。

`runApplication` はファイルを同期的に読みます。非同期にしか読めないロケーション (HTTP、Flutter のアセット) には `runApplicationAsync` が必要です。Flutter アプリはいずれにせよこちらを使います。

設定ファイルを変更するには再起動が必要です。開発中は、[ホットリロード](../hot-reload.md) が新しい値でコンテキストを再起動します。

## エディターの補完

ジェネレーターは、Spring のコードを持つすべてのパッケージについて `lib/spring_gen/spring_metadata.json` を書き出します。その `@ConfigurationProperties` クラスのキーと、その `///` コメント、型、デフォルト、許可される値です。`dart run tool/spring_schema.dart <app>` (フレームワークのリポジトリにあります) は、アプリケーションとその依存関係のメタデータを YAML 言語サーバー用の JSON Schema に変換するため、`application*.yml` で補完とチェックが効きます。[メタデータ](../../spring-core-dart-generator/metadata.md) を参照してください。

## Spring (Java) との対応

これらのページの内容はすべて Spring Boot の *Externalized Configuration* に従っており、主な違いは次のとおりです。

- `lib/resources/` がクラスパスで、(`classpath:` ではなく) `resources:` と書きます。
- `--dart-define` の値は、コマンドラインのすぐ下にある独自のソースです。Java に対応するものはなく、最も近いのは `-Dkey=value` です。
- `.properties` ファイルは ISO-8859-1 ではなく UTF-8 です。
- `env:` のインポート、XML のプロパティファイル、Spring Cloud Config のクライアントはありません。HTTP のインポート (`spring.config.import=https://...`) は、非同期の起動で使えます。

すべての違いは [Spring との違い](../differences.md) にあります。

## 関連項目

- [設定ファイル](config-files.md)
- [プロファイル](profiles.md)
- [インポート](imports.md)
- [コマンドライン、環境変数、--dart-define](sources.md)
- [@ConfigurationProperties](../configuration-properties.md)
- [Environment](../../spring-core-dart/config/environment.md)
- [プレースホルダー](../../spring-core-dart/config/placeholders.md)
