
# インポート

`spring.config.import` は、設定ファイルの中から、またはコマンドラインから、追加の設定を読みます。大きな設定を複数のファイルに分割したり、運用担当者が用意するもの (ローカルの上書き、マウントされたシークレット、設定サーバー上のファイル) を追加したりするのに使います。

## 使う理由

すべてを一つの `application.yml` に入れると、読みにくくなっていきます。インポートを使えば、関心ごとにファイルを分けつつ (`db.yml`、`themes/ocean.yml`)、アプリケーションからは一つのキーの集まりとして見えます。また、設定をその環境に結び付けます。ファイルとしてマウントされた Kubernetes のシークレットや、あるマシンにだけ存在する上書きファイルなどです。

## 例

```yaml
# lib/resources/application.yml
spring:
  config:
    import:
      - resources:db.yml                 # パッケージに含まれる。必須
      - optional:file:./local.yml        # プログラムの隣。なくてもよい
      - optional:configtree:/run/secrets/  # Kubernetes や Docker のシークレット
shop:
  title: NEON Books
```

```properties
# lib/resources/application.properties: 同じ内容
spring.config.import=resources:db.yml,optional:file:./local.yml,optional:configtree:/run/secrets/
shop.title=NEON Books
```

```yaml
# lib/resources/db.yml
db:
  url: postgres://localhost/shop
  pool-size: 5
```

```text
/run/secrets/db/password      → db.password=<the file's content>
```

## ロケーションの形式

同じ形式が `spring.config.import`、`spring.config.location`、`spring.config.additional-location` で使えます。

| 形式 | 読まれるもの | 備考 |
|---|---|---|
| `resources:db.yml` | `lib/resources/` のファイル。ジェネレーターが埋め込む | VM、AOT、Flutter、Web のどのビルドでも動く |
| `resources:config/` | `lib/resources/` のディレクトリ: その中の `application*` ファイル (または `spring.config.name` のもの) | その中でファイルが見つかったときだけ、見つかったとみなされる |
| `file:./local.yml` | ファイルシステムのファイル | Web では使えない |
| `file:./config/` | ディレクトリ: その `application*` ファイル | `/` で終わらなければならない |
| `file:./config/*/` | 各サブディレクトリ。アルファベット順 | `*` は一つで、最後のディレクトリとして。`file:./config/*/app.yml` は各サブディレクトリのそのファイルを読む |
| `local.yml` | 単なるパス: `file:` と同じくファイル。インポートでは、インポート元のファイルからの相対パス | `resources:` のファイルは、この方法で隣の `resources:` のファイルをインポートする |
| `optional:...` | 上記のいずれか。なくてもよい | ロケーション全体の前に付ける |
| `file:./conf[.yml]` | 既知の拡張子のないファイルを YAML として読む | ヒントは大文字小文字を区別せずに照合される |
| `file:./legacy.properties[encoding=iso-8859-1]` | そのエンコーディングの `.properties` ファイル | UTF-8、ISO-8859-1、US-ASCII (Java の名前と別名)。YAML は常に UTF-8 |
| `file:./legacy.conf[.properties][encoding=latin1]` | 両方のヒント。順序は問わない | |
| `configtree:/run/secrets/` | 設定ツリー: 各ファイルが一つのプロパティ | [設定ツリー](None#設定ツリー) を参照 |
| `configtree:/run/*/` | 各サブディレクトリを設定ツリーとして | |
| `https://cfg.example.com/shop.yml` | HTTP または HTTPS 経由のファイル | 非同期の起動のみ。[HTTP](None#http-経由で) を参照 |
| `package:shop_defaults/defaults.yml` | プログラムのパッケージ設定を通した、Dart パッケージのファイル | Web でも AOT の実行ファイルでも使えない |
| `asset:config/shop.yml` | Flutter のアセット | `spring_boot_starter_flutter` が必要。非同期に読まれる |
| `x;y` | グループ: 複数からなる一つのロケーション | 最初のエントリーが `optional:` なら任意。どれかのエントリーが何かを見つければ、見つかったとみなされる |

既知の拡張子 (`.properties`、`.yml`、`.yaml`) のないロケーションは、`/` で終わる (ディレクトリ) か、拡張子のヒントを持たなければなりません。他の形式には、`ConfigDataEnvironment(loaders:)` に渡す独自の `PropertySourceLoader` が必要です。

## 優先順位

- インポートされたファイルは、**それをインポートしたファイルを上書きします**。
- インポートされたファイルはそれ自身の `-{profile}` 版を持ち、それはインポート元のファイルのプロファイルのファイルより優先されます。`application.yml` が `db.yml` をインポートすると、`db-dev.yml` は `application-dev.yml` より優先されます。
- 相対ロケーションは、インポート元のファイルからの相対です。
- コマンドライン (`--spring.config.import=...`) や `SPRING_CONFIG_IMPORT` で指定したインポートは、すべてのロケーションより上のグループになります。
- ファイルは一度だけ読まれるため、インポートの循環は害になりません。複数の場所で指定されたファイルは、優先される場所で数えられます。リストの後の項目、`additional-location` より前のコマンドラインのインポート、ロケーションより前の `additional-location` です。その場所に書かれたエンコーディングのヒントが適用されます。

## インポートのプレースホルダー

インポートの `${...}` は、インポート元のドキュメントのインポートが読まれるときに、コマンドライン、環境変数、それまでに読まれたドキュメントに対して解決されます。

```yaml
spring:
  config:
    import: optional:file:${SHOP_CONFIG_DIR:/etc/shop}/shop.yml
```

プレースホルダーを解決できない `optional:` のインポートはスキップされます。必須のものは起動を失敗させます。

## プロファイルのファイルでのインポート

プロファイルのファイル (`application-prod.yml`) や、プロファイルに限定されたドキュメントの中のインポートは、そのプロファイルでだけ読まれ、他のインポートと同じく必須です。必須のファイルがないと起動が失敗します。ある環境にだけ存在するファイルに使います。

```yaml
# lib/resources/application-prod.yml
spring:
  config:
    import: configtree:/run/secrets/
```

## 設定ツリー

Kubernetes はシークレットや ConfigMap をファイルのディレクトリとしてマウントし、Docker もシークレットで同じことをします。`configtree:` のロケーションはそうしたディレクトリを読みます。その下の各ファイルが、パスを名前とし、ファイルの内容を値とする一つのプロパティになります。

```text
/run/secrets/
  db/
    password        "s3cret\n"   → db.password=s3cret
  mail.api-key      "abc"        → mail.api-key=abc
```

- ロケーションは `optional:` のものでも `/` で終わらなければならず、そうでなければ起動が失敗します。
- 各値から末尾の改行が一つ取り除かれます。
- 名前が `..` で始まるエントリー (Kubernetes の内部リンク) はスキップされます。
- ディレクトリがない必須のツリーは起動を失敗させます。ワイルドカードでは、サブディレクトリのないものが失敗させます。
- 値は文字列で、他のプロパティと同じようにバインドされ、変換されます。
- 読まれるのはファイルシステムのディレクトリだけなので、Web では使えません。

## HTTP 経由で

```bash
dart run bin/main.dart --spring.config.import=optional:https://config.neon.books/shop.yml
```

- ファイルは `GET` リクエストで取得されます。400 以上のステータスは読み込みを失敗させます。
- `optional:` の HTTP ロケーションは、まず `HEAD` リクエストで確認されます (サーバーが `HEAD` を拒否すれば `GET`)。404 や接続エラーではスキップされます。
- 読み込みは非同期なので、アプリケーションは `runApplicationAsync` (または `SpringApplication.runAsync`。Flutter アプリはこちらを使います) で起動しなければなりません。同期的な `runApplication` は `the resource can only be read asynchronously; use processAndApply()` で失敗します。
- 読み込みには `dart:io` が必要なので、Flutter の Web アプリでは動きません。
- ヘッダー、クレデンシャル、リトライは送られません。トークンが必要なサーバーや Vault には、`EnvironmentPostProcessor` (下記) や独自の `ProtocolResolver` で値を自分で追加してください。

## 独自の種類のロケーション

組み込みの形式でまかなえないものは、2 つの拡張ポイントでカバーします。

**`ProtocolResolver`** はリソースローダーにプレフィックスを教えます。そうすると、設定のインポート、`@PropertySource`、`@Value` のリソースがそれを受け入れます。

```dart
// ツールやテストのために、マップから配信される memory:shop.yml。
final application = SpringApplication(
  [appBeans],
  resourceLoader: DefaultResourceLoader(
    protocolResolvers: [
      InMemoryProtocolResolver('memory:', {'shop.yml': 'shop:\n  title: Test\n'}),
    ],
  ),
);
// spring.config.import=memory:shop.yml
```

**`EnvironmentPostProcessor`** は、どの Bean も存在する前に Environment を変更します。サーバーから設定を取得したり、プロパティソースを追加したり、プロファイルを有効にしたり、インポートを追加したりできます。`EnvironmentPostProcessor.configDataOrder` より前に順序付けられたものは、ファイルが読まれる前に実行されます。

```dart
// 運用担当者が ./secrets/ にマウントするシークレットのファイルをインポートする。
class LocalSecrets implements EnvironmentPostProcessor, Ordered {
  @override
  int get order => EnvironmentPostProcessor.configDataOrder - 1;

  @override
  void postProcessEnvironment(
    ConfigurableEnvironment environment,
    SpringApplication application,
  ) {
    environment.propertySources.addLast(
      MapPropertySource('secrets', {
        'spring.config.import': 'optional:file:./secrets/',
      }),
    );
  }
}

final application = SpringApplication(
  [appBeans],
  environmentPostProcessors: [LocalSecrets()],
);
```

## 対応していないもの

- `env:` のインポート。
- 設定ロケーションでの `resources*:` とクラスパスのワイルドカード。
- XML のプロパティファイル (`x.xml` は起動を失敗させます。`optional:` のものはスキップされます)。
- Spring Cloud Config、Consul、Vault のクライアント: `configserver:` や `vault:` のロケーションはありません。HTTP のインポートか `EnvironmentPostProcessor` を使ってください。

## Spring (Java) との対応

キーもルールも Spring Boot の `spring.config.import` と同じです。ただし:

- `;` のグループの各エントリーはそれぞれのプレフィックスで読まれるため、`x.yml;configtree:/run/secrets/` はツリーを読みます。Spring Boot はグループ全体のリゾルバーを最初のエントリーから選びます。
- ワイルドカードのロケーションで見つかったファイル内の相対インポートは、そのファイルからの相対です。Spring Boot はワイルドカードのパターンを基準に解決します。
- ファイルである `configtree:` のロケーションはないものとみなされるため、`optional:` ならスキップされます。Spring Boot は失敗します。
- インポートのプレースホルダーは、最初のパスではなく、インポートが読まれるときに解決されます。

## 関連項目

- [設定ファイル](config-files.md)
- [プロファイル](profiles.md)
- [概要: どのソースが優先されるか](index.md)
- [リソース](../../spring-core-dart/resources/resource.md)
- [プロパティソース](../../spring-core-dart/config/property-source.md)
