コマンドライン、環境変数、--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

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: ...) として列挙します。

コードでだけ読むキー (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}

プレースホルダー を参照してください。

ランダムな値

${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 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 ファイルには対応していません。

関連項目