
# --dart-define キー

`flutter build apk --dart-define=SPRING_PROFILES_ACTIVE=prod` は、コンパイルされるプログラムに値を渡します。Spring for Dart がそれをプロパティとして扱えるように、`@SpringBootApplication` の出力は、アプリケーションが読みうるすべてのプロパティ名を、それぞれ定数のチェックの背後に置いて、`springApplication.dartDefines` に列挙します。このページでは、その理由、名前の出どころ、リストを短くする方法を説明します。

## キーが定数でなければならない理由

Flutter アプリ、Web アプリ、AOT 実行ファイルには、コマンドラインも役に立つ環境変数もないことがよくあります。そのようなプログラムはビルド時の define で設定します。`flutter build` と `flutter run` では `--dart-define`、`dart compile` と `dart run` では `-D` です。

しかし Dart のプログラムが define を読めるのは、**定数式とリテラルのキー** を使う場合だけです。

```dart
const url = String.fromEnvironment('API_URL'); // どこでも動く
```

「どの define が与えられたか」を問い合わせる方法も、実行時にしか名前がわからない define を読む方法もありません。Web と AOT ビルドでは、コンパイラーがコンパイル中に `String.fromEnvironment('API_URL')` を値に置き換えるので、キーはソースに書かれていなければなりません。

Spring は、アノテーションや設定ファイルにある名前を使い、実行時に名前でプロパティを読みます (`environment.getProperty('api.url')`)。この二つを橋渡しするため、ジェネレーターはアプリケーションが読みうるすべての名前をビルド時に集め、名前ごとに一つの定数の検索を書き出します。ランタイムは与えられた define のマップを持ち、それをプロパティソースとして提供します。

## ジェネレーターが書き出すもの

`springApplication` の `dartDefines:` 引数です。`spring_core_dart` のサンプルからの抜粋です (プレフィックスは外しています)。

```dart
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [springBootAutoConfiguration],
  dartDefines: {
    if (const bool.hasEnvironment('DEBUG'))
      'DEBUG': const String.fromEnvironment('DEBUG'),
    if (const bool.hasEnvironment('GREETING_PUNCTUATION'))
      'GREETING_PUNCTUATION': const String.fromEnvironment(
        'GREETING_PUNCTUATION',
      ),
    if (const bool.hasEnvironment('LOGGING_LEVEL_ROOT'))
      'LOGGING_LEVEL_ROOT': const String.fromEnvironment('LOGGING_LEVEL_ROOT'),
    if (const bool.hasEnvironment('SPRING_PROFILES_ACTIVE'))
      'SPRING_PROFILES_ACTIVE': const String.fromEnvironment(
        'SPRING_PROFILES_ACTIVE',
      ),
    // ...
    if (const bool.hasEnvironment('greeting.punctuation'))
      'greeting.punctuation': const String.fromEnvironment(
        'greeting.punctuation',
      ),
    if (const bool.hasEnvironment('spring.profiles.active'))
      'spring.profiles.active': const String.fromEnvironment(
        'spring.profiles.active',
      ),
    // ...
  },
  fingerprint: !const bool.fromEnvironment('dart.vm.product')
      ? _$fingerprint
      : null,
);
```

仕組み:

- 各エントリーは **定数** の条件によるコレクション `if` です。define が与えられていなければ `const bool.hasEnvironment(...)` はコンパイル時に `false` になり、コンパイラーはそのエントリーを取り除きます。コンパイルされたマップには渡した define だけが残るので、リストが長くても実行時のコストはありません。
- キーはソートされます (大文字の名前は小文字の名前より前に並びます)。
- `bool.hasEnvironment` は、空文字列として与えられた define (`--dart-define=KEY=`) と、まったく与えられていない define を区別します。

実行時に、`SpringApplication` はマップをプロパティソース `dartDefines` として環境に入れます。

- **コマンドライン引数のすぐ下**、**OS の環境変数と設定ファイルより上** に置かれます。
- 環境変数と同じく緩い名前で扱われます。define `API_URL` は `${API_URL}` と `api.url` に応え、`SPRING_PROFILES_ACTIVE` はプロファイルを有効にします。

## 各名前の二つの形

集められた名前はすべて二度書かれます。書かれたとおりの形 (`shop.currency`) と、環境変数の形 (`SHOP_CURRENCY`) です。どちらもリテラルのキーなので、どちらの綴りでも渡せます。

```bash
flutter build web --dart-define=shop.currency=USD
flutter build web --dart-define=SHOP_CURRENCY=USD
```

環境変数の形は、Spring Boot が環境変数をバインドするときの形です。

| 名前 | 環境変数の形 |
|---|---|
| `shop.currency` | `SHOP_CURRENCY` |
| `shop.max-basket-size` | `SHOP_MAXBASKETSIZE` (ダッシュは取り除かれる) |
| `app.servers[0].host` | `APP_SERVERS_0_HOST` |
| `spring.flutter.scan-os-environment` | `SPRING_FLUTTER_SCANOSENVIRONMENT` |
| `NEON_KEYCLOAK_SECRET` | `NEON_KEYCLOAK_SECRET` (すでにその形) |

ルール: 大文字にし、`.` は `_` になり、`-` は取り除かれ、インデックス `[0]` は `_0_` になり、末尾の `_` は落とされます。

読まれるのはこの二つの綴りだけです。緩いバインディングが他の場所で受け付ける他の綴り (`shop.maxBasketSize`、`SHOP_MAX_BASKET_SIZE`) はマップのキーではないので、そのような名前の define は見えません。

英字、数字、`_`、`.`、`-`、`[`、`]` 以外の文字を含む名前は、生成コードにエスケープされるのではなく、スキップされます。

## 名前の出どころ

ジェネレーターは四つの場所から名前を集めます。

**1. アプリケーションのスキャンされるライブラリ。** `@SpringBootApplication` のスキャンが対象とするすべてのライブラリと、それがインポートする入れ子の `@ComponentScan` モジュールのライブラリ (独自のモジュールを持つ `lib/src/` のスキャンルートも含む) で:

- クラス、コンストラクター、パラメーター、フィールド、メソッド、トップレベルの宣言に付いたあらゆるアノテーションの引数の中のすべての `${...}` プレースホルダー。入れ子の定数、リスト、マップ、レコードの中の文字列も対象です。入れ子のプレースホルダーは両方のキーになり (`${a:${b}}` は `a` と `b`)、キーの中のプレースホルダーは内側のものだけになります (`${${env}.url}` は `env`。完全なキーはわからないため)。
- `@ConditionalOnProperty` と `@ConditionalOnBooleanProperty` の名前を、その `prefix` と結合したもの。
- `@ConfigurationProperties` クラスのバインドされる名前。プレフィックスの後に、各コンストラクターのパラメーターや public フィールドをケバブケースにしたもの (`maxBasketSize` → `shop.max-basket-size`)、そして同じライブラリの入れ子のクラスのものです。

**2. 設定ファイル。** 埋め込みリソースのうち、名前が `application` で始まり `.properties`、`.yml`、`.yaml` で終わるすべてのファイル (`application.yml`、`application-prod.properties`、`config/application-eu.yml`) の、各キー (YAML は平坦化されます。`server.port`、`app.hosts[0]`) と、値の中の各プレースホルダー。解析できない YAML ファイルはスキップされ、アプリケーションがそのファイルを読むときに報告されます。その他のファイル (`config/supplier.properties`) は読まれません。

**3. 常に提供されるいくつかの名前。** 設定ファイルの前後に読まれ、スキャンされるコードがそれらに触れないためです。

```text
spring.profiles.active
spring.profiles.include
spring.main.banner-mode
spring.flutter.scan-os-environment
debug
trace
logging.level.root
```

**4. それ以外はありません。** 特に:

- **スターターのプロパティ** (`server.port`、`spring.datasource.url` など) は、自分の設定ファイルやスキャンされるコードがそれに触れた場合にだけキーになります。

そのようなプロパティを `--dart-define` で設定できるようにするには、`application.properties` (または `application.yml`) で、たとえばデフォルト値とともにそれを書いておきます。

```properties
# lib/resources/application.properties
server.port=8080
```

## 例

ビルド時にプロファイルと API を選ぶ Flutter アプリ:

```bash
flutter build apk \
  --dart-define=SPRING_PROFILES_ACTIVE=prod \
  --dart-define=API_URL=https://api.neon.books
```

```yaml
# lib/resources/application.yml
api:
  url: http://localhost:8080   # このキーにより api.url と API_URL が define になる
```

```dart
@Service()
class CatalogClient {
  CatalogClient(@Value(r'${api.url}') this.baseUrl);

  final String baseUrl; // prod ビルドでは https://api.neon.books
}
```

ファイルから複数の値を渡す (Flutter の機能。キーは同じ):

```bash
flutter run --dart-define-from-file=config/dev.json
```

AOT 実行ファイル:

```bash
dart compile exe -Dserver.port=9090 -o build/shop bin/main.dart
```

一回の実行だけログを増やす (`logging.level.root` は常にキー):

```bash
flutter run --dart-define=LOGGING_LEVEL_ROOT=debug
```

値はプログラムにコンパイルされ、そこから読み取れます。この方法で秘密情報を渡してはいけません。

## キーを外す

ビルドオプション `dart_defines_exclude` は、プロパティ名のプレフィックスのリストを受け取ります。その下のプロパティは、両方の形とも `dartDefines` に書かれないので、`--dart-define` では設定できません。設定ファイル、環境変数、コマンドラインでは引き続き設定できます。

```yaml
# 自分のパッケージの build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          dart_defines_exclude: [spring.flutter.theme]
```

目的もなく多くのキーが列挙される場合 (`application.yml` で宣言された Flutter のテーマはトークンごとに一つのキーになります) や、プロパティをビルド時に変更できないようにしたい場合に使います。

プレフィックスの一致の仕方:

- **セグメント単位。** `spring.datasource` は `spring.datasource.url` を外しますが、`spring.datasourceish` は外しません。
- **Spring Boot のバインドと同じく緩やか。** セグメントは大文字小文字を区別せずに比較され、セグメント内の `-` と `_` は無視され、インデックスはそれ自体で一つのセグメントです。`spring.dataSource`、`spring.data-source`、`SPRING_DATASOURCE` は同じプレフィックスです。
- **両方の形をまとめて。** プロパティのどちらかの形が一致すれば、ドット区切りの形と環境変数の形の両方が外されます。
- **末尾の `.` や `[` は無視されます。** `spring.datasource.` は `spring.datasource` です。

不正なエントリーは `ArgumentError` でビルドを失敗させます。文字列でないエントリー、空のエントリー、ワイルドカード (`spring.datasource.*`。プレフィックスはすでにその下のすべてを対象にします)、英字、数字、`_`、`.`、`-`、`[`、`]` 以外の文字です。

## Spring (Java) との対応

Java のプログラムは実行時にシステムプロパティと環境変数を読むので、Spring Boot にはこのような仕組みは不要です。`java` コマンドラインの `-Dshop.currency=USD` はプロパティになります。Dart でシステムプロパティに最も近いものは define で、define は定数のキーでしか読めないため、ジェネレーターがキーを書いてくれます。

## 関連項目

- [@SpringBootApplication](spring-boot-application.md)
- [オプション](options.md)
- [Environment](../spring-core-dart/config/environment.md)
- [プレースホルダー](../spring-core-dart/config/placeholders.md)
- [@ConfigurationProperties](../spring-core-dart/config/configuration-properties.md)
