Qiita Teams that are logged in
You are not logged in to any team
Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
SignupLogin
Azure利用時の設計原則Microsoft Azure Well-Architected Frameworkを読み解く詳しくはこちら
325
336
Improve article
Send edit request
Article information
RevisionsEdit RequestsShow all likersShow article in Markdown
Report article
Help us understand the problem. What is going on with this article?
@kazuki43zoo

Spring Bootの外部設定値の扱い方を理解する

Javaspringspring-boot

今回は外部設定値（プロパティファイル、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系からかなり機能追加・改善が行われているため、

  • 「バージョンアップに伴う記載内容の見直し（必要最小限の修正）」
  • 「機能追加部分の説明追加」

の２回に分けて更新したいと思います。まずは、「バージョンアップに伴う記載内容の見直し」になります。

外部設定として扱う値は？

アプリケーションを作成する場合、ソースコード上にハードコーディングできない（or したくない）値を扱うことがよくあります。具体的には・・・以下のような値が外部設定値として扱う候補になります。

  • データベースへの接続情報などの環境に依存する値
  • 機能要件で決められたアプリケーションの動作を変更するためのパラメータ値
  • 機能要件上はパラメータ化する必要はないけどテスト容易性などを考慮して外部化しておいた方がよい値
  • 性能要件に応じてチューニングが必要になる事が想定されるパラメータ値
  • etc..

外部設定値の取得方法

Spring Bootアプリケーションでは、以下のいずれかの方法で外部設定値を取得することができます。

  • Spring Frameworkが提供している@Valueを使用する
  • Spring Bootが提供している「Type-safe Configuration Properties」の仕組みを利用する （基本的にはこの仕組みを使うのがお勧めです :laughing: :laughing: :laughing:）
  • Spring Frameworkが提供しているEnvironmentインタフェースを利用する

それぞれ簡単に取得方法を紹介しておきましょう。

なお、「@Value」と「Type-safe Configuration Properties」には機能的な違い（制限）があるので、Spring Bootのリファレンスを参照しておくと良いと思います。「Type-safe Configuration Properties」ではSpELが利用できないので、プロパティ指定時にSpELを使う必要がある場合のみ@Valueを使えば良いと思います。

src/main/resources/application.properties
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」に開発者毎の設定値を指定することができます。
このプロパティファイルには、アプリケーションの機能的な動作仕様に影響を与えない設定値（例えば、ログレベルなど）のみ指定するように心がけましょう。さもないと・・・あなたの環境では仕様通り動くけど、他の環境では動かない・・・といった事象を引き起こすかもしれません :scream:

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 {
    // ...
}
テスト用のプロパティファイル（test.properties）
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ファイルでは、以下のように指定するとプロファイルをインクルードすることができます。

application.properties
spring.profiles.include=default,p3

プロファイルをインクルードした場合は、インクルード先のプロパティファイル/YAMLファイルが優先されます。例えば、アクティブなプロファイルを指定しなかったケースを例に見てみると、以下の順番で設定値が適用されます。

  • application-p3.properties (or .yml)
  • application-default.properties (or .yml)
  • application.properties (or .yml)

ポイントは、インクルードしたプロファイルのプロパティファイル/YAMLファイルの方が優先される点でしょう。たとえば以下のように、インクルード元でインクルード先に指定している設定値を上書きすることはできません。

application-p3.properties(インクルード先)
app.timezone=PST
application.properties(インクルード元)
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」との相性がよいです。

application.yml
app:
    name: MyApp

本投稿ではYAMLファイルの使い方については説明は割愛するため、YAMLファイルを利用する場合は「Spring Bootのリファレンスページ」をご覧ください。

@PropertySourceの利用

Spring Bootでは、Spring Frameworkが提供している@PropertySourceを使用して任意のプロパティファイルを読み込むこともできます。

@SpringBootApplication
@PropertySource("classpath:security.properties")
public class SpringBootDemoApplication  {
    // ...
}

プロパティ値の置き換え（プレースホルダの利用）

プロパティファイルやYAMLファイル内では、プレースホルダを利用してプロパティ値に別の外部設定値を埋め込むことができます。

application.properties
app.name=MyApp
app.description=${app.name} is a Spring Boot application
application.yml
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のリファレンスページを一読することをお勧めします。

参考サイト

325
336
Improve article
Send edit request
Article information
RevisionsEdit RequestsShow all likersShow article in Markdown
Report article
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
kazuki43zoo
Javaエンジニアで、SpringやMyBatisらへんにそれなりに詳しいです。お仕事のつながりで「Spring徹底入門 Spring FrameworkによるJavaアプリケーション開発」を共著させてもらいました！

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
325
336
Improve article
Send edit request
Article information
RevisionsEdit RequestsShow all likersShow article in Markdown
Report article
Help us understand the problem. What is going on with this article?