外部設定

設定とは、コードは同じままで、場所によって変わる値のことです。サーバーの URL、ポート、タイムアウト、機能のスイッチ、ログレベルなどです。spring_boot_dart はそれらをコードの外から読むため、一つのビルドがノート PC でも、テストでも、本番でも、それぞれの値で動き、何も再コンパイルしません。

これは Spring Boot の Externalized Configuration です。ファイル名、キー、ルールは Spring Boot のものなので、Spring プロジェクトの設定はたいていそのまま動きます。

使う理由

コードに書いた設定を変えるには、新しいビルドが必要です。設定から読む値は、プログラムを実行する人が変えられます。バイナリの隣にファイルを置く運用担当者、環境変数を持つコンテナ、コマンドラインのオプションを使う CI のジョブ、--dart-define を使う Flutter のビルドなどです。どれが優先されるかは Spring Boot のルールが決めるため、lib/resources/application.yml に妥当なデフォルトを入れて出荷し、どのキーでも外から上書きできます。

例

同じキーを 5 つの場所から。最も優先度の高いソースが勝ちます。

# lib/resources/application.yml: プログラムとともに出荷される
shop:
  url: http://localhost:8080
# lib/resources/application-prod.yml: prod プロファイルで読まれる
shop:
  url: https://neon.books
dart run bin/main.dart                                   # http://localhost:8080
dart run bin/main.dart --spring.profiles.active=prod     # https://neon.books
SHOP_URL=https://staging.neon.books dart run bin/main.dart   # 環境変数はファイルより優先される
dart run bin/main.dart --shop.url=http://127.0.0.1:9000      # コマンドラインはすべてより優先される
// どの Bean も、ソースにかかわらず同じ方法で読む。
@Service()
class Links {
  Links(@Value(r'${shop.url}') this.url);

  final String url;
}

ソース

ソース どこから来るか ページ
設定ファイル lib/resources/、lib/resources/config/、./、./config/、./config/*/ の application.properties、application.yml、application.yaml 設定ファイル
プロファイルのファイルとドキュメント application-{profile}.*、および spring.config.activate.on-profile を持つドキュメント プロファイル
インポート spring.config.import: 追加のファイル、ディレクトリ、設定ツリー、HTTP、パッケージ、アセット インポート
コマンドライン --key=value コマンドライン、環境変数、--dart-define
環境変数 SHOP_URL=...。緩い名前で コマンドライン、環境変数、--dart-define
--dart-define プログラムにコンパイルされる値 コマンドライン、環境変数、--dart-define
SPRING_APPLICATION_JSON 変数またはプロパティの中の一つの JSON オブジェクト コマンドライン、環境変数、--dart-define
コード SpringApplication(defaultProperties:)、run(properties:)、EnvironmentPostProcessor コマンドライン、環境変数、--dart-define
@PropertySource 構成クラスで指定したファイル プロパティソース

どのソースが優先されるか

複数のソースが同じキーを設定すると、最も優先度の高いものが勝ちます。高い順に:

  1. run(properties: ...)、テストでは springBootTest(properties: ...) (テストの dynamicProperties はさらに上)。
  2. コマンドライン引数 (--shop.url=...)。
  3. --dart-define の値。
  4. SPRING_APPLICATION_JSON (または --spring.application.json)。
  5. OS の環境変数。Flutter アプリは、ビルドで有効にしない限りこれを読みません。
  6. ${random.*} の値。
  7. 設定ファイル。次の順序で (上が優先):
    • コマンドラインまたは環境変数で指定した spring.config.import。
    • 次に spring.config.additional-location。
    • 次にロケーション: file:./config/*/、file:./config/、file:./ が resources:/config/、resources:/ より上。
    • 各グループの中では、プロファイルのファイルが通常のファイルより上で、最後に有効になったプロファイルが最も上。
    • インポートされたファイルはインポート元のファイルより上で、そのプロファイル版もインポート元のプロファイル版より上。
    • 一つのロケーションの中では、.properties が .yml より、.yml が .yaml より上。
    • 一つのファイルの中では、後のドキュメントが前のドキュメントより上。
  8. @PropertySource のファイル。
  9. SpringApplication(defaultProperties: ...)。

リストは常に、それを持つ最も優先度の高いソースから丸ごと来ます。--shop.hosts[0]=local はファイルの 3 つのホストを置き換えます。最初のホストを変更するのではありません。マップのエントリーはソースをまたいでマージされ、キーごとに優先度の高いソースが勝ちます。@ConfigurationProperties を参照してください。

設定が読まれるタイミング

設定は起動時に一度だけ、どの Bean も生成される前に読まれます。

  1. コマンドライン、--dart-define の値、環境変数、コードのプロパティ、${random.*} がプロパティソースになります。
  2. EnvironmentPostProcessor.configDataOrder より前に順序付けられた EnvironmentPostProcessor が実行されます (SPRING_APPLICATION_JSON はその一つです)。
  3. 設定ファイルが読まれます: ロケーション、プロファイル、インポート、ドキュメント。これが ConfigDataEnvironment です。
  4. その他の EnvironmentPostProcessor が実行されます。名前が変わったプロパティ のチェックもその一つです。
  5. ApplicationEnvironmentPreparedEvent が発行され、ログレベルが適用され、Bean が生成されます。

runApplication はファイルを同期的に読みます。非同期にしか読めないロケーション (HTTP、Flutter のアセット) には runApplicationAsync が必要です。Flutter アプリはいずれにせよこちらを使います。

設定ファイルを変更するには再起動が必要です。開発中は、ホットリロード が新しい値でコンテキストを再起動します。

エディターの補完

ジェネレーターは、Spring のコードを持つすべてのパッケージについて lib/spring_gen/spring_metadata.json を書き出します。その @ConfigurationProperties クラスのキーと、その /// コメント、型、デフォルト、許可される値です。dart run tool/spring_schema.dart <app> (フレームワークのリポジトリにあります) は、アプリケーションとその依存関係のメタデータを YAML 言語サーバー用の JSON Schema に変換するため、application*.yml で補完とチェックが効きます。メタデータ を参照してください。

Spring (Java) との対応

これらのページの内容はすべて Spring Boot の Externalized Configuration に従っており、主な違いは次のとおりです。

すべての違いは Spring との違い にあります。

関連項目