プロパティと構成

このセクションには、プロパティおよび構成設定の設定と読み取り、および 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 (Javadoc) には 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 サーバーを起動しません。

外部構成で定義されたプロパティは、プライマリソースを除いて、Java API で指定された値をオーバーライドして置き換えます。プライマリソースは、SpringApplication (Javadoc) コンストラクターに提供されるものです。

  • 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 (Javadoc) の 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 (Javadoc) の 3 つのソースを使用します。アプリケーションソースは次のとおりです。

  1. MyApplication (コードから)

  2. MyDatabaseConfig (外部設定から)

  3. MyJmsConfig (外部設定から)

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

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

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

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

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

環境に何を設定しても、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 (Javadoc) プロパティの大文字のシノニムにバインドできます。

外部プロパティに 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 はマップをフラット化して 1 レベルの深さにし、ピリオドで区切られたキーを持つようにします。これは、多くの人が Java の Properties (標準 Javadoc) ファイルで慣れているものです。

前述の 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 (Javadoc) にはこのための 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 つの場所にまとめることはできません (技術的には不可能です)。

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

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