外部設定
設定とは、コードは同じままで、場所によって変わる値のことです。サーバーの 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 |
構成クラスで指定したファイル | プロパティソース |
どのソースが優先されるか
複数のソースが同じキーを設定すると、最も優先度の高いものが勝ちます。高い順に:
run(properties: ...)、テストではspringBootTest(properties: ...)(テストのdynamicPropertiesはさらに上)。- コマンドライン引数 (
--shop.url=...)。 --dart-defineの値。SPRING_APPLICATION_JSON(または--spring.application.json)。- OS の環境変数。Flutter アプリは、ビルドで有効にしない限りこれを読みません。
${random.*}の値。- 設定ファイル。次の順序で (上が優先):
- コマンドラインまたは環境変数で指定した
spring.config.import。 - 次に
spring.config.additional-location。 - 次にロケーション:
file:./config/*/、file:./config/、file:./がresources:/config/、resources:/より上。 - 各グループの中では、プロファイルのファイルが通常のファイルより上で、最後に有効になったプロファイルが最も上。
- インポートされたファイルはインポート元のファイルより上で、そのプロファイル版もインポート元のプロファイル版より上。
- 一つのロケーションの中では、
.propertiesが.ymlより、.ymlが.yamlより上。 - 一つのファイルの中では、後のドキュメントが前のドキュメントより上。
- コマンドラインまたは環境変数で指定した
@PropertySourceのファイル。SpringApplication(defaultProperties: ...)。
リストは常に、それを持つ最も優先度の高いソースから丸ごと来ます。--shop.hosts[0]=local はファイルの 3 つのホストを置き換えます。最初のホストを変更するのではありません。マップのエントリーはソースをまたいでマージされ、キーごとに優先度の高いソースが勝ちます。@ConfigurationProperties を参照してください。
設定が読まれるタイミング
設定は起動時に一度だけ、どの Bean も生成される前に読まれます。
- コマンドライン、
--dart-defineの値、環境変数、コードのプロパティ、${random.*}がプロパティソースになります。 EnvironmentPostProcessor.configDataOrderより前に順序付けられたEnvironmentPostProcessorが実行されます (SPRING_APPLICATION_JSONはその一つです)。- 設定ファイルが読まれます: ロケーション、プロファイル、インポート、ドキュメント。これが
ConfigDataEnvironmentです。 - その他の
EnvironmentPostProcessorが実行されます。名前が変わったプロパティ のチェックもその一つです。 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 に従っており、主な違いは次のとおりです。
lib/resources/がクラスパスで、(classpath:ではなく)resources:と書きます。--dart-defineの値は、コマンドラインのすぐ下にある独自のソースです。Java に対応するものはなく、最も近いのは-Dkey=valueです。.propertiesファイルは ISO-8859-1 ではなく UTF-8 です。env:のインポート、XML のプロパティファイル、Spring Cloud Config のクライアントはありません。HTTP のインポート (spring.config.import=https://...) は、非同期の起動で使えます。
すべての違いは Spring との違い にあります。