1. 導入

Spring Boot Gradle プラグインは、Gradle (英語) で Spring Boot サポートを提供します。次のことができます。パッケージの実行可能ファイル jar または war アーカイブ、Spring Boot アプリケーションの実行、および spring-boot-dependencies によって提供される依存関係管理の使用。Spring Boot の Gradle プラグインには Gradle 5.x または 6.x が必要です(4.10 もサポートされていますが、このサポートは非推奨であり、将来のリリースで削除される予定です)。

このユーザーガイドに加えて、API ドキュメントも利用できます。

2. 入門

プラグインを開始するには、プロジェクトに適用する必要があります。

プラグインは Gradle のプラグインポータルに公開 (英語) され、plugins ブロックを使用して適用できます。

Groovy
plugins {
	id 'org.springframework.boot' version '2.2.5.RELEASE'
}
Kotlin
plugins {
	id("org.springframework.boot") version "2.2.5.RELEASE"
}

プラグインは単独で適用され、プロジェクトにほとんど変更を加えません。代わりに、プラグインは特定の他のプラグインが適用されたことを検出し、それに応じて反応します。例:java プラグインが適用されると、実行可能な jar をビルドするタスクが自動的に構成されます。典型的な Spring Boot プロジェクトは、groovy (英語) java (英語) 、または org.jetbrains.kotlin.jvm (英語) プラグインと io.spring.dependency-management (GitHub) プラグインを最低限適用します。例:

Groovy
apply plugin: 'java'
apply plugin: 'io.spring.dependency-management'
Kotlin
plugins {
	java
	id("org.springframework.boot") version "2.2.5.RELEASE"
}

apply(plugin = "io.spring.dependency-management")

他のプラグインが適用された場合の Spring Boot プラグインの動作の詳細については、他のプラグインへの反応に関するセクションを参照してください。

3. 依存関係の管理

io.spring.dependency-management (GitHub) プラグインを適用すると、Spring Boot のプラグインは、使用している Spring Boot のバージョンから spring-boot-dependenciesbom を自動的にインポートします。これにより、Maven ユーザーが楽しんでいるものと同様の依存関係管理エクスペリエンスが提供されます。例:BOM で管理される依存関係を宣言するときにバージョン番号を省略することができます。この機能を利用するには、通常の方法で依存関係を宣言しますが、バージョン番号は省略します。

Groovy
dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
}
Kotlin
dependencies {
	implementation("org.springframework.boot:spring-boot-starter-web")
	implementation("org.springframework.boot:spring-boot-starter-data-jpa")
}

3.1. 管理対象バージョンのカスタマイズ

依存関係管理プラグインの適用時に自動的にインポートされる spring-boot-dependenciesbom は、プロパティを使用して、管理する依存関係のバージョンを制御します。これらのプロパティの完全なリストについては、bom (GitHub) を参照してください。

管理対象バージョンをカスタマイズするには、対応するプロパティを設定します。例:slf4j.version プロパティによって制御される SLF4J のバージョンをカスタマイズするには:

Groovy
ext['slf4j.version'] = '1.7.20'
Kotlin
extra["slf4j.version"] = "1.7.20"
各 Spring Boot リリースは、サードパーティの特定の依存関係セットに対して設計およびテストされています。バージョンを上書きすると互換性の課題が発生する可能性があるため、注意して行う必要があります。

3.2. Spring Boot の依存関係管理を単独で使用する

Spring Boot の依存関係管理は、Spring Boot のプラグインをそのプロジェクトに適用せずにプロジェクトで使用できます。SpringBootPlugin クラスは、グループ ID、アーティファクト ID、またはバージョンを知らなくても BOM をインポートするために使用できる BOM_COORDINATES 定数を提供します。

まず、Spring Boot プラグインに依存するようにプロジェクトを構成しますが、適用しません。

Groovy
plugins {
	id 'org.springframework.boot' version '2.2.5.RELEASE' apply false
}
Kotlin
plugins {
	id("org.springframework.boot") version "2.2.5.RELEASE" apply false
}

Spring Boot プラグインの依存関係管理プラグインへの依存関係は、依存関係を宣言することなく依存関係管理プラグインを使用できることを意味します。これは、Spring Boot が使用するのと同じバージョンの依存関係管理プラグインを自動的に使用することも意味します。

依存関係管理プラグインを適用し、Spring Boot の bom をインポートするように構成します。

Groovy
apply plugin: 'io.spring.dependency-management'

dependencyManagement {
	imports {
		mavenBom org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES
	}
}
Kotlin
apply(plugin = "io.spring.dependency-management")

the<DependencyManagementExtension>().apply {
	imports {
		mavenBom(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
	}
}

上記の Kotlin コードは少し厄介です。これは、依存関係管理プラグインを必須の方法で適用しているためです。

ルートの親プロジェクトからプラグインを適用するか、Spring Boot プラグインで行っているように plugins ブロックを使用することで、コードをより扱いにくくすることができます。このメソッドの欠点は、依存関係管理プラグインのバージョンを指定する必要があることです:

plugins {
	java
	id("org.springframework.boot") version "2.2.5.RELEASE" apply false
	id("io.spring.dependency-management") version "1.0.9.RELEASE"
}

dependencyManagement {
	imports {
		mavenBom(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
	}
}

3.3. さらに学ぶ

依存関係管理プラグインの機能の詳細については、そのドキュメント (GitHub) を参照してください。

4. 実行可能アーカイブのパッケージ化

プラグインは、アプリケーションのすべての依存関係を含む実行可能アーカイブ(jar ファイルおよび war ファイル)を作成し、java -jar で実行できます。

4.1. 実行可能 jar のパッケージ化

bootJar タスクを使用して、実行可能 jar を構築できます。タスクは、java プラグインが適用されるときに自動的に作成され、BootJar(Javadoc) のインスタンスです。assemble タスクは bootJar タスクに依存するように自動的に構成されるため、assemble(または build)を実行すると bootJar タスクも実行されます。

4.2. 実行可能 war のパッケージング

bootWar タスクを使用して、実行可能な war を構築できます。タスクは、war プラグインが適用されるときに自動的に作成され、BootWar(Javadoc) のインスタンスです。assemble タスクは bootWar タスクに依存するように自動的に構成されるため、assemble(または build)を実行すると bootWar タスクも実行されます。

4.2.1. 実行可能およびデプロイ可能な war のパッケージ化

war ファイルは、java -jar を使用して実行し、外部コンテナーにデプロイできるようにパッケージ化できます。これを行うには、providedRuntime 構成に埋め込みサーブレットコンテナーの依存関係を追加する必要があります。例:

Groovy
dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
}
Kotlin
dependencies {
	implementation("org.springframework.boot:spring-boot-starter-web")
	providedRuntime("org.springframework.boot:spring-boot-starter-tomcat")
}

これにより、外部コンテナーのクラスと競合しない war ファイルの WEB-INF/lib-provided ディレクトリに確実にパッケージ化されます。

providedRuntime は、Gradle の compileOnly 構成よりも優先されます。他の制限の中でも、compileOnly の依存関係はテストクラスパスにないため、Web ベースの統合テストは失敗します。

4.3. 実行可能ファイルと通常のアーカイブのパッケージ化

デフォルトでは、bootJar または bootWar タスクが構成されている場合、jar または war タスクは無効になっています。jar または war タスクを有効にすることにより、実行可能なアーカイブと通常のアーカイブの両方を同時にビルドするようにプロジェクトを構成できます。

Groovy
jar {
	enabled = true
}
Kotlin
tasks.getByName<Jar>("jar") {
	enabled = true
}

実行可能アーカイブと通常のアーカイブが同じ場所に書き込まれないようにするには、どちらか一方を別の場所を使用するように構成する必要があります。そのための 1 つの方法は、分類子を構成することです。

Groovy
bootJar {
	classifier = 'boot'
}
Kotlin
tasks.getByName<BootJar>("bootJar") {
	classifier = "boot"
}

4.4. 実行可能アーカイブパッケージの構成

BootJar(Javadoc) および BootWar(Javadoc) タスクは、それぞれ Gradle の Jar および War タスクのサブクラスです。その結果、jar または war をパッケージ化するときに使用できるすべての標準構成オプションは、実行可能な jar または war をパッケージ化するときにも使用できます。実行可能 jar および war に固有の多くの構成オプションも提供されます。

4.4.1. メインクラスの構成

デフォルトでは、実行可能アーカイブのメインクラスは、タスクのクラスパス上のディレクトリで public static void main(String[]) メソッドを持つクラスを探すことにより自動的に構成されます。

メインクラスは、タスクの mainClassName プロパティを使用して明示的に構成することもできます。

Groovy
bootJar {
	mainClassName = 'com.example.ExampleApplication'
}
Kotlin
tasks.getByName<BootJar>("bootJar") {
	mainClassName = "com.example.ExampleApplication"
}

または、Spring Boot DSL の mainClassName プロパティを使用して、プロジェクト全体でメインクラス名を設定できます。

Groovy
springBoot {
	mainClassName = 'com.example.ExampleApplication'
}
Kotlin
springBoot {
	mainClassName = "com.example.ExampleApplication"
}

application プラグイン (英語) が適用されている場合、その mainClassName プロジェクトプロパティを設定する必要があり、同じ目的で使用できます。

Groovy
mainClassName = 'com.example.ExampleApplication'
Kotlin
application {
	mainClassName = "com.example.ExampleApplication"
}

最後に、タスクのマニフェストで Start-Class 属性を構成できます。

Groovy
bootJar {
	manifest {
		attributes 'Start-Class': 'com.example.ExampleApplication'
	}
}
Kotlin
tasks.getByName<BootJar>("bootJar") {
	manifest {
		attributes("Start-Class" to "com.example.ExampleApplication")
	}
}

4.4.2. Devtools を除外する

デフォルトでは、Spring Boot の Devtools モジュール org.springframework.boot:spring-boot-devtools は、実行可能な jar または war から除外されます。アーカイブに Devtools を含める場合は、excludeDevtools プロパティを false に設定します。

Groovy
bootWar {
	excludeDevtools = false
}
Kotlin
tasks.getByName<BootWar>("bootWar") {
	isExcludeDevtools = false
}

4.4.3. 解凍が必要なライブラリの構成

ほとんどのライブラリは、実行可能アーカイブにネストされている場合に直接使用できますが、特定のライブラリには問題がある場合があります。例:JRuby には、jruby-complete.jar が常にファイルシステムで直接利用可能であることを前提とする独自のネストされた jar サポートが含まれています。

問題のあるライブラリを処理するために、実行可能アーカイブは、実行可能アーカイブの実行時に特定のネストされた jar を一時フォルダーに解凍するように構成できます。ライブラリは、ソース jar ファイルの絶対パスと一致する Ant スタイルのパターンを使用して、解凍が必要であると識別できます。

Groovy
bootJar {
	requiresUnpack '**/jruby-complete-*.jar'
}
Kotlin
tasks.getByName<BootJar>("bootJar") {
	requiresUnpack("**/jruby-complete-*.jar")
}

さらに制御するために、クロージャを使用することもできます。クロージャには FileTreeElement が渡され、開梱が必要かどうかを示す boolean を返す必要があります。

4.4.4. アーカイブを完全に実行可能にする

Spring Boot は、完全に実行可能なアーカイブのサポートを提供します。アーカイブは、アプリケーションの起動方法を知っているシェルスクリプトを先頭に追加することにより、完全に実行可能になります。Unix ライクなプラットフォームでは、この起動スクリプトにより、アーカイブを他の実行可能ファイルのように直接実行したり、サービスとしてインストールしたりできます。

この機能を使用するには、起動スクリプトの組み込みを有効にする必要があります。

Groovy
bootJar {
	launchScript()
}
Kotlin
tasks.getByName<BootJar>("bootJar") {
	launchScript()
}

これにより、Spring Boot のデフォルトの起動スクリプトがアーカイブに追加されます。デフォルトの起動スクリプトには、適切なデフォルト値を持ついくつかのプロパティが含まれています。値は、properties プロパティを使用してカスタマイズできます。

Groovy
bootJar {
	launchScript {
		properties 'logFilename': 'example-app.log'
	}
}
Kotlin
tasks.getByName<BootJar>("bootJar") {
	launchScript {
		properties(mapOf("logFilename" to "example-app.log"))
	}
}

デフォルトの起動スクリプトがニーズを満たさない場合、script プロパティを使用してカスタム起動スクリプトを提供できます。

Groovy
bootJar {
	launchScript {
		script = file('src/custom.script')
	}
}
Kotlin
tasks.getByName<BootJar>("bootJar") {
	launchScript {
		script = file("src/custom.script")
	}
}

4.4.5. PropertiesLauncher を使用する

PropertiesLauncher を使用して実行可能な jar または war を起動するには、タスクのマニフェストを構成して Main-Class 属性を設定します。

Groovy
bootWar {
	manifest {
		attributes 'Main-Class': 'org.springframework.boot.loader.PropertiesLauncher'
	}
}
Kotlin
tasks.getByName<BootWar>("bootWar") {
	manifest {
		attributes("Main-Class" to "org.springframework.boot.loader.PropertiesLauncher")
	}
}

5. アプリケーションの公開

5.1. maven プラグインを使用した公開

maven プラグイン (英語) が適用されると、uploadBootArchives という名前の bootArchives 構成の Upload タスクが自動的に作成されます。デフォルトでは、bootArchives 構成には、bootJar または bootWar タスクによって作成されたアーカイブが含まれています。uploadBootArchives タスクは、アーカイブを Maven リポジトリに公開するように構成できます。

Groovy
uploadBootArchives {
	repositories {
		mavenDeployer {
			repository url: 'https://repo.example.com'
		}
	}
}
Kotlin
tasks.getByName<Upload>("uploadBootArchives") {
	repositories.withGroovyBuilder {
		"mavenDeployer" {
			"repository"("url" to "https://repo.example.com")
		}
	}
}

5.2. maven-publish プラグインを使用した公開

Spring Boot jar または war を公開するには、MavenPublicationartifact メソッドを使用して公開に追加します。公開するアーティファクトを生成するタスクを artifact メソッドに渡します。例:デフォルトの bootJar タスクによって生成されたアーティファクトを公開するには:

Groovy
publishing {
	publications {
		bootJava(MavenPublication) {
			artifact bootJar
		}
	}
	repositories {
		maven {
			url 'https://repo.example.com'
		}
	}
}
Kotlin
publishing {
	publications {
		create<MavenPublication>("bootJava") {
			artifact(tasks.getByName("bootJar"))
		}
	}
	repositories {
		maven {
			url = uri("https://repo.example.com")
		}
	}
}

5.3. application プラグインで配布する

application プラグイン (英語) が適用されると、boot という名前のディストリビューションが作成されます。この配布には、bootJar または bootWar タスクによって作成されたアーカイブと、Unix ライクなプラットフォームおよび Windows でそれを起動するスクリプトが含まれています。Zip および tar ディストリビューションは、それぞれ bootDistZip および bootDistTar タスクによって構築できます。application プラグインを使用するには、mainClassName プロパティをアプリケーションのメインクラスの名前で構成する必要があります。

6. Gradle を使用してアプリケーションを実行する

最初にアーカイブを作成せずにアプリケーションを実行するには、bootRun タスクを使用します。

$ ./gradlew bootRun

bootRun タスクは、JavaExec サブクラスである BootRun(Javadoc) のインスタンスです。そのため、Gradle で Java プロセスを実行するための通常の構成オプション (英語) はすべて利用可能です。タスクは、メインソースセットのランタイムクラスパスを使用するように自動的に構成されます。

デフォルトでは、メインクラスは、タスクのクラスパス上のディレクトリで public static void main(String[]) メソッドを持つクラスを探すことで自動的に構成されます。

メインクラスは、タスクの main プロパティを使用して明示的に構成することもできます。

Groovy
bootRun {
	main = 'com.example.ExampleApplication'
}
Kotlin
tasks.getByName<BootRun>("bootRun") {
	main = "com.example.ExampleApplication"
}

または、Spring Boot DSL の mainClassName プロパティを使用して、プロジェクト全体でメインクラス名を設定できます。

Groovy
springBoot {
	mainClassName = 'com.example.ExampleApplication'
}
Kotlin
springBoot {
	mainClassName = "com.example.ExampleApplication"
}

デフォルトでは、bootRun は、開発中の起動を高速化するために起動を最適化するように JVM を構成します。この動作は、次の例に示すように、optimizedLaunch プロパティを使用して無効にできます。

Groovy
bootRun {
	optimizedLaunch = false
}
Kotlin
tasks.getByName<BootRun>("bootRun") {
	isOptimizedLaunch = false
}

application プラグイン (英語) が適用されている場合、その mainClassName プロパティを構成する必要があり、同じ目的で使用できます。

Groovy
application {
	mainClassName = 'com.example.ExampleApplication'
}
Kotlin
application {
	mainClassName = "com.example.ExampleApplication"
}

6.1. アプリケーションに引数を渡す

すべての JavaExec タスクと同様に、Gradle 4.9 以降を使用する場合は、--args='<arguments>' を使用してコマンドラインから引数を bootRun に渡すことができます。例:dev という名前のプロファイルをアクティブにしてアプリケーションを実行するには、次のコマンドを使用できます。

$ ./gradlew bootRun --args='--spring.profiles.active=dev'

詳細については、JavaExec.setArgsString の javadoc を参照して (英語) ください。

6.2. リソースをリロードする

プロジェクトに devtools が追加されている場合、アプリケーションの変更を自動的に監視します。または、bootRun を構成して、アプリケーションの静的リソースがソースの場所からロードされるようにすることができます。

Groovy
bootRun {
	sourceResources sourceSets.main
}
Kotlin
tasks.getByName<BootRun>("bootRun") {
	sourceResources(sourceSets["main"])
}

これにより、開発中に役立つ可能性があるライブアプリケーションに再読み込み可能になります。

7. アクチュエーターとの統合

7.1. ビルド情報の生成

Spring Boot Actuator の info エンドポイントは、META-INF/build-info.properties ファイルの存在下でビルドに関する情報を自動的に公開します。このファイルを生成するために、BuildInfo(Javadoc) タスクが提供されています。タスクを使用する最も簡単な方法は、プラグインの DSL を使用することです。

Groovy
springBoot {
	buildInfo()
}
Kotlin
springBoot {
	buildInfo()
}

これにより、bootBuildInfo という名前の BuildInfo(Javadoc) タスクが構成され、存在する場合は、Java プラグインの classes タスクがそれに依存するようになります。タスクの宛先ディレクトリは、メインソースセットのリソースの出力ディレクトリにある META-INF(通常は build/resources/main)です。

デフォルトでは、生成されたビルド情報はプロジェクトから取得されます。

プロパティ デフォルト値

build.artifact

bootJar または bootWar タスクのベース名、またはそのようなタスクが存在しない場合は unspecified

build.group

プロジェクトのグループ

build.name

プロジェクトの名前

build.version

プロジェクトのバージョン

build.time

プロジェクトが構築されている時間

プロパティは、DSL を使用してカスタマイズできます。

Groovy
springBoot {
	buildInfo {
		properties {
			artifact = 'example-app'
			version = '1.2.3'
			group = 'com.example'
			name = 'Example application'
		}
	}
}
Kotlin
springBoot {
	buildInfo {
		properties {
			artifact = "example-app"
			version = "1.2.3"
			group = "com.example"
			name = "Example application"
		}
	}
}

build.time のデフォルト値は、プロジェクトがビルドされる瞬間です。これの副作用は、タスクが最新にならないことです。その結果、プロジェクトのテストなど、より多くのタスクを実行する必要があるため、ビルドに時間がかかります。もう 1 つの副作用は、タスクの出力が常に変更されるため、ビルドが実際に再現できないことです。build.time プロパティの精度よりもビルドパフォーマンスまたは再現性を高く評価する場合は、timenull または固定値に設定します。

追加のプロパティをビルド情報に追加することもできます。

Groovy
springBoot {
	buildInfo {
		properties {
			additional = [
				'a': 'alpha',
				'b': 'bravo'
			]
		}
	}
}
Kotlin
springBoot {
	buildInfo {
		properties {
			additional = mapOf(
				"a" to "alpha",
				"b" to "bravo"
			)
		}
	}
}

8. 他のプラグインへの反応

別のプラグインが適用されると、Spring Boot プラグインはプロジェクトの構成にさまざまな変更を加えることで反応します。このセクションでは、これらの変更について説明します。

8.1. Java プラグインへの反応

Gradle の java プラグイン (英語) がプロジェクトに適用されると、Spring Boot プラグインは次のようになります。

  1. プロジェクトの実行可能ファイル fat jar を作成する bootJar という名前の BootJar(Javadoc) タスクを作成します。jar には、メインソースセットのランタイムクラスパス上のすべてが含まれます。クラスは BOOT-INF/classes にパッケージ化され、jar は BOOT-INF/lib にパッケージ化されます

  2. bootJar タスクに依存するように assemble タスクを構成します。

  3. jar タスクを無効にします。

  4. アプリケーションの実行に使用できる bootRun という名前の BootRun(Javadoc) タスクを作成します。

  5. bootJar タスクによって生成された成果物を含む bootArchives という名前の構成を作成します。

  6. UTF-8 を使用するようにエンコードが構成されていない JavaCompile タスクを構成します。

  7. -parameters コンパイラー引数を使用するように JavaCompile タスクを構成します。

8.2. Kotlin プラグインへの反応

Kotlin の Gradle プラグイン (英語) がプロジェクトに適用されると、Spring Boot プラグインは次のことを行います。

  1. Spring Boot の依存関係管理で使用される Kotlin バージョンをプラグインのバージョンに合わせます。これは、Kotlin プラグインのバージョンに一致する値で kotlin.version プロパティを設定することにより実現されます。

  2. -java-parameters コンパイラー引数を使用するように KotlinCompile タスクを構成します。

8.3. war プラグインへの反応

Gradle の war プラグイン (英語) がプロジェクトに適用されると、Spring Boot プラグインは次のようになります。

  1. プロジェクトの実行可能なファット war を作成する bootWar という名前の BootWar(Javadoc) タスクを作成します。標準パッケージに加えて、providedRuntime 構成のすべてが WEB-INF/lib-provided にパッケージされます。

  2. bootWar タスクに依存するように assemble タスクを構成します。

  3. war タスクを無効にします。

  4. bootArchives 構成を構成して、bootWar タスクによって生成された成果物を含めます。

8.4. 依存関係管理プラグインへの反応

io.spring.dependency-management プラグイン (GitHub) がプロジェクトに適用されると、Spring Boot プラグインは spring-boot-dependenciesbom を自動的にインポートします。

8.5. アプリケーションプラグインへの反応

Gradle の application プラグイン (英語) がプロジェクトに適用されると、Spring Boot プラグインは次のようになります。

  1. java -jar を使用して bootArchives 構成でアーティファクトを起動するスクリプトを作成する bootStartScripts という名前の CreateStartScripts タスクを作成します。タスクは、defaultJvmOpts プロパティの規則として applicationDefaultJvmArgs プロパティを使用するように構成されています。

  2. boot という名前の新しいディストリビューションを作成し、lib ディレクトリの bootArchives 構成のアーティファクトと bin ディレクトリの開始スクリプトを含むように構成します。

  3. main プロパティの規則として mainClassName プロパティを使用するように bootRun タスクを構成します。

  4. jvmArgs プロパティの規則として applicationDefaultJvmArgs プロパティを使用するように bootRun タスクを構成します。

  5. マニフェストの Start-Class エントリの規則として mainClassName プロパティを使用するように bootJar タスクを構成します。

  6. マニフェストの Start-Class エントリの規則として mainClassName プロパティを使用するように bootWar タスクを構成します。

8.6. Maven プラグインへの反応

Gradle の maven プラグイン (英語) がプロジェクトに適用されると、Spring Boot プラグインは uploadBootArchivesUpload タスクを構成して、生成する pom で依存関係が宣言されないようにします。

Unofficial Translation by spring.pleiades.io. See the original content.