
# コマンドライン、環境変数、--dart-define

設定ファイルは、アプリケーションとともに出荷される値を持ちます。このページのソースは、ファイルを編集せずに、起動時やビルド時にそれらを変更します。どれも設定ファイルより優先されます。完全な順序は [概要](index.md#どのソースが優先されるか) にあります。

## 使う理由

コンテナ内のサーバーは、設定を環境変数として受け取ります。CI のジョブはコマンドラインでオプションを渡します。Flutter アプリにはそのどちらもないため、ビルドごとの値を `--dart-define` として受け取ります。どれも、それぞれのソースが書ける名前で、同じキーに届きます。

## 例

```yaml
# lib/resources/application.yml
shop:
  max-basket-size: 10
  api-url: http://localhost:8080
```

```bash
dart run bin/main.dart --shop.max-basket-size=30         # コマンドライン
SHOP_MAXBASKETSIZE=30 dart run bin/main.dart             # 環境変数
SPRING_APPLICATION_JSON='{"shop":{"max-basket-size":30}}' dart run bin/main.dart
flutter run --dart-define=SHOP_API_URL=https://api.neon.books   # ビルド時
```

4 つとも `shop.max-basket-size` (または `shop.api-url`) を設定し、`@Value(r'${shop.max-basket-size}')` と `@ConfigurationProperties('shop')` がそれを読みます。

## コマンドライン

```bash
dart run bin/main.dart --shop.max-basket-size=30 --spring.profiles.active=prod --debug
```

- `--key=value` は `key` を設定します。区切りになるのは最初の `=` だけです。
- 単独の `--flag` は `flag` を空の値に設定します (`--debug` は条件レポートを有効にします)。
- 繰り返したオプションはすべての値をカンマでつないで保持します。
- 単独の `--` はオプションの終わりで、その後は通常の引数です。
- 通常の引数はプロパティではありません。ランナーは `ApplicationArguments.nonOptionArgs` を通してそれらを受け取ります ([ランナー](../runners.md) を参照)。

Flutter のデスクトップアプリは、`SpringApplicationWidget(args: ...)` で引数を渡します。

## 環境変数

`SHOP_MAXBASKETSIZE=20` は `shop.max-basket-size` を設定します。名前は `_` で分割されて小文字になり、ダッシュは関係ありません。数値の部分はインデックスになります。

| 変数 | キー |
|---|---|
| `SHOP_MAXBASKETSIZE` | `shop.max-basket-size` (`shop.maxBasketSize` も) |
| `SHOP_HOSTS_0_` または `SHOP_HOSTS_0` | `shop.hosts[0]` |
| `APP_MAIN_SERVER_HOST` | `app.main-server.host` (ネストしたオブジェクトにバインドされる) |
| `SPRING_PROFILES_ACTIVE` | `spring.profiles.active` |
| `LOGGING_LEVEL_NEON_CHECKOUT` | `logging.level.neon.checkout` |

スマートフォンやブラウザーには有用な環境変数がありません。Flutter アプリは、ビルドで `spring.flutter.scan-os-environment=true` を定義した場合にだけそれを読みます。

## 緩い名前

プロパティにはケバブケースの正規名があります。`shop.max-basket-size` のように、小文字の単語を `-` でつないだものです。各ソースはそれぞれの方法で書いてかまわず、それでも一致します。

| 書き方 | 場所 |
|---|---|
| `shop.max-basket-size` | 正規形。ファイルでの推奨 |
| `shop.maxBasketSize` | キャメルケース。ファイルで |
| `shop.max_basket_size` | アンダースコア。ファイルで |
| `SHOP_MAXBASKETSIZE`、`SHOP_MAX_BASKET_SIZE` | 環境変数と `--dart-define` |

`[...]` の中では、マップのキーは書かれたとおりに扱われます。キーを読むコード (`@Value`、`environment.getProperty`) は正規形を使ってください。

## --dart-define

ビルド時に `--dart-define` (`dart run` と `dart compile` では `-DKEY=value`) で与えた値は、コマンドラインのすぐ下、環境変数と設定ファイルより上のプロパティソースです。環境変数と同じ緩い名前が使えます。

```bash
flutter build apk --dart-define=SPRING_PROFILES_ACTIVE=prod \
  --dart-define=API_URL=https://api.neon.books
flutter build apk --dart-define-from-file=config/prod.json
dart compile exe bin/main.dart -DSHOP_MAXBASKETSIZE=30
```

```dart
@Value(r'${API_URL}') String apiUrl     // https://api.neon.books
@Value(r'${api.url}') String sameUrl    // 環境変数と同じく緩い名前で
```

`SPRING_PROFILES_ACTIVE` は `application-prod.yml` を有効にするため、プロファイルでビルドフレーバーを置き換えられます。

Web と AOT ビルドでは、`String.fromEnvironment` はリテラルのキーを持つ `const` としてしか動かないため、define はプログラムのコンパイル時に分かっていなければなりません。そのためジェネレーターは、アプリケーションが読みうるすべてのキーを、それぞれ環境変数の形でも、`SpringApplication(dartDefines: ...)` として列挙します。

- アノテーションの `${...}` プレースホルダー。
- `@ConditionalOnProperty` の名前。
- `@ConfigurationProperties` クラスのフィールド。
- `application*` 設定ファイルのキーとプレースホルダー。
- `spring.profiles.active`。

コードでだけ読むキー (`environment.getProperty('x')`) は列挙されません。`application.properties` に (空でもよいので) 書くか、自分で `SpringApplication(dartDefines: {...})` に渡してください。[--dart-define のキー](../../spring-core-dart-generator/dart-defines.md) を参照してください。

define はプログラムにコンパイルされ、APK、IPA、`main.dart.js` から読み取れます。パスワードや秘密鍵を決してこの方法で渡さないでください。

## SPRING_APPLICATION_JSON

環境変数 `SPRING_APPLICATION_JSON`、またはプロパティ `spring.application.json` (たとえばコマンドラインで) の JSON オブジェクトです。環境変数のすぐ上、コマンドラインと `--dart-define` の下のプロパティにフラット化されます。プラットフォームが設定を一つの変数として渡す場合に便利です。

```bash
SPRING_APPLICATION_JSON='{"shop":{"hosts":["a","b"],"max-basket-size":30}}' dart run bin/main.dart
# shop.hosts[0]=a, shop.hosts[1]=b, shop.max-basket-size=30

dart run bin/main.dart --spring.application.json='{"server":{"port":9090}}'
```

JSON は、どちらかの名前を持つ最初のソースから来ます。設定ファイルより前に読まれるため、`spring.config.*` や `spring.profiles.active` を設定できます。解析できない JSON や、オブジェクトでない JSON は起動を失敗させます。

## コードで

| 場所 | 優先順位 | 用途 |
|---|---|---|
| `SpringApplication(defaultProperties: {...})`、または `setDefaultProperties` | 最低: すべてのファイルがこれを上書きする | 設定ファイルなしでも動くプログラムのデフォルト |
| `run(args, properties: {...})` | 最高: コマンドラインより上 | ツールとテスト (`springBootTest(properties:)` はこれの上に作られている) |
| `run(args, systemEnvironment: {...})` | OS の環境変数を置き換える | テスト |
| `SpringApplication(environmentPostProcessors: [...])` | 任意: コードが好きな場所にソースを追加する | サーバーや Vault からの設定、計算したプロファイル |

```dart
// application.properties なしで動くツール。
void main(List<String> args) => SpringApplication(
      [toolBeans],
      defaultProperties: {'tool.output': 'out/', 'logging.level.root': 'warn'},
    ).run(args);
```

`EnvironmentPostProcessor` は [インポート](imports.md#独自の種類のロケーション) で説明しています。

## プレースホルダー

値には他のプロパティを含められます。`${key}` は `key` の値に置き換えられ、`${key:default}` は `key` が設定されていなければ `default` を使います。

```yaml
shop:
  name: NEON Books
  title: ${shop.name} (${spring.profiles.active:local})
  url: ${SHOP_URL:http://localhost:8080}
  api: ${shop.url}/api/v${shop.api-version:1}
  literal: \${not.a.placeholder}
```

- `\${` はリテラルの `${` になります。`.properties` では `\\${` と書きます。
- `${db:url}` は、Spring 6.2 と同じく、まずキー `db:url` として検索され、次にデフォルト `url` を持つ `db` として検索されます。
- 解決できず、デフォルトもないプレースホルダーは、値が必要な場所 (`@Value`、`getProperty`) で、それを示すレポートとともに失敗します。`@ConfigurationProperties` のバインドでは書いたとおりに保たれます。
- Dart では、`@Value` の文字列を raw 文字列 (`r'${shop.name}'`) で書いてください。`'${...}'` は Dart の文字列補間だからです。
- `#{...}` (SpEL) は `@Value` と `@ConditionalOnExpression` の中でだけ評価され、設定ファイルでは決して評価されません。

[プレースホルダー](../../spring-core-dart/config/placeholders.md) を参照してください。

## ランダムな値

`${random.*}` は、読むたびに新しいランダムな値を返します。実行ごとに異なるべき値に使います。

| プレースホルダー | 値 |
|---|---|
| `${random.int}`、`${random.long}` | 任意の int または long (Web では最大 53 ビット) |
| `${random.int(10)}`、`${random.int[5,10]}`、`${random.long(100)}` | 範囲内の数値。上限は含まない |
| `${random.uuid}` | ランダムなバージョン 4 の UUID |
| `${random.value}`、またはその他の `random.*` | 32 桁のランダムな 16 進数 |

## 値の書き方

値はすべてテキストで、型付きのフィールドにバインドされるときに変換されます。

| 型 | 形式 |
|---|---|
| `Duration` | `10s`、`500ms`、`5m`、`1h`、`2d` (単位は `ns`、`us`、`ms`、`s`、`m`、`h`、`d`。大文字小文字を問わない)。ISO 8601 の `PT10S`、`P1DT2H` (年と月はない)。単なる数値はミリ秒、または `@DurationUnit` の単位 |
| `DataSize` | `512B`、`10KB`、`5MB`、`1GB`、`1TB`。大文字小文字を問わず、1024 の累乗で、整数のみ。単なる数値はバイト、または `@DataSizeUnit` の単位 |
| `bool` | `true`、`on`、`yes`、`1` / `false`、`off`、`no`、`0`。大文字小文字を問わない。それ以外は起動を失敗させる |
| 列挙型 | 大文字小文字と区切り文字を無視して照合する: `ONLY_SHOW_SELECTED`、`only-show-selected`、`onlyShowSelected` |
| 数値 | 10 進数、または 16 進数 (`0x1F`、`#1F`)。空の値は「設定されていない」とみなされる |
| リスト | カンマ区切りのリスト、YAML のリスト、またはインデックス付きのキー |

[Durations](../../spring-core-dart/conversion/durations.md) と [データサイズ](../../spring-core-dart/conversion/data-size.md) を参照してください。

## 名前が変わったプロパティ

Spring Boot のいくつかのプレフィックスは、Dart では意味のない Java の歴史を背負っています。ここではそれらに別の名前があります。

| Spring Boot | ここでは |
|---|---|
| `spring.jackson.*` | `spring.json.*` |
| `spring.cloud.openfeign.*` | `spring.feign.*` |
| `spring.servlet.multipart.*` | `spring.web.multipart.*` |
| `server.servlet.*` | `server.*` |
| `logging.logback.rollingpolicy.*` | `logging.file.rolling-policy.*` |
| `spring.flyway.*` | `spring.sql.migration.*` |

古い名前が黙って無視されることはありません。古いプレフィックスの下のどのキーも、どのソース (ファイル、コマンドライン、`--dart-define`、`SPRING_JACKSON_TIME_ZONE` のような環境変数) にあっても、起動を止めます。

```text
Description:

These properties have been renamed:

  - spring.jackson.default-property-inclusion is now
    spring.json.default-property-inclusion
```

Spring Boot の `spring-boot-properties-migrator` は警告するだけで、古い名前を読み続けます。そうすると、忘れられた `server.servlet.session.*` によって、セッションがデフォルトのままになってしまいます。

## Spring (Java) との対応

コマンドライン、環境変数、緩いバインド、`SPRING_APPLICATION_JSON`、プレースホルダー、ランダムな値は Spring Boot に従います。`--dart-define` に対応するものは Java にはありません (最も近いのは `-Dkey=value` のシステムプロパティです)。`.env` ファイルには対応していません。

## 関連項目

- [概要: どのソースが優先されるか](index.md)
- [設定ファイル](config-files.md)
- [@ConfigurationProperties](../configuration-properties.md)
- [Environment](../../spring-core-dart/config/environment.md)
- [@Value](../../spring-core-dart/config/value.md)
