今回は外部設定値(プロパティファイル、JVMのシステムプロパティ、環境変数などに定義した設定値)をSpring Bootがどのように扱うのか紹介したいと思います。
なお、前回紹介した「Spring BootのAutoConfigureの仕組みを理解する」でも外部設定値を参照した条件付きBean定義の仕組みがサポートされていたり、各AutoConfigure用のコンフィギュレーションクラスの中から外部設定値を参照してBean定義していたりします!!
前提バージョン
- Spring Boot 2.4.5
(1.4.1.BUILD-SNAPSHOT) - Spring Framework 5.3.6
(4.3.3.BUILD-SNAPSHOT)
Note:
[2021/5/7]
投稿から5年くらいたっても一定のViewが継続してあるので、最新のSpring(Spring Boot)バージョンの内容に更新しました。外部設定周りは投稿時のSpring Boot 1.4.x系からかなり機能追加・改善が行われているため、
- 「バージョンアップに伴う記載内容の見直し(必要最小限の修正)」
- 「機能追加部分の説明追加」
の2回に分けて更新したいと思います。まずは、「バージョンアップに伴う記載内容の見直し」になります。
外部設定として扱う値は?
アプリケーションを作成する場合、ソースコード上にハードコーディングできない(or したくない)値を扱うことがよくあります。具体的には・・・以下のような値が外部設定値として扱う候補になります。
- データベースへの接続情報などの環境に依存する値
- 機能要件で決められたアプリケーションの動作を変更するためのパラメータ値
- 機能要件上はパラメータ化する必要はないけどテスト容易性などを考慮して外部化しておいた方がよい値
- 性能要件に応じてチューニングが必要になる事が想定されるパラメータ値
- etc..
外部設定値の取得方法
Spring Bootアプリケーションでは、以下のいずれかの方法で外部設定値を取得することができます。
- Spring Frameworkが提供している
@Value
を使用する - Spring Bootが提供している「Type-safe Configuration Properties」の仕組みを利用する (基本的にはこの仕組みを使うのがお勧めです
)
- Spring Frameworkが提供している
Environment
インタフェースを利用する
それぞれ簡単に取得方法を紹介しておきましょう。
なお、「@Value
」と「Type-safe Configuration Properties」には機能的な違い(制限)があるので、Spring Bootのリファレンスを参照しておくと良いと思います。「Type-safe Configuration Properties」ではSpELが利用できないので、プロパティ指定時にSpELを使う必要がある場合のみ@Value
を使えば良いと思います。
app.timezone=Asia/Tokyo
@Value
の利用
DIコンテナで管理するクラスのフィールド、setterメソッド、コンストラクタ引数などに@Value(${設定名:デフォルト値})
の形式で指定すると、指定した設定値がインジェクションされます。デフォルト値は省略可能ですが、デフォルト値が未指定の状態で設定値の指定がないとエラーになります。
@Component
public class AppProperties {
@Value("${app.timezone:UTC}")
private TimeZone timezone; // ← "app.timezone"の設定値がインジェクションされる
// ... getter/setter
}
Type-safe Configuration Propertiesの利用
DIコンテナで管理するクラスに@ConfigurationProperties
を付与すると、クラス内のプロパティに設定値(「prefix
属性に指定したプレフィック + "." + プロパティ名」の値)が自動的にインジェクションされます。デフォルト値を設けたい場合は、プロパティの初期値として指定してください。
@ConfigurationProperties("app")
public class AppProperties {
private TimeZone timezone = TimeZone.getTimeZone("UTC"); // ← "app.timezone"の設定値がインジェクションされる
// ... getter/setter
}
package com.example;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
@SpringBootApplication
@ConfigurationPropertiesScan // @ConfigurationPropertiesが付与されたクラスをスキャンしてDIコンテナに登録する
public class SpringBootPropertiesDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SpringBootPropertiesDemoApplication.class, args);
}
}
この方法は、Spring BootのAutoConfigureの中でも利用されています。
NOTE:
@ConfigurationPropertiesScan
はSpring Boot 2.2で追加されたアノテーションです。
Environment
インタフェースの利用
外部設定値は、Spring Frameworkが提供しているEnvironment
インタフェースのメソッドを介して取得することもできます。この方法を使うことは基本的にはないと思いますが、プログラム内で動的に取得先(設定名)を切り替えるような使い方をしたい場合は、この方法を利用を検討してみてください。
@Service
public class MyService {
private static final TimeZone DEFAULT_TIMEZONE= TimeZone.getTimeZone("UTC");
private final Environment environment;
public MyService(Environment environment) { // Environmentをインジェクション
this.environment = environment;
}
public void printApplicationManagedTimezone() {
TimeZone timezone = environment.getProperty("app.timezone", TimeZone.class, DEFAULT_TIMEZONE);
System.out.println(timezone);
}
}
外部設定値の指定方法
以下に、外部設定値の主な指定方法を(優先度が高い順に)紹介します。なお、個人的にたぶん利用しないだろうな〜と思った方法については説明は割愛します。(サポートしている指定方法の全量は、Spring Bootのリファレンスをご覧ください)
指定方法 | 説明 |
---|---|
Developer tools用のプロパティファイル |
Spring Boot Developer tools用のプロパティファイル(~/.config/spring-boot/spring-boot-devtools.properties )に「設定名=値 」の形式で指定する。(Spring Boot Developer toolsを適用している場合のみ) |
@TestPropertySource |
@TestPropertySource (テスト用のプロパティファイル or アノテーションの属性値)に「設定名=値 」の形式で指定する。テストケース内で設定値を指定したい場合に利用。 |
@SpringBootTest |
@SpringBootTest (@XxxxTest )のproperties 属性に「設定名=値 」の形式で指定する。テストケース内で設定値を指定したい場合に利用。 |
コマンドライン引数 | コマンドライン引数に「--設定名=値 」の形式で指定する。 |
JSONアプリケーションプロパティ | 環境変数「SPRING_APPLICATION_JSON」(プロパティ名「spring.application.json」)にJSON構造で設定名と設定値を指定する |
JVMのシステムプロパティ | JVMの起動引数に「-D設定名=値 」の形式で指定する。 |
OSの環境変数 | OSの環境変数に「設定名=値 」の形式で指定する。 |
Spring Boot専用のプロパティファイル | Spring Boot専用のプロパティファイル/YAMLファイルに「設定名=値 」の形式で指定する。 |
@PropertySource |
@PropertySource に指定した任意のプロパティファイルに「設定名=値 」の形式で指定する。 |
NOTE:
warとしてデプロイする場合は、JNDI、サーブレットコンテナのパラメータ、サーブレットの初期化パラメータにプロパティ値を指定することも可能ですが、warとしてデプロイするパターンはあまりないと思うので、本エントリーでは説明は割愛します。
Developer tools用のプロパティファイル
Spring Boot Developer toolsを適用している場合は、OSユーザーのホームディレクトリ直下の「~/.config/spring-boot/spring-boot-devtools.properties
」に開発者毎の設定値を指定することができます。
このプロパティファイルには、アプリケーションの機能的な動作仕様に影響を与えない設定値(例えば、ログレベルなど)のみ指定するように心がけましょう。さもないと・・・あなたの環境では仕様通り動くけど、他の環境では動かない・・・といった事象を引き起こすかもしれません
NOTE:
過去バージョンとの互換性を保つために、「
~/.config/spring-boot/spring-boot-devtools.properties
」が存在しない場合は「~/.spring-boot-devtools.properties
」を読み込む仕組みになっています。
@SpringBootTest
のproperties
属性の利用
特定のテストケースクラスのみで設定値を変更したい場合は、@SpringBootTest
のproperties
属性に直接設定値を指定することができます。
// ...
@SpringBootTest(properties = "app.timezone=Asia/Tokyo")
public class IntegrationTests {
// ...
}
NOTE:
@JdbcTest
などのアノテーションでサポートされているproperties
属性も同様の扱いになります。
具体的なアノテーションについては、Spring Bootのリファレンスを参照してください。
@TestPropertySource
の利用
複数のテストケースクラスでテスト用の設定値を共有したい場合は、プロパティファイルを使うとよいです。
// ...
@TestPropertySource(locations = "/test.properties")
public class IntegrationTests {
// ...
}
app.timezone=Asia/Tokyo
特定のテストケースクラスのみで設定値を変更したい場合は、properties
属性に直接設定値を指定することができます。これは、前述した@SpringBootTest
のproperties
属性で代替することができます。
// ...
@TestPropertySource(properties = "app.timezone=Asia/Tokyo")
public class IntegrationTests {
// ...
}
@TestPropertySource
の詳しい利用方法については、Spring Frameworkのリファレンスページをご覧ください。
コマンドライン引数の利用
アプリケーションの実行時に設定値を変更したい場合は、コマンドライン引数を使います。
$ java -jar xxx.jar --app.timezone=Asia/Tokyo
NOTE:
@SpringBootTest
のargs
属性を利用すると、テストでコマンドライン引数相当の指定をすることができます。// ... @SpringBootTest(args = "--app.timezone=Asia/Tokyo") public class IntegrationTests { // ... }
JSONアプリケーションプロパティ
環境変数やシステムプロパティには指定可能なプロパティに制限があるため、それら制限を回避するための方法として、環境変数名「SPRING_APPLICATION_JSON
」またはプロパティ名「spring.application.json
」にJSON形式でプロパティを指定することができます。
$ export SPRING_APPLICATION_JSON='{"app":{"timezone":"Asia/Tokyo"}}' && java -jar xxx.jar
$ java -Dspring.application.json='{"app":{"timezone":"Asia/Tokyo"}}' -jar xxx.jar
上記の例では、「app.timezone=Asia/Tokyo
」と同じ扱いになります。
JVMのシステムプロパティ
アプリケーションの実行時に設定値を変更したい場合は、JVMのシステムプロパティを使います。コマンドライン引数はSpring Boot独自の仕組みなのに対して、システムプロパティはJava標準の仕組みなので、Spring Bootの管理外のコンポーネントと設定値を共有したい場合は、システムプロパティの利用を検討するとよいでしょう。
$ java -Dapp.timezone=Asia/Tokyo -jar xxx.jar
OSの環境変数
アプリケーションを実行するOSユーザー毎に設定値を変更したい場合は、OSの環境変数(ユーザー環境変数)を使います。
$ APP_TIMEZONE=Asia/Tokyo
$ java -jar xxx.jar
環境変数(_
区切り)で指定した設定値は、「.
」や「-
」区切りの名前で参照することができます。上記の例であれば、Spring Bootからは「app.timezone
」または「app-timezone
」という名前を指定して値を取得することができます。
Spring Boot専用のプロパティファイル
Spring Bootは、Spring Bootアプリケーション専用のプロパティファイル/YAMLファイル(application.properties
またはapplication.yml
)を読み込む仕組みになっています。Spring Bootアプリケーション専用のプロパティファイル/YAMLファイルの特徴としては、プロファイル毎にプロパティファイル/YAMLファイルを用意できる点があげられます。
明示的にアクティブなプロファイルを指定しない場合は、暗黙的にdefault
というプロファイルを指定したことになり、以下の順番で設定値が適用されます。
-
application-default.properties
(or.yml
) -
application.properties
(or.yml
)
プロファイル指定時のプロパティファイルの読み込み
また、明示的にアクティブなプロファイルを指定した場合は、プロファイルの指定順とは逆順でプロパティファイル/YAMLファイルの設定値が適用されます。例えば、-Dspring.profiles.active=p1,p2
とした場合は、以下の順番で設定値が適用されます。
-
application-p2.properties
(or.yml
) -
application-p1.properties
(or.yml
) -
application.properties
(or.yml
)
プロファイルのインクルード時の読み込み
さらに・・・Spring Boot専用のプロパティファイル/YAMLファイルでは、以下のように指定するとプロファイルをインクルードすることができます。
spring.profiles.include=default,p3
プロファイルをインクルードした場合は、インクルード先のプロパティファイル/YAMLファイルが優先されます。例えば、アクティブなプロファイルを指定しなかったケースを例に見てみると、以下の順番で設定値が適用されます。
-
application-p3.properties
(or.yml
) -
application-default.properties
(or.yml
) -
application.properties
(or.yml
)
ポイントは、インクルードしたプロファイルのプロパティファイル/YAMLファイルの方が優先される点でしょう。たとえば以下のように、インクルード元でインクルード先に指定している設定値を上書きすることはできません。
app.timezone=PST
spring.profiles.include=default,p3
app.timezone=Asia/Tokyo
上記の例では、app.timezone
にはPST
が適用されます。
直感的には・・・ Asia/Tokyo
になってほしい気がしますが・・・現時点のSpring Bootでは上書でされません。
プロパティファイルの格納場所
Spring Boot専用のプロパティファイル/YAMLファイルは、デフォルトでは以下の場所に格納することができ、以下の順番で設定値が適用されます。
- アプリケーションの実行ディレクトリ直下の「config」ディレクトリのサブディレクトリ(
file:./config/*/
) - アプリケーションの実行ディレクトリ直下の「config」ディレクトリ(
file:./config/
) - アプリケーションの実行ディレクトリ(
file:./
) - クラスパス直下の「config」ディレクトリ(
classpath:/config/
) - クラスパス直下(
classpath:/
)
なお、プロパティファイルのベース名前(デフォルトはapplication
)の変更・格納ディレクトリの追加・対象ファイルの追加(任意のファイルを対象にする場合)などは、専用の外部設定値(spring.config.name
、spring.config.location
、spring.config.additional-location
)を指定することで実現することができます。詳しくは、「Spring Bootのリファレンスページ」をご覧ください。
YAMLファイルの利用
Spring Bootでは、プロパティファイルの代わりにYAMLファイルを利用することができます。YAML形式はプロパティ形式に比べてデータ構造を表現するのに優れているため、Spring Bootが提供する「Type-safe Configuration Properties」との相性がよいです。
app:
name: MyApp
本投稿ではYAMLファイルの使い方については説明は割愛するため、YAMLファイルを利用する場合は「Spring Bootのリファレンスページ」をご覧ください。
@PropertySource
の利用
Spring Bootでは、Spring Frameworkが提供している@PropertySource
を使用して任意のプロパティファイルを読み込むこともできます。
@SpringBootApplication
@PropertySource("classpath:security.properties")
public class SpringBootDemoApplication {
// ...
}
プロパティ値の置き換え(プレースホルダの利用)
プロパティファイルやYAMLファイル内では、プレースホルダを利用してプロパティ値に別の外部設定値を埋め込むことができます。
app.name=MyApp
app.description=${app.name} is a Spring Boot application
app:
name: MyApp
description: ${app.name} is a Spring Boot application
さらに、Spring Bootは乱数を埋め込むための特別の設定値(random.
で始まる設定値)を提供しています。詳しくは、「Spring Bootのリファレンスページ」をご覧ください。
まとめ
今回は、Spring Bootアプリケーションで外部設定値を扱う方法について紹介してみました。外部設定の管理は、アプリケーションを作る上で絶対に欠かすことができない技術要素の一つといえます。Spring Bootの場合は、実行環境に依存する設定値はプロファイル毎のプロパティファイル/YAMLファイルに定義し、アプリケーション起動時のパラメータ(spring.profiles.acive)で利用するプロファイルを切り替えるのが標準的な管理方法になります。
なお、本投稿では触れていない部分もいくつかあるので、ちゃんと把握したい方はSpring Bootのリファレンスページを一読することをお勧めします。
- https://docs.spring.io/spring-boot/docs/2.4.5/reference/htmlsingle/#boot-features-external-config
- https://docs.spring.io/spring-boot/docs/2.4.5/reference/htmlsingle/#howto-properties-and-configuration
参考サイト
- https://docs.spring.io/spring-boot/docs/2.4.5/reference/htmlsingle/#boot-features-external-config
- https://docs.spring.io/spring-boot/docs/2.4.5/reference/htmlsingle/#howto-properties-and-configuration
- https://docs.spring.io/spring-framework/docs/5.3.6/reference/html/testing.html#testcontext-ctx-management-property-sources
- https://docs.spring.io/spring-framework/docs/5.3.6/reference/html/core.html#beans-using-propertysource