1. 導入
Spring Boot Gradle プラグインは、Gradle (英語) で Spring Boot サポートを提供します。実行可能な jar または war アーカイブをパッケージ化し、Spring Boot アプリケーションを実行し、spring-boot-dependencies
によって提供される依存関係管理を使用することができます。Spring Boot の Gradle プラグインには、Gradle 7.x (7.5 以降) または 8.x が必要であり、Gradle の構成キャッシュ (英語) と共に使用できます。
このユーザーガイドに加えて、API ドキュメントも利用できます。
2. 入門
プラグインを開始するには、プロジェクトに適用する必要があります。
プラグインは Gradle のプラグインポータルに公開 (英語) され、plugins
ブロックを使用して適用できます。
plugins {
id 'org.springframework.boot' version '3.2.2'
}
plugins {
id("org.springframework.boot") version "3.2.2"
}
プラグインを単独で適用すると、プロジェクトにいくつかの変更が加えられます。代わりに、プラグインは他の特定のプラグインが適用されたときにそれを検出し、それに応じて反応します。例: java
プラグインが適用されると、実行可能な jar を構築するためのタスクが自動的に構成されます。典型的な Spring Boot プロジェクトでは、groovy
(英語) 、java
(英語) 、org.jetbrains.kotlin.jvm
(英語) プラグインを最低限適用し、依存関係管理のために io.spring.dependency-management
[GitHub] (英語) プラグインまたは Gradle のネイティブ bom サポートも使用します。例:
plugins {
id 'java'
id 'org.springframework.boot' version '3.2.2'
}
apply plugin: 'io.spring.dependency-management'
plugins {
java
id("org.springframework.boot") version "3.2.2"
}
apply(plugin = "io.spring.dependency-management")
他のプラグインが適用された場合の Spring Boot プラグインの動作の詳細については、他のプラグインへの反応に関するセクションを参照してください。
3. 依存関係の管理
Spring Boot アプリケーションの依存関係を管理するには、io.spring.dependency-management
[GitHub] (英語) プラグインを適用するか、Gradle のネイティブ bom サポートを使用します。前者の主な利点は、管理対象バージョンのプロパティベースのカスタマイズを提供することですが、後者を使用すると、ビルドが高速になる可能性があります。
3.1. 依存関係管理プラグインによる依存関係の管理
io.spring.dependency-management
[GitHub] (英語) プラグインを適用すると、Spring Boot のプラグインは、使用しているバージョンの Spring Boot から spring-boot-dependencies
bom を自動的にインポートします。これにより、Maven ユーザーが享受するのと同様の依存関係管理エクスペリエンスが提供されます。例: bom で管理されている依存関係を宣言するときに、バージョン番号を省略できます。この機能を利用するには、通常の方法で依存関係を宣言しますが、バージョン番号は省略します。
dependencies {
implementation('org.springframework.boot:spring-boot-starter-web')
implementation('org.springframework.boot:spring-boot-starter-data-jpa')
}
dependencies {
implementation("org.springframework.boot:spring-boot-starter-web")
implementation("org.springframework.boot:spring-boot-starter-data-jpa")
}
3.1.1. 管理バージョンのカスタマイズ
依存関係管理プラグインの適用時に自動的にインポートされる spring-boot-dependencies
bom は、プロパティを使用して、管理する依存関係のバージョンを制御します。これらのプロパティの完全なリストについては、Spring Boot リファレンスの Dependency versions Appendix
を参照してください。
管理対象バージョンをカスタマイズするには、対応するプロパティを設定します。例: slf4j.version
プロパティによって制御される SLF4J のバージョンをカスタマイズするには:
ext['slf4j.version'] = '1.7.20'
extra["slf4j.version"] = "1.7.20"
各 Spring Boot リリースは、サードパーティの特定の依存関係セットに対して設計およびテストされています。バージョンを上書きすると互換性の問題が発生する可能性があるため、注意して行う必要があります。 |
3.1.2. Spring Boot の依存関係管理のみを使用
Spring Boot の依存関係管理は、Spring Boot のプラグインをそのプロジェクトに適用せずにプロジェクトで使用できます。SpringBootPlugin
クラスは、グループ ID、アーティファクト ID、バージョンを知らなくても BOM をインポートするために使用できる BOM_COORDINATES
定数を提供します。
まず、Spring Boot プラグインに依存するようにプロジェクトを構成しますが、適用しません。
plugins {
id 'org.springframework.boot' version '3.2.2' apply false
}
plugins {
id("org.springframework.boot") version "3.2.2" apply false
}
Spring Boot プラグインの依存関係管理プラグインへの依存関係は、依存関係を宣言することなく依存関係管理プラグインを使用できることを意味します。これは、Spring Boot が使用するのと同じバージョンの依存関係管理プラグインを自動的に使用することも意味します。
依存関係管理プラグインを適用し、Spring Boot の bom をインポートするように構成します。
apply plugin: 'io.spring.dependency-management'
dependencyManagement {
imports {
mavenBom org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES
}
}
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 "3.2.2" apply false
id("io.spring.dependency-management") version "1.1.4"
}
dependencyManagement {
imports {
mavenBom(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
}
}
3.1.3. さらに学ぶ
依存関係管理プラグインの機能の詳細については、そのドキュメント (英語) を参照してください。
3.2. Gradle の Bom サポートによる依存関係の管理
Gradle を使用すると、BOM を使用して、プロジェクトを platform
または enforcedPlatform
依存関係として宣言することにより、プロジェクトのバージョンを管理できます。platform
依存関係は、BOM 内のバージョンを推奨として扱い、依存関係グラフ内の他のバージョンと制約により、BOM で宣言されたもの以外のバージョンの依存関係が使用される場合があります。enforcedPlatform
依存関係は、BOM のバージョンを要件として扱い、依存関係グラフで見つかった他のバージョンをオーバーライドします。
次の例に示すように、SpringBootPlugin
クラスは BOM_COORDINATES
定数を提供し、これを使用して、グループ ID、アーティファクト ID、バージョンを知らなくても、Spring Boot の bom への依存関係を宣言できます。
dependencies {
implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
}
dependencies {
implementation(platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES))
}
プラットフォームまたは強制されたプラットフォームは、それが宣言された構成のバージョン、または宣言された構成から拡張された構成のバージョンのみを制約します。その結果、複数の構成で同じ依存関係を宣言する必要がある場合があります。
3.2.1. 管理バージョンのカスタマイズ
Gradle の bom サポートを使用する場合、spring-boot-dependencies
のプロパティを使用して、それが管理する依存関係のバージョンを制御することはできません。代わりに、Gradle が提供するメカニズムの 1 つを使用する必要があります。そのようなメカニズムの 1 つが解決戦略です。SLF4J のモジュールはすべて org.slf4j
グループにあるため、次の例に示すように、特定のバージョンを使用するようにそのグループのすべての依存関係を構成することにより、バージョンを制御できます。
configurations.all {
resolutionStrategy.eachDependency { DependencyResolveDetails details ->
if (details.requested.group == 'org.slf4j') {
details.useVersion '1.7.20'
}
}
}
configurations.all {
resolutionStrategy.eachDependency {
if (requested.group == "org.slf4j") {
useVersion("1.7.20")
}
}
}
各 Spring Boot リリースは、サードパーティの特定の依存関係セットに対して設計およびテストされています。バージョンを上書きすると互換性の問題が発生する可能性があるため、注意して行う必要があります。 |
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
構成に埋め込みサーブレットコンテナーの依存関係を追加する必要があります。例:
dependencies {
implementation('org.springframework.boot:spring-boot-starter-web')
providedRuntime('org.springframework.boot:spring-boot-starter-tomcat')
}
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
タスクは、アーカイブ分類子の規則として plain
を使用するように構成されています。これにより、bootJar
と jar
、bootWar
と war
の出力場所が異なり、実行可能アーカイブとプレーンアーカイブの両方を同時に構築できます。
プレーンアーカイブではなく実行可能アーカイブで分類子を使用する場合は、jar
および bootJar
タスクの次の例に示すように分類子を構成します。
tasks.named("bootJar") {
archiveClassifier = 'boot'
}
tasks.named("jar") {
archiveClassifier = ''
}
tasks.named<BootJar>("bootJar") {
archiveClassifier.set("boot")
}
tasks.named<Jar>("jar") {
archiveClassifier.set("")
}
または、プレーンアーカイブをまったく作成しない場合は、次の jar
タスクの例に示すように、そのタスクを無効にします。
tasks.named("jar") {
enabled = false
}
tasks.named<Jar>("jar") {
enabled = false
}
ネイティブイメージを作成するときは、jar タスクを無効にしないでください。詳細については、#33238 [GitHub] (英語) を参照してください。 |
4.4. 実行可能アーカイブパッケージの構成
BootJar
(Javadoc) および BootWar
(Javadoc) タスクは、それぞれ Gradle の Jar
および War
タスクのサブクラスです。その結果、jar または war をパッケージ化するときに使用できるすべての標準構成オプションは、実行可能な jar または war をパッケージ化するときにも使用できます。実行可能な jar および war に固有の構成オプションも多数提供されています。
4.4.1. メインクラスの構成
デフォルトでは、実行可能アーカイブのメインクラスは、メインソースセットの出力で public static void main(String[])
メソッドを持つクラスを探すことによって自動的に構成されます。
メインクラスは、タスクの mainClass
プロパティを使用して明示的に構成することもできます。
tasks.named("bootJar") {
mainClass = 'com.example.ExampleApplication'
}
tasks.named<BootJar>("bootJar") {
mainClass.set("com.example.ExampleApplication")
}
または、Spring Boot DSL の mainClass
プロパティを使用して、プロジェクト全体でメインクラス名を設定できます。
springBoot {
mainClass = 'com.example.ExampleApplication'
}
springBoot {
mainClass.set("com.example.ExampleApplication")
}
application
プラグイン (英語) が適用されている場合は、その mainClass
プロパティを構成する必要があり、同じ目的で使用できます。
application {
mainClass = 'com.example.ExampleApplication'
}
application {
mainClass.set("com.example.ExampleApplication")
}
最後に、タスクのマニフェストで Start-Class
属性を構成できます。
tasks.named("bootJar") {
manifest {
attributes 'Start-Class': 'com.example.ExampleApplication'
}
}
tasks.named<BootJar>("bootJar") {
manifest {
attributes("Start-Class" to "com.example.ExampleApplication")
}
}
メインクラスが Kotlin で記述されている場合は、生成された Java クラスの名前を使用する必要があります。デフォルトでは、これは Kt サフィックスが追加された Kotlin クラスの名前です。例: ExampleApplication は ExampleApplicationKt になります。@JvmName を使用して別の名前が定義されている場合は、その名前を使用する必要があります。 |
4.4.2. 開発専用の依存関係を含める
デフォルトでは、developmentOnly
構成で宣言されたすべての依存関係は、実行可能な jar または war から除外されます。
developmentOnly
構成で宣言された依存関係をアーカイブに含める場合は、次の bootWar
タスクの例に示すように、そのタスクのクラスパスを構成に含めるように構成します。
tasks.named("bootWar") {
classpath configurations.developmentOnly
}
tasks.named<BootWar>("bootWar") {
classpath(configurations["developmentOnly"])
}
4.4.3. 解凍が必要なライブラリの構成
ほとんどのライブラリは、実行可能アーカイブにネストされている場合に直接使用できますが、特定のライブラリには問題がある場合があります。例: JRuby には、jruby-complete.jar
が常にファイルシステムで直接利用可能であることを前提とする独自のネストされた jar サポートが含まれています。
問題のあるライブラリを処理するために、実行可能アーカイブの実行時に、特定のネストされた jar を一時ディレクトリに解凍するように実行可能アーカイブを構成できます。ライブラリは、ソース jar ファイルの絶対パスと一致する Ant スタイルのパターンを使用して解凍する必要があると識別できます。
tasks.named("bootJar") {
requiresUnpack '**/jruby-complete-*.jar'
}
tasks.named<BootJar>("bootJar") {
requiresUnpack("**/jruby-complete-*.jar")
}
さらに制御するために、クロージャを使用することもできます。クロージャには FileTreeElement
が渡され、開梱が必要かどうかを示す boolean
を返す必要があります。
4.4.4. アーカイブを完全に実行可能にする
Spring Boot は、完全に実行可能なアーカイブのサポートを提供します。アーカイブは、アプリケーションの起動方法を知っているシェルスクリプトを先頭に追加することにより、完全に実行可能になります。Unix ライクなプラットフォームでは、この起動スクリプトにより、アーカイブを他の実行可能ファイルのように直接実行したり、サービスとしてインストールしたりできます。
現在、一部のツールはこの形式を受け入れないため、この手法を常に使用できるとは限りません。例: jar -xf は、完全に実行可能にされた jar または war の抽出にサイレントに失敗する場合があります。このオプションは、java -jar で実行したり、サーブレットコンテナーにデプロイしたりするのではなく、直接実行する場合にのみ有効にすることをお勧めします。 |
この機能を使用するには、起動スクリプトの組み込みを有効にする必要があります。
tasks.named("bootJar") {
launchScript()
}
tasks.named<BootJar>("bootJar") {
launchScript()
}
これにより、Spring Boot のデフォルトの起動スクリプトがアーカイブに追加されます。デフォルトの起動スクリプトには、適切なデフォルト値を持ついくつかのプロパティが含まれています。値は、properties
プロパティを使用してカスタマイズできます。
tasks.named("bootJar") {
launchScript {
properties 'logFilename': 'example-app.log'
}
}
tasks.named<BootJar>("bootJar") {
launchScript {
properties(mapOf("logFilename" to "example-app.log"))
}
}
デフォルトの起動スクリプトがニーズを満たさない場合、script
プロパティを使用してカスタム起動スクリプトを提供できます。
tasks.named("bootJar") {
launchScript {
script = file('src/custom.script')
}
}
tasks.named<BootJar>("bootJar") {
launchScript {
script = file("src/custom.script")
}
}
4.4.5. PropertiesLauncher の使用
PropertiesLauncher
を使用して実行可能な jar または war を起動するには、タスクのマニフェストを構成して Main-Class
属性を設定します。
tasks.named("bootWar") {
manifest {
attributes 'Main-Class': 'org.springframework.boot.loader.launch.PropertiesLauncher'
}
}
tasks.named<BootWar>("bootWar") {
manifest {
attributes("Main-Class" to "org.springframework.boot.loader.launch.PropertiesLauncher")
}
}
4.4.6. 階層化された Jar または War のパッケージ化
デフォルトでは、bootJar
タスクは、アプリケーションのクラスと依存関係をそれぞれ BOOT-INF/classes
と BOOT-INF/lib
に含むアーカイブを構築します。同様に、bootWar
は、WEB-INF/classes
のアプリケーションのクラスと、WEB-INF/lib
および WEB-INF/lib-provided
の依存関係を含むアーカイブを構築します。jar のコンテンツから docker イメージを作成する必要がある場合は、これらのディレクトリをさらに分離して、個別のレイヤーに書き込むことができると便利です。
階層化された jar は、通常の Boot パッケージ jar と同じレイアウトを使用しますが、各レイヤーを説明する追加のメタデータファイルが含まれています。
デフォルトでは、次のレイヤーが定義されています。
バージョンに
SNAPSHOT
が含まれていないプロジェクト以外の依存関係のdependencies
。jar ローダークラスの
spring-boot-loader
。バージョンに
SNAPSHOT
が含まれているプロジェクト以外の依存関係のsnapshot-dependencies
。プロジェクトの依存関係、アプリケーションクラス、リソース用の
application
。
レイヤーの順序は、アプリケーションの一部が変更されたときに前のレイヤーがキャッシュされる可能性を決定するため、重要です。デフォルトの順序は dependencies
、spring-boot-loader
、snapshot-dependencies
、application
です。変更の可能性が最も低いコンテンツを最初に追加し、次に変更の可能性が高いレイヤーを追加する必要があります。
この機能を無効にするには、次の方法で無効にします。
tasks.named("bootJar") {
layered {
enabled = false
}
}
tasks.named<BootJar>("bootJar") {
layered {
enabled.set(false)
}
}
階層化された jar または war が作成されると、spring-boot-jarmode-layertools
jar が依存関係としてアーカイブに追加されます。クラスパス上のこの jar を使用すると、特別なモードでアプリケーションを起動できます。これにより、ブートストラップコードで、アプリケーションとはまったく異なるもの(たとえば、レイヤーを抽出するもの)を実行できます。この依存関係を除外する場合は、次の方法で行うことができます。
tasks.named("bootJar") {
layered {
includeLayerTools = false
}
}
tasks.named<BootJar>("bootJar") {
layered {
includeLayerTools.set(false)
}
}
カスタムレイヤー構成
アプリケーションによっては、レイヤーの作成方法を調整し、新しいレイヤーを追加したい場合があります。
これは、jar または war をレイヤーに分離する方法と、それらのレイヤーの順序を説明する構成を使用して実行できます。次の例は、上記のデフォルトの順序を明示的に定義する方法を示しています。
tasks.named("bootJar") {
layered {
application {
intoLayer("spring-boot-loader") {
include "org/springframework/boot/loader/**"
}
intoLayer("application")
}
dependencies {
intoLayer("application") {
includeProjectDependencies()
}
intoLayer("snapshot-dependencies") {
include "*:*:*SNAPSHOT"
}
intoLayer("dependencies")
}
layerOrder = ["dependencies", "spring-boot-loader", "snapshot-dependencies", "application"]
}
}
tasks.named<BootJar>("bootJar") {
layered {
application {
intoLayer("spring-boot-loader") {
include("org/springframework/boot/loader/**")
}
intoLayer("application")
}
dependencies {
intoLayer("application") {
includeProjectDependencies()
}
intoLayer("snapshot-dependencies") {
include("*:*:*SNAPSHOT")
}
intoLayer("dependencies")
}
layerOrder.set(listOf("dependencies", "spring-boot-loader", "snapshot-dependencies", "application"))
}
}
layered
DSL は、3 つの部分を使用して定義されます。
application
クロージャは、アプリケーションクラスとリソースを階層化する方法を定義します。dependencies
クロージャーは、依存関係を階層化する方法を定義します。layerOrder
メソッドは、レイヤーが書き込まれる順序を定義します。
ネストされた intoLayer
クロージャーは、application
および dependencies
セクション内で使用され、レイヤーのコンテンツを要求します。これらのクロージャーは、定義された順序で上から下に評価されます。以前の intoLayer
クロージャーによって要求されていないコンテンツは、引き続き後続のコンテンツで検討できます。
intoLayer
クロージャーは、ネストされた include
および exclude
呼び出しを使用してコンテンツを要求します。application
クロージャーは、包含 / 除外パラメーターに Ant スタイルのパスマッチングを使用します。dependencies
セクションは group:artifact[:version]
パターンを使用します。また、プロジェクトの依存関係を含めたり除外したりするために使用できる includeProjectDependencies()
および excludeProjectDependencies()
メソッドも提供します。
include
呼び出しが行われない場合、すべてのコンテンツ(以前のクロージャーによって要求されていない)が考慮されます。
exclude
呼び出しが行われない場合、除外は適用されません。
上記の例の dependencies
クロージャを見ると、最初の intoLayer
が application
レイヤーのすべてのプロジェクト依存関係を要求していることがわかります。次の intoLayer
は、snapshot-dependencies
レイヤーのすべての SNAPSHOT 依存関係を要求します。3 番目の最後の intoLayer
は、dependencies
レイヤーに残っているもの(この場合、プロジェクトの依存関係または SNAPSHOT ではない依存関係)を要求します。
application
クロージャーにも同様のルールがあります。最初に、spring-boot-loader
レイヤーの org/springframework/boot/loader/**
コンテンツを要求します。次に、application
レイヤーの残りのクラスとリソースを要求します。
intoLayer クロージャーが追加される順序は、多くの場合、レイヤーが書き込まれる順序とは異なります。このため、layerOrder メソッドは常に呼び出され、intoLayer 呼び出しによって参照されるすべてのレイヤーをカバーする必要があります。 |
5. OCI イメージのパッケージ化
プラグインは、Cloud Native Buildpacks (英語) (CNB)を使用して jar または war ファイルから OCI イメージ [GitHub] (英語) を作成できます。bootBuildImage
タスクを使用してイメージを構築できます。
セキュリティ上の理由から、イメージは root 以外のユーザーとしてビルドおよび実行されます。詳細については、CNB 仕様 (英語) を参照してください。 |
タスクは、java
または war
プラグインが適用されると自動的に作成され、BootBuildImage
(Javadoc) のインスタンスです。
5.1. Docker デーモン
bootBuildImage
タスクには、Docker デーモンへのアクセスが必要です。このタスクは、ローカルの Docker CLI 構成ファイル (英語) をインスペクションして現在のコンテキスト (英語) を特定し、そのコンテキスト接続情報を使用して Docker デーモンと通信します。現在のコンテキストを特定できない場合、またはコンテキストに接続情報がない場合、タスクはデフォルトのローカル接続を使用します。これは、サポートされているすべてのプラットフォーム上の Docker エンジン (英語) で構成なしで動作します。
環境変数を設定して、代替のローカル接続またはリモート接続を使用するように bootBuildImage
タスクを構成できます。次の表に、環境変数とその値を示します。
環境変数 | 説明 |
---|---|
DOCKER_CONFIG | 現在のコンテキストを決定するために使用される Docker CLI 構成ファイル (英語) の場所 (デフォルトは |
DOCKER_CONTEXT | Docker CLI 構成ファイルからホスト情報を取得するために使用するコンテキスト (英語) の名前 ( |
DOCKER_HOST | Docker デーモンのホストとポートを含む URL- 例: |
DOCKER_TLS_VERIFY |
|
DOCKER_CERT_PATH | HTTPS の証明書とキーファイルへのパス ( |
Docker デーモン接続情報は、プラグイン構成の docker
プロパティを使用して提供することもできます。次の表は、使用可能なプロパティをまとめたものです。
プロパティ | 説明 |
---|---|
| Docker CLI 構成ファイル (英語) からホスト情報を取得するために使用するコンテキスト (英語) の名前 |
| Docker デーモンのホストとポートを含む URL- 例: |
|
|
| HTTPS の証明書とキーファイルへのパス ( |
|
|
詳細については、例も参照してください。
5.2. Docker レジストリ
builder
または runImage
プロパティで指定された Docker イメージが、認証を必要とするプライベート Docker イメージレジストリに格納されている場合、認証資格情報は docker.builderRegistry
プロパティを使用して提供できます。
生成された Docker イメージを Docker イメージレジストリに公開する場合は、docker.publishRegistry
プロパティを使用して認証資格情報を提供できます。
プロパティは、ユーザー認証または ID トークン認証用に提供されています。サポートされている認証方法の詳細については、イメージの保存に使用されている Docker レジストリのドキュメントを参照してください。
次の表は、docker.builderRegistry
および docker.publishRegistry
で使用可能なプロパティをまとめたものです。
プロパティ | 説明 |
---|---|
| Docker イメージレジストリユーザーのユーザー名。ユーザー認証に必要です。 |
| Docker イメージレジストリユーザーのパスワード。ユーザー認証に必要です。 |
| Docker イメージレジストリのアドレス。ユーザー認証のオプション。 |
| Docker イメージレジストリユーザーのメールアドレス。ユーザー認証のオプション。 |
| Docker イメージレジストリユーザーの ID トークン。トークン認証に必要です。 |
詳細については、例も参照してください。
5.3. イメージのカスタマイズ
プラグインはビルダー (英語) を呼び出して、イメージの生成を調整します。ビルダーには、生成されたイメージに影響を与えるためにアプリケーションをインスペクションできる複数の buildpacks が含 (英語) まれています。デフォルトでは、プラグインはビルダーイメージを選択します。生成されたイメージの名前は、プロジェクトのプロパティから推測されます。
タスクプロパティを使用して、ビルダーがプロジェクトでどのように動作するかを構成できます。次の表は、使用可能なプロパティとそのデフォルト値をまとめたものです。
プロパティ | コマンドラインオプション | 説明 | デフォルト値 |
---|---|---|---|
|
| 使用する Builder イメージの名前。 |
|
|
| 使用する実行イメージの名前。 | デフォルト値はなく、Builder メタデータで指定された実行イメージを使用する必要があることを示します。 |
|
| 生成されたイメージのイメージ名: (Javadoc) 。 |
|
|
| ポリシー (Javadoc) は、ビルダーをプルしてレジストリからイメージを実行するタイミングを決定するために使用されます。許容値は |
|
| ビルダーに渡す必要のある環境変数。 | GraalVM ネイティブイメージプラグイン (英語) が適用されている場合は空または | |
| ビルダーがイメージをビルドするときに使用する必要がある Buildpacks。指定された buildpacks のみが使用され、ビルダーに含まれているデフォルトの buildpacks がオーバーライドされます。Buildpack 参照は、次のいずれかの形式である必要があります。
| なし。ビルダーがそれに含まれる buildpacks を使用する必要があることを示します。 | |
| イメージをビルドするときにビルダーコンテナーにマウントする必要があるボリュームバインドマウント (英語) 。バインディングは、ビルダーコンテナーの作成時に、解析されず、検証されずに Docker に渡されます。バインディングは、次のいずれかの形式である必要があります。
| ||
|
| ビルダーコンテナーが使用するように構成されたネットワークドライバー (英語) 。指定された値は、ビルダーコンテナーの作成時に、検証されずに Docker に渡されます。 | |
|
| 構築する前にキャッシュを消去するかどうか。 |
|
| ビルダー操作の詳細ログを有効にします。 |
| |
|
| 生成されたイメージを Docker レジストリに公開するかどうか。 |
|
| 生成されたイメージに適用する 1 つ以上の追加タグのリスト。 | ||
| ビルダーと buildpacks がイメージの構築中にファイルを保存するために使用する一時ワークスペース。値には、名前付きボリュームまたはバインドマウントの場所を指定できます。 | イメージ名から派生した名前を持つ、Docker デーモン内の名前付きボリューム。 | |
| buildpacks によって作成され、イメージ構築プロセスによって使用されるレイヤーを含むキャッシュ。値には、名前付きボリュームまたはバインドマウントの場所を指定できます。 | イメージ名から派生した名前を持つ、Docker デーモン内の名前付きボリューム。 | |
| buildpacks によって作成され、イメージ起動プロセスによって使用されるレイヤーを含むキャッシュ。値には、名前付きボリュームまたはバインドマウントの場所を指定できます。 | イメージ名から派生した名前を持つ、Docker デーモン内の名前付きボリューム。 | |
|
| 生成されたイメージのメタデータで | ビルドの再現性 (英語) を可能にする固定の日付。 |
|
| ビルダーイメージ内のアプリケーションコンテンツがアップロードされるディレクトリへのパス。アプリケーションのコンテンツも、生成されたイメージのこの場所に含まれます。 |
|
|
| 文字列値の配列として提供される、ビルダーコンテナーに適用されるセキュリティオプション (英語) |
|
The plugin detects the target Java compatibility of the project using the JavaPlugin’s targetCompatibility property.
When using the default Paketo builder and buildpacks, the plugin instructs the buildpacks to install the same Java version.
You can override this behaviour as shown in the builder configuration examples.
|
5.3.1. Tags format
The values provided to the tags
option should be full image references.
The accepted format is [domainHost:port/][path/]name[:tag][@digest]
.
If the domain is missing, it defaults to docker.io
.
If the path is missing, it defaults to library
.
If the tag is missing, it defaults to latest
.
Some examples:
-
my-image
leads to the image referencedocker.io/library/my-image:latest
my-repository/my-image
はdocker.io/my-repository/my-image:latest
につながりますexample.com/my-repository/my-image:1.0.0
はそのまま使用します
5.4. サンプル
5.4.1. カスタムイメージビルダーと実行イメージ
イメージの作成に使用されるビルダーまたはビルドされたイメージの起動に使用される実行イメージをカスタマイズする必要がある場合は、次の例に示すようにタスクを構成します。
tasks.named("bootBuildImage") {
builder = "mine/java-cnb-builder"
runImage = "mine/java-cnb-run"
}
tasks.named<BootBuildImage>("bootBuildImage") {
builder.set("mine/java-cnb-builder")
runImage.set("mine/java-cnb-run")
}
この構成では、名前 mine/java-cnb-builder
およびタグ latest
のビルダーイメージ、および mine/java-cnb-run
という名前の実行イメージとタグ latest
を使用します。
この例に示すように、ビルダーと実行イメージはコマンドラインでも指定できます。
$ gradle bootBuildImage --builder=mine/java-cnb-builder --runImage=mine/java-cnb-run
5.4.2. ビルダー構成
ビルダーが構成オプションを公開する場合、environment
プロパティを使用して設定できます。
以下は、ビルド時に Paketo Java buildpacks によって使用される JVM バージョンを構成する例 (英語) です。
tasks.named("bootBuildImage") {
environment["BP_JVM_VERSION"] = "17"
}
tasks.named<BootBuildImage>("bootBuildImage") {
environment.set(environment.get() + mapOf("BP_JVM_VERSION" to "17"))
}
ビルダーが実行されている Docker デーモンと buildpacks がアーティファクトをダウンロードするネットワークの場所の間にネットワークプロキシがある場合は、プロキシを使用するようにビルダーを構成する必要があります。Paketo ビルダーを使用する場合、これは、次の例に示すように、HTTPS_PROXY
および / または HTTP_PROXY
環境変数を設定することで実現できます。
tasks.named("bootBuildImage") {
environment["HTTP_PROXY"] = "http://proxy.example.com"
environment["HTTPS_PROXY"] = "https://proxy.example.com"
}
tasks.named<BootBuildImage>("bootBuildImage") {
environment.set(mapOf("HTTP_PROXY" to "http://proxy.example.com",
"HTTPS_PROXY" to "https://proxy.example.com"))
}
5.4.3. ランタイム JVM 構成
Paketo Java buildpacks は、JAVA_TOOL_OPTIONS
環境変数を設定することにより、JVM ランタイム環境を構成 (英語) します。ビルドパックが提供する JAVA_TOOL_OPTIONS
値を変更して、アプリケーションイメージがコンテナーで起動されたときの JVM ランタイムの動作をカスタマイズできます。
イメージに保存してすべてのデプロイに適用する必要がある環境変数の変更は、Paketo ドキュメント (英語) に従って設定でき、次の例に示されています。
tasks.named("bootBuildImage") {
environment["BPE_DELIM_JAVA_TOOL_OPTIONS"] = " "
environment["BPE_APPEND_JAVA_TOOL_OPTIONS"] = "-XX:+HeapDumpOnOutOfMemoryError"
}
tasks.named<BootBuildImage>("bootBuildImage") {
environment.set(mapOf(
"BPE_DELIM_JAVA_TOOL_OPTIONS" to " ",
"BPE_APPEND_JAVA_TOOL_OPTIONS" to "-XX:+HeapDumpOnOutOfMemoryError"
))
}
5.4.4. カスタムイメージ名
デフォルトでは、イメージ名は name
および docker.io/library/${project.name}:${project.version}
のようなプロジェクトの version
から推測されます。次の例に示すように、タスクのプロパティを設定することにより、名前を制御できます。
tasks.named("bootBuildImage") {
imageName = "example.com/library/${project.name}"
}
tasks.named<BootBuildImage>("bootBuildImage") {
imageName.set("example.com/library/${project.name}")
}
この構成では明示的なタグが提供されないため、latest
が使用されることに注意してください。${project.version}
、ビルドで使用可能なプロパティ、ハードコードされたバージョンのいずれかを使用して、タグを指定することもできます。
次の例に示すように、イメージ名はコマンドラインでも指定できます。
$ gradle bootBuildImage --imageName=example.com/library/my-app:v1
5.4.5. Buildpacks
デフォルトでは、ビルダーはビルダーイメージに含まれている buildpacks を使用し、事前定義された順序で適用します。buildpacks の代替セットを提供して、ビルダーに含まれていない buildpacks を適用したり、含まれている buildpacks の順序を変更したりできます。1 つ以上の buildpacks が提供されている場合、指定された buildpacks のみが適用されます。
次の例では、.tgz
ファイルにパッケージ化されたカスタム buildpack を使用し、その後にビルダーに含まれる buildpack を使用するようにビルダーに指示します。
tasks.named("bootBuildImage") {
buildpacks = ["file:///path/to/example-buildpack.tgz", "urn:cnb:builder:paketo-buildpacks/java"]
}
tasks.named<BootBuildImage>("bootBuildImage") {
buildpacks.set(listOf("file:///path/to/example-buildpack.tgz", "urn:cnb:builder:paketo-buildpacks/java"))
}
Buildpacks は、以下に示す任意の形式で指定できます。
CNB ビルダーにある buildpack(ビルダーに buildpack-id
に一致する buildpack が 1 つしかない場合は、バージョンを省略できます):
urn:cnb:builder:buildpack-id
urn:cnb:builder:[email protected] (英語)
buildpack-id
buildpack コンテンツを含むディレクトリへのパス(Windows ではサポートされていません):
file:///path/to/buildpack/
/path/to/buildpack/
buildpack コンテンツを含む gzip 圧縮された tar ファイルへのパス:
file:///path/to/buildpack.tgz
/path/to/buildpack.tgz
パッケージ化された buildpack (英語) を含む OCI イメージ:
docker://example/buildpack
docker:///example/buildpack:latest
docker:///example/buildpack@sha256:45b23dee08…
example/buildpack
example/buildpack:latest
example/buildpack@sha256:45b23dee08…
5.4.6. イメージ公開
生成されたイメージは、publish
オプションを有効にすることで Docker レジストリに公開できます。
Docker レジストリで認証が必要な場合は、docker.publishRegistry
プロパティを使用して資格情報を構成できます。Docker レジストリが認証を必要としない場合は、docker.publishRegistry
構成を省略できます。
イメージが公開されるレジストリは、イメージ名のレジストリ部分(これらの例では docker.example.com )によって決定されます。docker.publishRegistry 資格情報が構成されていて、url プロパティが含まれている場合、この値はレジストリに渡されますが、発行レジストリの場所を判別するためには使用されません。 |
tasks.named("bootBuildImage") {
imageName.set("docker.example.com/library/${project.name}")
publish = true
docker {
publishRegistry {
username = "user"
password = "secret"
}
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
imageName.set("docker.example.com/library/${project.name}")
publish.set(true)
docker {
publishRegistry {
username.set("user")
password.set("secret")
}
}
}
この例に示すように、publish オプションはコマンドラインでも指定できます。
$ gradle bootBuildImage --imageName=docker.example.com/library/my-app:v1 --publishImage
5.4.7. ビルダーのキャッシュとワークスペースの構成
CNB ビルダーは、イメージのビルドおよび起動時に使用されるレイヤーをキャッシュします。デフォルトでは、これらのキャッシュは、ターゲットイメージのフルネームから派生した名前で Docker デーモンに名前付きボリュームとして保存されます。プロジェクトのバージョンがイメージ名のタグとして使用されている場合など、イメージ名が頻繁に変更される場合、キャッシュが頻繁に無効化される可能性があります。
次の例に示すように、キャッシュボリュームは、代替名を使用してキャッシュライフサイクルをより細かく制御できるように構成できます。
tasks.named("bootBuildImage") {
buildCache {
volume {
name = "cache-${rootProject.name}.build"
}
}
launchCache {
volume {
name = "cache-${rootProject.name}.launch"
}
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
buildCache {
volume {
name.set("cache-${rootProject.name}.build")
}
}
launchCache {
volume {
name.set("cache-${rootProject.name}.launch")
}
}
}
ビルダーと buildpacks には、イメージのビルド中に一時ファイルを保存する場所が必要です。デフォルトでは、この一時ビルドワークスペースは名前付きボリュームに保存されます。
次の例に示すように、名前付きボリュームの代わりにバインドマウントを使用するようにキャッシュとビルドワークスペースを構成できます。
tasks.named("bootBuildImage") {
buildWorkspace {
bind {
source = "/tmp/cache-${rootProject.name}.work"
}
}
buildCache {
bind {
source = "/tmp/cache-${rootProject.name}.build"
}
}
launchCache {
bind {
source = "/tmp/cache-${rootProject.name}.launch"
}
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
buildWorkspace {
bind {
source.set("/tmp/cache-${rootProject.name}.work")
}
}
buildCache {
bind {
source.set("/tmp/cache-${rootProject.name}.build")
}
}
launchCache {
bind {
source.set("/tmp/cache-${rootProject.name}.launch")
}
}
}
5.4.8. Docker の設定
minikube の Docker 構成
プラグインは、デフォルトのローカル接続の代わりに minikube が提供する Docker デーモン (英語) と通信できます。
Linux および macOS では、minikube の起動後に、コマンド eval $(minikube docker-env)
を使用して環境変数を設定できます。
次の例に示すような接続の詳細を提供することにより、プラグインを minikube デーモンを使用するように構成することもできます。
tasks.named("bootBuildImage") {
docker {
host = "tcp://192.168.99.100:2376"
tlsVerify = true
certPath = "/home/user/.minikube/certs"
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
docker {
host.set("tcp://192.168.99.100:2376")
tlsVerify.set(true)
certPath.set("/home/user/.minikube/certs")
}
}
podman の Docker 構成
プラグインは podman コンテナーエンジン (英語) と通信できます。
次の例に示すような接続の詳細を提供することにより、podman ローカル接続を使用するようにプラグインを構成できます。
tasks.named("bootBuildImage") {
docker {
host = "unix:///run/user/1000/podman/podman.sock"
bindHostToBuilder = true
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
docker {
host.set("unix:///run/user/1000/podman/podman.sock")
bindHostToBuilder.set(true)
}
}
podman CLI がインストールされている場合、コマンド podman info --format='{{.Host.RemoteSocket.Path}}' を使用して、この例に示されている docker.host 構成プロパティの値を取得できます。 |
Colima 用の Docker 構成
プラグインは、コリマ [GitHub] (英語) によって提供される Docker デーモンと通信できます。DOCKER_HOST
環境変数は、コマンド export DOCKER_HOST=$(docker context inspect colima -f '{{.Endpoints.docker.Host}}').
を使用して設定できます。
次の例に示すような接続の詳細を指定することで、Colima デーモンを使用するようにプラグインを構成することもできます。
tasks.named("bootBuildImage") {
docker {
host = "unix://${System.properties['user.home']}/.colima/docker.sock"
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
docker {
host.set("unix://${System.getProperty("user.home")}/.colima/docker.sock")
}
}
認証用の Docker 構成
ビルダーまたは実行イメージがユーザー認証をサポートするプライベート Docker レジストリに保管されている場合、次の例に示すように、docker.builderRegistry
プロパティを使用して認証の詳細を提供できます。
tasks.named("bootBuildImage") {
docker {
builderRegistry {
username = "user"
password = "secret"
url = "https://docker.example.com/v1/"
email = "[email protected] (英語) "
}
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
docker {
builderRegistry {
username.set("user")
password.set("secret")
url.set("https://docker.example.com/v1/")
email.set("[email protected] (英語) ")
}
}
}
ビルダーまたは実行イメージがトークン認証をサポートするプライベート Docker レジストリに保管されている場合、次の例に示すように、docker.builderRegistry
を使用してトークン値を提供できます。
tasks.named("bootBuildImage") {
docker {
builderRegistry {
token = "9cbaf023786cd7..."
}
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
docker {
builderRegistry {
token.set("9cbaf023786cd7...")
}
}
}
6. アプリケーションの公開
6.1. Maven-publish プラグインを使用した公開
Spring Boot jar または war を公開するには、MavenPublication
で artifact
メソッドを使用して公開に追加します。公開するアーティファクトを生成するタスクを artifact
メソッドに渡します。例: デフォルトの bootJar
タスクによって生成されたアーティファクトを公開するには:
publishing {
publications {
bootJava(MavenPublication) {
artifact tasks.named("bootJar")
}
}
repositories {
maven {
url 'https://repo.example.com'
}
}
}
publishing {
publications {
create<MavenPublication>("bootJava") {
artifact(tasks.named("bootJar"))
}
}
repositories {
maven {
url = uri("https://repo.example.com")
}
}
}
6.2. アプリケーションプラグインを使用した配布
application
プラグイン (英語) が適用されると、boot
という名前のディストリビューションが作成されます。このディストリビューションには、bootJar
または bootWar
タスクによって生成されたアーカイブと、それを Unix 系プラットフォームおよび Windows 上で起動するためのスクリプトが含まれています。Zip ディストリビューションと tar ディストリビューションは、それぞれ bootDistZip
タスクと bootDistTar
タスクによって構築できます。application
プラグインを使用するには、その mainClassName
プロパティをアプリケーションのメインクラスの名前で構成する必要があります。
7. Gradle でアプリケーションを実行する
アーカイブを作成せずにアプリケーションを実行するには、bootRun
タスクを使用します。
$ ./gradlew bootRun
bootRun
タスクは、JavaExec
サブクラスである BootRun
(Javadoc) のインスタンスです。そのため、Gradle で Java プロセスを実行するための通常の構成オプション (英語) はすべて利用可能です。タスクは、メインソースセットのランタイムクラスパスを使用するように自動的に構成されます。
デフォルトでは、メインソースセットの出力で public static void main(String[])
メソッドを持つクラスを探すことによって、メインクラスが自動的に構成されます。
メインクラスは、タスクの main
プロパティを使用して明示的に構成することもできます。
tasks.named("bootRun") {
mainClass = 'com.example.ExampleApplication'
}
tasks.named<BootRun>("bootRun") {
mainClass.set("com.example.ExampleApplication")
}
または、Spring Boot DSL の mainClass
プロパティを使用して、プロジェクト全体でメインクラス名を設定できます。
springBoot {
mainClass = 'com.example.ExampleApplication'
}
springBoot {
mainClass.set("com.example.ExampleApplication")
}
デフォルトでは、bootRun
は JVM を構成して、開発中の起動を高速化するために最適化します。この動作は、次の例に示すように、optimizedLaunch
プロパティを使用して無効にすることができます。
tasks.named("bootRun") {
optimizedLaunch = false
}
tasks.named<BootRun>("bootRun") {
optimizedLaunch.set(false)
}
application
プラグイン (英語) が適用されている場合は、その mainClass
のプロパティが設定されている必要があり、同じ目的で使用することができます。
application {
mainClass = 'com.example.ExampleApplication'
}
application {
mainClass.set("com.example.ExampleApplication")
}
7.1. アプリケーションに引数を渡す
すべての JavaExec
タスクと同様に、Gradle 4.9 以降を使用する場合は、--args='<arguments>'
を使用してコマンドラインから引数を bootRun
に渡すことができます。例: dev
という名前のプロファイルをアクティブにしてアプリケーションを実行するには、次のコマンドを使用できます。
$ ./gradlew bootRun --args='--spring.profiles.active=dev'
詳細については、JavaExec.setArgsString
の javadoc を参照して (英語) ください。
7.2. システムプロパティをアプリケーションに渡す
bootRun
は標準の JavaExec
タスクであるため、ビルドスクリプトで指定することにより、システムプロパティをアプリケーションの JVM に渡すことができます。システムプロパティのその値を構成可能にするには、プロジェクトプロパティ (英語) を使用してその値を設定します。プロジェクトプロパティをオプションにするには、findProperty
を使用して参照します。これにより、次の例に示すように、?:
エルビス演算子を使用してデフォルト値を提供することもできます。
tasks.named("bootRun") {
systemProperty 'com.example.property', findProperty('example') ?: 'default'
}
tasks.named<BootRun>("bootRun") {
systemProperty("com.example.property", findProperty("example") ?: "default")
}
上記の例では、その com.example.property
システムプロパティを example
プロジェクトプロパティの値に設定しています。example
プロジェクトプロパティが設定されていない場合、システムプロパティの値は default
になります。
Gradle を使用すると、次の例に示すように、-P
フラグを使用したコマンドラインなど、さまざまな方法でプロジェクトプロパティを設定できます。
$ ./gradlew bootRun -Pexample=custom
上記の例では、example
プロジェクトプロパティの値を custom
に設定しています。bootRun
は、これを com.example.property
システムプロパティの値として使用します。
7.3. リソースの再読み込み
devtools がプロジェクトに追加されている場合、変更がないかアプリケーションのクラスパスを自動的に監視します。devtools でリロードをトリガーするには、クラスパスを更新するために変更されたファイルを再コンパイルする必要があることに注意してください。devtools の使用の詳細については、リファレンスドキュメントのこのセクションを参照してください。
アプリケーションの静的リソースがソースの場所から読み込まれるように bootRun
を構成することもできます。
tasks.named("bootRun") {
sourceResources sourceSets.main
}
tasks.named<BootRun>("bootRun") {
sourceResources(sourceSets["main"])
}
これにより、開発中に役立つ可能性があるライブアプリケーションに再読み込み可能になります。
8. 事前処理
Spring AOT は、最適化されたバージョンを生成するためにビルド時にコードを分析するプロセスです。これは、GraalVM ネイティブイメージの生成を支援するために最もよく使用されます。
Spring Boot Gradle プラグインは、アプリケーションとテストコードの両方で AOT 処理を実行するために使用できるタスクを提供します。GraalVM ネイティブイメージプラグイン (英語) が適用されると、タスクは自動的に構成されます。
plugins {
id 'org.springframework.boot' version '3.2.2'
id 'org.graalvm.buildtools.native' version '0.9.28'
id 'java'
}
plugins {
id("org.springframework.boot") version "3.2.2"
id("org.graalvm.buildtools.native") version "0.9.28"
java
}
8.1. アプリケーションの処理
@SpringBootApplication
アノテーション付きメインクラスに基づいて、processAot
タスクは、実行時に提供される Bean の永続的なビューを生成し、Bean のインスタンス化ができるだけ簡単になるようにします。コールバックを使用して、ファクトリの追加の後処理が可能です。たとえば、これらは GraalVM がネイティブイメージでコンテキストを初期化するために必要なリフレクション構成を生成するために使用されます。
BeanFactory
はビルド時に完全に準備されるため、条件も評価されます。これは、実行時に通常の Spring Boot アプリケーションが行うことと比べて重要な違いがあります。たとえば、特定の機能をオプトインまたはオプトアウトする場合は、ビルド時に使用する環境を構成する必要があります。このため、processAot
タスクは JavaExec
(英語) タスクであり、必要に応じて環境変数、システムプロパティ、引数を使用して構成できます。
GraalVM ネイティブイメージプラグインの nativeCompile
タスクは、processAot
タスクの出力を使用するように自動的に構成されます。
8.2. 処理テスト
AOT エンジンは、Spring のテストコンテキストフレームワーク を使用する JUnit 5 テストに適用できます。processTestAot
タスクによって適切なテストが処理され、ApplicationContextInitialzer
コードが生成されます。アプリケーション AOT 処理と同様に、BeanFactory
はビルド時に完全に準備されます。processAot
と同様に、processTestAot
タスクは JavaExec
サブクラスであり、必要に応じて構成して、この処理に影響を与えることができます。
GraalVM ネイティブイメージプラグインの nativeTest
タスクは、processAot
および processTestAot
タスクの出力を使用するように自動的に構成されます。
9. アクチュエーターとの統合
9.1. ビルド情報の生成
Spring Boot Actuator の info
エンドポイントは、META-INF/build-info.properties
ファイルの存在下でビルドに関する情報を自動的に公開します。このファイルを生成するために、BuildInfo
(Javadoc) タスクが提供されています。タスクを使用する最も簡単な方法は、プラグインの DSL を使用することです。
springBoot {
buildInfo()
}
springBoot {
buildInfo()
}
これにより、bootBuildInfo
という名前の BuildInfo
(Javadoc) タスクが構成され、存在する場合は、Java プラグインの classes
タスクがそれに依存するようになります。タスクの宛先ディレクトリは、メインソースセットのリソースの出力ディレクトリにある META-INF
(通常は build/resources/main
)です。
デフォルトでは、生成されたビルド情報はプロジェクトから取得されます。
プロパティ | デフォルト値 |
---|---|
|
|
| プロジェクトのグループ |
| プロジェクトの名前 |
| プロジェクトのバージョン |
| プロジェクトが構築されている時間 |
プロパティは、DSL を使用してカスタマイズできます。
springBoot {
buildInfo {
properties {
artifact = 'example-app'
version = '1.2.3'
group = 'com.example'
name = 'Example application'
}
}
}
springBoot {
buildInfo {
properties {
artifact.set("example-app")
version.set("1.2.3")
group.set("com.example")
name.set("Example application")
}
}
}
生成されたビルド情報からデフォルトプロパティのいずれかを除外するには、その名前を除外に追加します。例: time
プロパティは次のように除外できます。
springBoot {
buildInfo {
excludes = ['time']
}
}
springBoot {
buildInfo {
excludes.set(setOf("time"))
}
}
build.time
のデフォルト値は、プロジェクトがビルドされている瞬間です。これの副作用は、タスクが最新のものにならないことです。その結果、プロジェクトのテストを含むより多くのタスクを実行する必要があるため、ビルドに時間がかかります。もう 1 つの副作用は、タスクの出力が常に変化するため、ビルドを真に再現できないことです。ビルドのパフォーマンスまたは再現性を build.time
プロパティの精度よりも高く評価する場合は、前の例に示すように time
プロパティを除外します。
追加のプロパティをビルド情報に追加することもできます。
springBoot {
buildInfo {
properties {
additional = [
'a': 'alpha',
'b': 'bravo'
]
}
}
}
springBoot {
buildInfo {
properties {
additional.set(mapOf(
"a" to "alpha",
"b" to "bravo"
))
}
}
}
追加のプロパティの値は、Provider
を使用して遅延計算できます。
10. 他のプラグインへの反応
別のプラグインが適用されると、Spring Boot プラグインはプロジェクトの構成にさまざまな変更を加えることで反応します。このセクションでは、これらの変更について説明します。
10.1. Java プラグインへの反応
Gradle の java
プラグイン (英語) がプロジェクトに適用されると、Spring Boot プラグインは次のようになります。
プロジェクトの実行可能ファイル uber jar を作成する
bootJar
という名前のBootJar
(Javadoc) タスクを作成します。jar には、メインソースセットのランタイムクラスパス上のすべてが含まれます。クラスはBOOT-INF/classes
にパッケージ化され、jar はBOOT-INF/lib
にパッケージ化されます。bootJar
タスクに依存するようにassemble
タスクを構成します。plain
をアーカイブ分類子の規則として使用するようにjar
タスクを構成します。buildpack (英語) を使用して OCI イメージを作成する
bootBuildImage
という名前のBootBuildImage
(Javadoc) タスクを作成します。bootRun
という名前のBootRun
(Javadoc) タスクを作成します。このタスクは、main
ソースセットを使用してアプリケーションを実行し、メインメソッドを検索し、ランタイムクラスパスを提供するために使用できます。bootTestRun
という名前の 'BootRun' (Javadoc) タスクを作成します。このタスクは、test
ソースセットを使用してアプリケーションを実行し、メインメソッドを検索し、ランタイムクラスパスを提供するために使用できます。bootJar
タスクによって生成された成果物を含むbootArchives
という名前の構成を作成します。Spring Boot Boot の Devtools のように、開発時にのみ必要で、実行可能な jar や war にパッケージされるべきではない依存関係のために、
developmentOnly
という名前の設定を作成します。開発時およびテストの作成および実行時にのみ必要であり、実行可能 jar および war にパッケージ化すべきではない依存関係に対して、
testAndDevelopmentOnly
という名前の構成を作成します。productionRuntimeClasspath
という名前の構成を作成します。これは、runtimeClasspath
からdevelopmentOnly
またはtestDevelopmentOnly
構成にのみ現れる依存関係を除いたものと同等です。エンコーディングが構成されていない
JavaCompile
タスクがUTF-8
を使用するように構成します。-parameters
コンパイラー引数を使用するようにJavaCompile
タスクを構成します。
10.2. Kotlin プラグインへの反応
Kotlin の Gradle プラグイン (英語) がプロジェクトに適用されると、Spring Boot プラグインは次のことを行います。
Spring Boot の依存関係管理で使用される Kotlin バージョンをプラグインのバージョンに合わせます。これは、Kotlin プラグインのバージョンに一致する値で
kotlin.version
プロパティを設定することにより実現されます。-java-parameters
コンパイラー引数を使用するようにKotlinCompile
タスクを構成します。
10.3. War プラグインへの反応
Gradle の war
プラグイン (英語) がプロジェクトに適用されると、Spring Boot プラグインは次のようになります。
プロジェクトの実行可能な fat war を作成する
bootWar
という名前のBootWar
(Javadoc) タスクを作成します。標準パッケージに加えて、providedRuntime
構成のすべてがWEB-INF/lib-provided
にパッケージされます。bootWar
タスクに依存するようにassemble
タスクを構成します。plain
をアーカイブ分類子の規則として使用するようにwar
タスクを構成します。bootArchives
構成を構成して、bootWar
タスクによって生成された成果物を含めます。
10.4. 依存関係管理プラグインへの対応
io.spring.dependency-management
プラグイン [GitHub] (英語) がプロジェクトに適用されると、Spring Boot プラグインは spring-boot-dependencies
bom を自動的にインポートします。
10.5. アプリケーションプラグインへの反応
Gradle の application
プラグイン (英語) がプロジェクトに適用されると、Spring Boot プラグインは次のようになります。
java -jar
を使用してbootArchives
構成でアーティファクトを起動するスクリプトを作成するbootStartScripts
という名前のCreateStartScripts
タスクを作成します。タスクは、defaultJvmOpts
プロパティの規則としてapplicationDefaultJvmArgs
プロパティを使用するように構成されています。boot
という名前の新しいディストリビューションを作成し、lib
ディレクトリのbootArchives
構成のアーティファクトとbin
ディレクトリの開始スクリプトを含むように構成します。main
プロパティの規則としてmainClassName
プロパティを使用するようにbootRun
タスクを構成します。bootRun
タスクとbootTestRun
タスクが、jvmArgs
プロパティの規則としてapplicationDefaultJvmArgs
プロパティを使用するように構成します。マニフェストの
Start-Class
エントリの規則としてmainClassName
プロパティを使用するようにbootJar
タスクを構成します。マニフェストの
Start-Class
エントリの規則としてmainClassName
プロパティを使用するようにbootWar
タスクを構成します。
10.6. GraalVM ネイティブイメージプラグインへの対応
GraalVM ネイティブイメージプラグイン (英語) がプロジェクトに適用されると、Spring Boot プラグインは次のことを行います。
以下の
org.springframework.boot.aot
プラグインを適用します。aot
およびaotTest
ソースセットを登録します。aot
ソースセット内のアプリケーションの AOT 最適化ソースを生成するprocessAot
という名前のProcessAot
タスクを登録します。processAot
に依存するaot
ソースセットの Java コンパイルおよびプロセスリソースタスクを構成します。アプリケーションのテスト用に AOT 最適化ソースを生成する
processTestAot
という名前のProcessTestAot
タスクをaotTest
ソースセットに登録します。processTestAot
に依存するaotTest
ソースセットの Java コンパイルおよびプロセスリソースタスクを構成します。
aot
ソースセットの出力をmain
GraalVM ネイティブバイナリのクラスパスに追加します。aotTest
ソースセットの出力をtest
GraalVM ネイティブバイナリのクラスパスに追加します。ツールチェーン検出を無効にするように GraalVM 拡張機能を構成します。
GraalVM 22.3 以降を必要とするように各 GraalVM ネイティブバイナリを構成します。
collectReachabilityMetadata
タスクによって生成された到達可能性メタデータをその jar に含めるようにbootJar
タスクを構成します。paketobuildpacks/builder-jammy-tiny:latest
をそのビルダーとして使用し、その環境でBP_NATIVE_IMAGE
をtrue
に設定するようにbootBuildImage
タスクを構成します。