--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,
);
仕組み:
- 各エントリーは 定数 の条件によるコレクション
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) です。どちらもリテラルのキーなので、どちらの綴りでも渡せます。
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. 常に提供されるいくつかの名前。 設定ファイルの前後に読まれ、スキャンされるコードがそれらに触れないためです。
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) で、たとえばデフォルト値とともにそれを書いておきます。
# 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 のテーマはトークンごとに一つのキーになります) や、プロパティをビルド時に変更できないようにしたい場合に使います。
プレフィックスの一致の仕方:
- セグメント単位。
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 は定数のキーでしか読めないため、ジェネレーターがキーを書いてくれます。