--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 を読めるのは、定数式とリテラルのキー を使う場合だけです。

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 のサンプルからの抜粋です (プレフィックスは外しています)。

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,
);

仕組み:

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

各名前の二つの形

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

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/ のスキャンルートも含む) で:

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

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

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

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

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

例

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

flutter build apk \
  --dart-define=SPRING_PROFILES_ACTIVE=prod \
  --dart-define=API_URL=https://api.neon.books
# lib/resources/application.yml
api:
  url: http://localhost:8080   # このキーにより api.url と API_URL が define になる
@Service()
class CatalogClient {
  CatalogClient(@Value(r'${api.url}') this.baseUrl);

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

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

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

AOT 実行ファイル:

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

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

flutter run --dart-define=LOGGING_LEVEL_ROOT=debug

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

キーを外す

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

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

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

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

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

Spring (Java) との対応

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

関連項目