プロパティと構成

このセクションには、プロパティおよび構成設定の設定と読み取り、および Spring Boot アプリケーションとの相互作用に関するトピックが含まれています。

ビルド時にプロパティを自動的に展開

プロジェクトのビルド構成でも指定されている一部のプロパティをハードコードするのではなく、既存のビルド構成を代わりに使用して自動的に展開できます。これは、Maven と Gradle の両方で可能です。

Maven を使用した自動プロパティ拡張

リソースフィルタリングを使用すると、Maven プロジェクトのプロパティを自動的に展開できます。spring-boot-starter-parent を使用すると、次の例に示すように、@..@ プレースホルダーを使用して Maven の「プロジェクトプロパティ」を参照できます。

  • プロパティ

  • YAML

[email protected] (英語)  @
[email protected] (英語)  @
app:
  encoding: "@project.build.sourceEncoding@"
  java:
    version: "@java.version@"
そのようにフィルタリングされるのは本番構成のみです（言い換えると、src/test/resources にはフィルタリングは適用されません）。
addResources フラグを有効にすると、spring-boot:run ゴールは src/main/resources をクラスパスに直接追加できます（ホットリロードの目的で）。そうすることで、リソースフィルタリングとこの機能が回避されます。代わりに、exec:java ゴールを使用するか、プラグインの構成をカスタマイズできます。詳細については、プラグインの使用ページを参照してください。

スターターの親を使用しない場合は、pom.xml の <build/> 要素内に次の要素を含める必要があります。

<resources>
	<resource>
		<directory>src/main/resources</directory>
		<filtering>true</filtering>
	</resource>
</resources>

また、<plugins/> 内に次の要素を含める必要があります。

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-resources-plugin</artifactId>
	<version>2.7</version>
	<configuration>
		<delimiters>
			<delimiter>@</delimiter>
		</delimiters>
		<useDefaultDelimiters>false</useDefaultDelimiters>
	</configuration>
</plugin>
構成で標準 Spring プレースホルダー（${placeholder} など）を使用する場合、useDefaultDelimiters プロパティは重要です。そのプロパティが false に設定されていない場合、これらはビルドによって拡張される可能性があります。

Gradle を使用した自動プロパティ拡張

次の例に示すように、Java プラグインの processResources タスクを構成することにより、Gradle プロジェクトからプロパティを自動的に展開できます。

tasks.named('processResources') {
	expand(project.properties)
}

その後、次の例に示すように、プレースホルダーを使用して Gradle プロジェクトのプロパティを参照できます。

  • プロパティ

  • YAML

app.name=${name}
app.description=${description}
app:
  name: "${name}"
  description: "${description}"
Gradle の expand メソッドは、Groovy の SimpleTemplateEngine を使用して、${..} トークンを変換します。${..} スタイルは、Spring 独自のプロパティプレースホルダーメカニズムと競合します。Spring プロパティプレースホルダーと自動展開を併用するには、Spring プロパティプレースホルダーを次のようにエスケープします: \${..}。

SpringApplication の設定の外部化

SpringApplication には Bean プロパティ setter があるため、アプリケーションを作成するときにその Java API を使用して、その動作を変更できます。または、spring.main.* でプロパティを設定して、設定を外部化することもできます。例: application.properties では、次の設定がある場合があります。

  • プロパティ

  • YAML

spring.main.web-application-type=none
spring.main.banner-mode=off
spring:
  main:
    web-application-type: "none"
    banner-mode: "off"

その場合、起動時に Spring Boot バナーは出力されず、アプリケーションは組み込み Web サーバーを起動しません。

外部構成で定義されたプロパティは、プライマリソースを除いて、JavaAPI で指定された値をオーバーライドおよび置換します。一次ソースは、SpringApplication コンストラクターに提供されるものです。

  • Java

  • Kotlin

import org.springframework.boot.Banner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

	public static void main(String[] args) {
		SpringApplication application = new SpringApplication(MyApplication.class);
		application.setBannerMode(Banner.Mode.OFF);
		application.run(args);
	}

}
import org.springframework.boot.Banner
import org.springframework.boot.SpringApplication
import org.springframework.boot.autoconfigure.SpringBootApplication

@SpringBootApplication
object MyApplication {

	@JvmStatic
	fun main(args: Array<String>) {
		val application = SpringApplication(MyApplication::class.java)
		application.setBannerMode(Banner.Mode.OFF)
		application.run(*args)
	}

}

または SpringApplicationBuilder の sources(…​) メソッドへ:

  • Java

  • Kotlin

import org.springframework.boot.Banner;
import org.springframework.boot.builder.SpringApplicationBuilder;

public class MyApplication {

	public static void main(String[] args) {
		new SpringApplicationBuilder()
			.bannerMode(Banner.Mode.OFF)
			.sources(MyApplication.class)
			.run(args);
	}

}
import org.springframework.boot.Banner
import org.springframework.boot.builder.SpringApplicationBuilder

object MyApplication {

	@JvmStatic
	fun main(args: Array<String>) {
		SpringApplicationBuilder()
			.bannerMode(Banner.Mode.OFF)
			.sources(MyApplication::class.java)
			.run(*args)
	}

}

上記の例で、次の構成がある場合:

  • プロパティ

  • YAML

spring.main.sources=com.example.MyDatabaseConfig,com.example.MyJmsConfig
spring.main.banner-mode=console
spring:
  main:
    sources: "com.example.MyDatabaseConfig,com.example.MyJmsConfig"
    banner-mode: "console"

実際のアプリケーションはバナーを表示し (構成によって上書きされます)、ApplicationContext の 3 つのソースを使用します。アプリケーションソースは次のとおりです。

  1. MyApplication (コードから)

  2. MyDatabaseConfig (外部設定から)

  3. MyJmsConfig (外部設定から)

アプリケーションの外部プロパティの場所を変更する

デフォルトでは、異なるソースのプロパティが定義済みの順序で Spring Environment に追加されます（正確な順序については、「Spring Boot 機能」セクションの "環境別の設定切り替え" を参照してください）。

次のシステムプロパティ（または環境変数）を指定して、動作を変更することもできます。

  • spring.config.name (SPRING_CONFIG_NAME): ファイル名のルートとしてのデフォルトは application です。

  • spring.config.location (SPRING_CONFIG_LOCATION): ロードするファイル（クラスパスリソースや URL など）。このドキュメントには別の Environment プロパティソースが設定されており、システムプロパティ、環境変数、コマンドラインによってオーバーライドできます。

環境に何を設定しても、Spring Boot は常に上記のように application.properties をロードします。デフォルトでは、YAML が使用されている場合、".yaml" および ".yml" 拡張子を持つファイルもリストに追加されます。

ロードされているファイルに関する詳細情報が必要な場合は、org.springframework.boot.context.config のログレベルを trace に設定できます。

「短い」コマンドライン引数を使用する

コマンドラインで設定プロパティを設定するために、--server.port=9000 の代わりに --port=9000 を使用したい人もいます。次の例に示すように、application.properties のプレースホルダーを使用して、この動作を有効にできます。

  • プロパティ

  • YAML

server.port=${port:8080}
server:
  port: "${port:8080}"
spring-boot-starter-parent POM から継承する場合、maven-resources-plugins のデフォルトのフィルタートークンは ${*} から @ （つまり、${maven.token} ではなく @maven.token@）に変更され、Spring スタイルのプレースホルダーとの競合を防ぎます。application.properties の Maven フィルタリングを直接有効にしている場合は、デフォルトのフィルタートークンを変更して、他の区切り文字 [Apache] (英語) を使用することもできます。
この特定のケースでは、ポートバインディングは Heroku や Cloud Foundry などの PaaS 環境で機能します。これら 2 つのプラットフォームでは、PORT 環境変数が自動的に設定され、Spring は Environment プロパティの大文字のシノニムにバインドできます。

外部プロパティに YAML を使用する

YAML は JSON のスーパーセットであるため、次の例に示すように、外部プロパティを階層形式で保存するための便利な構文です。

spring:
  application:
    name: "cruncher"
  datasource:
    driver-class-name: "com.mysql.jdbc.Driver"
    url: "jdbc:mysql://localhost/test"
server:
  port: 9000

application.yaml というファイルを作成し、クラスパスのルートに配置します。次に、snakeyaml を依存関係に追加します（Maven は org.yaml:snakeyaml を調整します。spring-boot-starter を使用する場合はすでに含まれています）。YAML ファイルは Java Map<String,Object> （JSON オブジェクトのように）に解析され、Spring Boot はマップをフラット化して、Java の Properties ファイルで多くの人が慣れているように、1 レベルの深さでピリオドで区切られたキーを持つようにします。

前述の YAML の例は、次の application.properties ファイルに対応しています。

spring.application.name=cruncher
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://localhost/test
server.port=9000

YAML の詳細については、「Spring Boot 機能」セクションの "YAML の操作" を参照してください。

アクティブ Spring プロファイルを設定する

Spring Environment にはこのための API がありますが、通常はシステムプロパティ（spring.profiles.active）または OS 環境変数（SPRING_PROFILES_ACTIVE）を設定します。また、次のように、-D 引数を使用してアプリケーションを起動できます（メインクラスまたは jar アーカイブの前に配置することを忘れないでください）。

$ java -jar -Dspring.profiles.active=production demo-0.0.1-SNAPSHOT.jar

Spring Boot では、次の例に示すように、application.properties でアクティブなプロファイルを設定することもできます。

  • プロパティ

  • YAML

spring.profiles.active=production
spring:
  profiles:
    active: "production"

この方法で設定された値は、SpringApplicationBuilder.profiles() メソッドではなく、システムプロパティまたは環境変数の設定に置き換えられます。後者の Java API を使用して、デフォルトを変更せずにプロファイルを拡張できます。

詳細については、「Spring Boot 機能」セクションの "プロファイル" を参照してください。

デフォルトのプロファイル名の設定

デフォルトのプロファイルは、アクティブなプロファイルがない場合に有効になるプロファイルです。デフォルトでは、デフォルトプロファイルの名前は default ですが、System プロパティ（spring.profiles.default）または OS 環境変数（SPRING_PROFILES_DEFAULT）を使用して変更できます。

Spring Boot では、次の例に示すように、application.properties でデフォルトのプロファイル名を設定することもできます。

  • プロパティ

  • YAML

spring.profiles.default=dev
spring:
  profiles:
    default: "dev"

詳細については、「Spring Boot 機能」セクションの "プロファイル" を参照してください。

環境に応じて構成を変更する

Spring Boot は、アクティブなプロファイルに基づいて条件付きでアクティブ化できるマルチドキュメント YAML ファイルとプロパティファイル（詳細はマルチドキュメントファイルの操作を参照）をサポートしています。

ドキュメントに spring.config.activate.on-profile キーが含まれている場合、プロファイル値 (プロファイルのコンマ区切りリストまたはプロファイル式) が Spring Environment.acceptsProfiles() メソッドに渡されます。プロファイル式が一致する場合、そのドキュメントは最終マージに含まれます (そうでない場合は含まれません)。次の例を参照してください。

  • プロパティ

  • YAML

server.port=9000
#---
spring.config.activate.on-profile=development
server.port=9001
#---
spring.config.activate.on-profile=production
server.port=0
server:
  port: 9000
---
spring:
  config:
    activate:
      on-profile: "development"
server:
  port: 9001
---
spring:
  config:
    activate:
      on-profile: "production"
server:
  port: 0

上記の例では、デフォルトのポートは 9000 です。ただし、「開発」という Spring プロファイルがアクティブな場合、ポートは 9001 です。「本番」がアクティブな場合、ポートは 0 です。

ドキュメントは、検出された順序でマージされます。後の値は前の値を上書きします。

外部プロパティの組み込みオプションを理解する

Spring Boot は、実行時に application.properties (または YAML ファイルやその他の場所) からの外部プロパティをアプリケーションにバインドします。クラスパス上の追加の jar ファイルから提供される可能性があるため、サポートされているすべてのプロパティの完全なリストを 1 つの場所にまとめることはできません (技術的には不可能です)。

アクチュエーター機能を備えた実行中のアプリケーションには、configprops エンドポイントがあり、@ConfigurationProperties を介して使用可能なすべてのバインド済みプロパティとバインド可能プロパティが表示されます。

付録には、Spring Boot でサポートされる最も一般的なプロパティのリストを含む application.properties の例が含まれています。最終的なリストは、@ConfigurationProperties および @Value アノテーションのソースコードを検索することと、Binder をときどき使用することから得られます。読み込みプロパティの正確な順序の詳細については、"環境別の設定切り替え" を参照してください。