コマンドライン、環境変数、--dart-define
設定ファイルは、アプリケーションとともに出荷される値を持ちます。このページのソースは、ファイルを編集せずに、起動時やビルド時にそれらを変更します。どれも設定ファイルより優先されます。完全な順序は 概要 にあります。
使う理由
コンテナ内のサーバーは、設定を環境変数として受け取ります。CI のジョブはコマンドラインでオプションを渡します。Flutter アプリにはそのどちらもないため、ビルドごとの値を --dart-define として受け取ります。どれも、それぞれのソースが書ける名前で、同じキーに届きます。
例
# lib/resources/application.yml
shop:
max-basket-size: 10
api-url: http://localhost:8080
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') がそれを読みます。
コマンドライン
dart run bin/main.dart --shop.max-basket-size=30 --spring.profiles.active=prod --debug
--key=valueはkeyを設定します。区切りになるのは最初の=だけです。- 単独の
--flagはflagを空の値に設定します (--debugは条件レポートを有効にします)。 - 繰り返したオプションはすべての値をカンマでつないで保持します。
- 単独の
--はオプションの終わりで、その後は通常の引数です。 - 通常の引数はプロパティではありません。ランナーは
ApplicationArguments.nonOptionArgsを通してそれらを受け取ります (ランナー を参照)。
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) で与えた値は、コマンドラインのすぐ下、環境変数と設定ファイルより上のプロパティソースです。環境変数と同じ緩い名前が使えます。
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
@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 のキー を参照してください。
define はプログラムにコンパイルされ、APK、IPA、main.dart.js から読み取れます。パスワードや秘密鍵を決してこの方法で渡さないでください。
SPRING_APPLICATION_JSON
環境変数 SPRING_APPLICATION_JSON、またはプロパティ spring.application.json (たとえばコマンドラインで) の JSON オブジェクトです。環境変数のすぐ上、コマンドラインと --dart-define の下のプロパティにフラット化されます。プラットフォームが設定を一つの変数として渡す場合に便利です。
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 からの設定、計算したプロファイル |
// application.properties なしで動くツール。
void main(List<String> args) => SpringApplication(
[toolBeans],
defaultProperties: {'tool.output': 'out/', 'logging.level.root': 'warn'},
).run(args);
EnvironmentPostProcessor は インポート で説明しています。
プレースホルダー
値には他のプロパティを含められます。${key} は key の値に置き換えられ、${key:default} は key が設定されていなければ default を使います。
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の中でだけ評価され、設定ファイルでは決して評価されません。
プレースホルダー を参照してください。
ランダムな値
${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 のリスト、またはインデックス付きのキー |
名前が変わったプロパティ
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 のような環境変数) にあっても、起動を止めます。
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 ファイルには対応していません。