バージョン:

Gradleを使ってQuarkusアプリをビルドする

新規プロジェクトの作成

Gradleプロジェクトを生成するには、 Quarkus CLIまたはQuarkus Mavenプラグインを使用できます:

コマンドラインインタフェース

quarkus create app my-groupId:my-artifactId \
    --extension=resteasy-reactive,resteasy-reactive-jackson \
    --gradle

Quarkus CLIのインストール方法や使用方法については、 Quarkus CLIガイドを参照してください。

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:2.16.12.Final:create \
    -DprojectGroupId=my-groupId \
    -DprojectArtifactId=my-artifactId \
    -Dextensions="resteasy-reactive,resteasy-reactive-jackson" \
    -DbuildTool=gradle

mvn io.quarkus.platform:quarkus-maven-plugin:2.16.12.Final:create を単に起動すると、Maven プラグインはユーザー入力を求めます。Mavenコマンドに -B を渡すことで、このインタラクティブモードを無効にする(およびデフォルト値を使用する)ことができます。

Kotlin DSLを使用したい場合は、 gradle の代わりに gradle-kotlin-dsl を使用してください。

Quarkusプロジェクトのスキャフォールドは、プロジェクトにGradleラッパー( ./gradlew )を自動的にインストールします。

スタンドアロンのGradleを使用したい場合は、Gradle 7.5.1 を使用してください。

プロジェクトは、渡されたartifactIdにちなんだ名前のディレクトリに生成されます。

ネイティブモードとJVMモード用の一対のDockerfilesも src/main/docker で生成されます。これらのDockerfileには、イメージをビルドしてコンテナを実行する手順が書かれています。

JVMモードでのカスタムテスト設定プロファイル

デフォルトでは、JVMモードのQuarkusテストは、 test 設定プロファイルを使用して実行されます。Quarkusの設定プロファイルに慣れていない場合は、設定プロファイルのドキュメントで必要な情報がすべて説明されていますので、そちらを参照してください。

しかし、以下に示す Gradle ビルド設定でテスト用のカスタム設定プロファイルを使用することは可能です。これは例えば、デフォルトのテストデータベースではない特定のデータベースを使ってテストを実行する必要がある場合に便利です。

Groovy DSL

test {
    systemProperty "quarkus.test.profile", "foo" (1)
}

1	`foo` 設定プロファイルがテストの実行に使用されます。

Kotlin DSL

tasks.test {
    systemProperty("quarkus.test.profile", "foo") (1)
}

1	`foo` 設定プロファイルがテストの実行に使用されます。

今のところ、ネイティブモードでカスタムテスト設定プロファイルを使用することはできません。ネイティブテストは常に prod プロファイルを使用して実行されます。

エクステンションへの対応

Quarkusプロジェクトの内部から、利用可能なエクステンションのリストを取得することができます。

コマンドラインインタフェース

quarkus extension

Gradle

./gradlew listExtensions

以下を使ってエクステンションを有効化できます。

コマンドラインインタフェース

quarkus extension add 'hibernate-validator'

Gradle

./gradlew addExtension --extensions='hibernate-validator'

エクステンションは、カンマ区切りのリストを使用して渡されます。

io.quarkus:quarkus-agroal エクステンション名は、エクステンションのGAV名です。しかし、部分的な名前を渡すことができ、Quarkusは適切なエクステンションを見つけるために最善を尽くします。例えば、 agroal 、 Agroal 、 agro は io.quarkus:quarkus-agroal に展開されます。エクステンションが見つからなかったり、複数のエクステンションが一致した場合は、コマンドの結果に赤いチェックマーク❌が表示されます。

$ ./gradlew addExtension --extensions="jdbc,agroal,non-exist-ent"
[...]
❌ Multiple extensions matching 'jdbc'
     * io.quarkus:quarkus-jdbc-h2
     * io.quarkus:quarkus-jdbc-mariadb
     * io.quarkus:quarkus-jdbc-postgresql
     Be more specific e.g using the exact name or the full gav.
✅ Adding extension io.quarkus:quarkus-agroal
❌ Cannot find a dependency matching 'non-exist-ent', maybe a typo?
[...]

グロブパターンに一致するエクステンションをすべてインストールすることができます。

コマンドラインインタフェース

quarkus extension add 'smallrye-*'

Gradle

./gradlew addExtension --extensions='smallrye-*'

開発モード

Quarkusには開発モードが組み込まれています。以下のコマンドで起動することができます:

コマンドラインインタフェース

quarkus dev

Gradle

./gradlew --console=plain quarkusDev

この方法で実行する場合、継続的テストの使い勝手は同じにはなりません。gradleはデーモンとして実行されるため、Quarkusは「きれいな」テスト出力を描くことができず、出力のログを取るだけになってしまうからです。

その後、アプリケーションのソース、リソース、および設定を更新することができます。変更は実行中のアプリケーションに自動的に反映されます。変更がすぐに反映されるので、UIやデータベースにまたがった開発をするのに最適です。

quarkusDev は、バックグラウンドでのコンパイルによるホットデプロイを可能にします。つまり、Java ファイルやリソースファイルを変更してブラウザを更新すると、これらの変更が自動的に有効になります。これは、設定プロパティーファイルのようなリソースファイルにも適用されます。ブラウザをリフレッシュする行為は、ワークスペースのスキャンをトリガし、変更が検出された場合、Javaファイルがコンパイルされ、アプリケーションが再配置されると、あなたの要求は再配置されたアプリケーションによって処理されます。コンパイルやデプロイに問題がある場合は、エラーページでお知らせします。

CTRL+C を叩いてアプリケーションを停止させます。

開発環境が動作する作業ディレクトリーを変更することができます:

Groovy DSL

quarkusDev {
    workingDir = rootProject.projectDir
}

Kotlin DSL

tasks.quarkusDev {
    workingDir = rootProject.projectDir.toString()
}

デフォルトでは、 quarkusDev タスクは compileJava コンパイラ・オプションを使用します。これらは、タスクの compilerArgs プロパティーを設定することで上書きすることができます。

デフォルトでは、 quarkusDev はデバッグホストを localhost に設定します (セキュリティー上の理由から)。これを変更する必要がある場合、例えばすべてのホストでデバッグを有効にしたい場合は、 -DdebugHost オプションを次のように使用します。

コマンドラインインタフェース

quarkus dev -DdebugHost=0.0.0.0

Gradle

./gradlew --console=plain quarkusDev -DdebugHost=0.0.0.0

このプラグインは quarkusDev の設定も公開しています。この設定を使って依存関係を宣言すると、その依存関係の使用が開発モードに制限されます。 quarkusDev の設定は以下のように使用できます。

Groovy DSL

dependencies {
    quarkusDev 'io.quarkus:quarkus-jdbc-h2'
}

Kotlin DSL

dependencies {
    quarkusDev("io.quarkus:quarkus-jdbc-h2")
}

リモート開発モード

開発モードをリモートで使用することができるので、コンテナー環境(OpenShiftなど)でQuarkusを実行して、ローカルファイルに加えられた変更をすぐに確認できるようにすることができます。

これにより、実際にアプリを実行するのと同じ環境で、同じサービスにアクセスしながら開発することができます。

本番環境では使用しないでください。開発環境でのみ使用してください。本番環境のアプリケーションを開発モードで実行してはいけません。

そのためには、 mutable-jar のフォーマットを使って mutable アプリケーションを構築する必要があります。 application.properties で以下のプロパティを設定します。

quarkus.package.type=mutable-jar (1)
quarkus.live-reload.password=changeit (2)
quarkus.live-reload.url=http://my.cluster.host.com:8080 (3)

1	これは、QuarkusにMutable-jar形式を使用するように指示します。ミュータブルアプリケーションには、Quarkusのデプロイメント時間の部分も含まれているため、より多くのディスクスペースを占有します。普通に実行した場合は、イミュータブルアプリケーションと同じ速度で起動し、同じメモリーを使用しますが、devモードで起動することもできます。
2	リモート側とローカル側の通信を安全に保つためのパスワードです。
3	アプリがdevモードで実行されるURL。これはローカル側でのみ必要なので、プロパティーファイルから除外して、コマンドラインでシステムプロパティーとして指定するとよいでしょう。

mutable-jar は、通常のQuarkus jarをビルドするのと同じ方法でビルドできます。つまり、次を実行します。

コマンドラインインタフェース

quarkus build

Gradle

./gradlew build

リモートホストでQuarkusを起動する前に、環境変数 QUARKUS_LAUNCH_DEVMODE=true を設定します。ベアメタルを使用している場合は、 export QUARKUS_LAUNCH_DEVMODE=true コマンドで設定し、適切に java -jar … コマンドでアプリケーションを実行します。

アプリケーションをdocker経由で実行する場合は、 docker run コマンドに -e QUARKUS_LAUNCH_DEVMODE=true を追加してイメージを起動します。アプリケーションが起動すると、ログに次のような行が表示されるはずです: Profile dev activated. Live Coding activated .

リモート側にはMavenなどの開発ツールを入れる必要はありません。新しいQuarkusアプリケーションで生成される通常の fast-jar Dockerfileがあれば大丈夫です。ベアメタルのQuarkus runner jarを起動している場合は、通常のdevmodeを実行しようとしないでください。

ここで、 remote-dev コマンドを使用して、ローカルエージェントをリモートホストに接続する必要があります。

./gradlew quarkusRemoteDev -Dquarkus.live-reload.url=http://my-remote-host:8080

これでブラウザを更新するたびに、ローカルで行った変更がリモートアプリにすぐに表示されるようになりました。

すべての設定項目を以下に示します。

ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能

Configuration property	タイプ	デフォルト
`quarkus.live-reload.instrumentation` Whether Quarkus should enable its ability to not do a full restart when changes to classes are compatible with JVM instrumentation. If this is set to true, Quarkus will perform class redefinition when possible. Environment variable: `QUARKUS_LIVE_RELOAD_INSTRUMENTATION` Show more	boolean	`false`
`quarkus.live-reload.watched-resources` The names of additional resource files to watch for changes, triggering a reload on change. Directories are not supported. Environment variable: `QUARKUS_LIVE_RELOAD_WATCHED_RESOURCES` Show more	文字列のリスト
`quarkus.live-reload.password` Password used to use to connect to the remote dev-mode application Environment variable: `QUARKUS_LIVE_RELOAD_PASSWORD` Show more	string
`quarkus.live-reload.url` URL used to use to connect to the remote dev-mode application Environment variable: `QUARKUS_LIVE_RELOAD_URL` Show more	string
`quarkus.live-reload.connect-timeout` The amount of time to wait for a remote dev connect or reconnect Environment variable: `QUARKUS_LIVE_RELOAD_CONNECT_TIMEOUT` Show more	Duration	`30S`
`quarkus.live-reload.retry-interval` The amount of time to wait between attempts when connecting to the server side of remote dev Environment variable: `QUARKUS_LIVE_RELOAD_RETRY_INTERVAL` Show more	Duration	`2S`
`quarkus.live-reload.retry-max-attempts` The maximum number of attempts when connecting to the server side of remote dev Environment variable: `QUARKUS_LIVE_RELOAD_RETRY_MAX_ATTEMPTS` Show more	int	`10`

Configuration property

タイプ

デフォルト

quarkus.live-reload.instrumentation

Whether Quarkus should enable its ability to not do a full restart when changes to classes are compatible with JVM instrumentation. If this is set to true, Quarkus will perform class redefinition when possible.

Environment variable: QUARKUS_LIVE_RELOAD_INSTRUMENTATION

boolean

false

quarkus.live-reload.watched-resources

The names of additional resource files to watch for changes, triggering a reload on change. Directories are not supported.

Environment variable: QUARKUS_LIVE_RELOAD_WATCHED_RESOURCES

文字列のリスト

quarkus.live-reload.password

Password used to use to connect to the remote dev-mode application

Environment variable: QUARKUS_LIVE_RELOAD_PASSWORD

string

quarkus.live-reload.url

URL used to use to connect to the remote dev-mode application

Environment variable: QUARKUS_LIVE_RELOAD_URL

string

quarkus.live-reload.connect-timeout

The amount of time to wait for a remote dev connect or reconnect

Environment variable: QUARKUS_LIVE_RELOAD_CONNECT_TIMEOUT

Duration

30S

quarkus.live-reload.retry-interval

The amount of time to wait between attempts when connecting to the server side of remote dev

Environment variable: QUARKUS_LIVE_RELOAD_RETRY_INTERVAL

Duration

2S

quarkus.live-reload.retry-max-attempts

The maximum number of attempts when connecting to the server side of remote dev

Environment variable: QUARKUS_LIVE_RELOAD_RETRY_MAX_ATTEMPTS

int

10

期間フォーマットについて

期間のフォーマットは標準の java.time.Duration フォーマットを使用します。詳細は Duration#parse() javadoc を参照してください。

数値で始まる期間の値を指定することもできます。この場合、値が数値のみで構成されている場合、コンバーターは値を秒として扱います。そうでない場合は、 PT が暗黙的に値の前に付加され、標準の java.time.Duration 形式が得られます。

デバッグ

開発モードでは、Quarkusはデフォルトでデバッグモードを有効にして起動し、JVMをサスペンドせずにポート 5005 をリッスンします。

この動作は、 debug システム・プロパティーに以下の値のいずれかを与えることで変更できます。

false - JVMはデバッグモードを無効にして起動します。
true - JVM はデバッグモードで起動され、 `5005`ポートをリッスンします。
client - JVM はクライアントモードで起動し、 localhost:5005 に接続を試みます。
{port} - JVM はデバッグモードで起動されています。 {port}

追加のシステム・プロパティー suspend は、デバッグ・モードで起動されたときに JVM をサスペンドするために使用できます。 suspend は以下の値をサポートしています。

y または true - デバッグモードの JVM 起動が中断されます。
n または false - デバッグモードの JVM をサスペンドせずに起動します。

また、JVMをサスペンドした状態で、デバッグモードでQuarkusアプリケーションを実行することもできます。

コマンドラインインタフェース

quarkus dev -Dsuspend -Ddebug

Gradle

./gradlew --console=plain quarkusDev -Dsuspend -Ddebug

次に、デバッガーを localhost:5005 にアタッチします。

IDEでのインポート

プロジェクトを生成したら、お気に入りのIDEでインポートすることができます。唯一の条件は、Gradleプロジェクトをインポートできることです。

Eclipse

Eclipse で、 File → Import をクリックします。ウィザードで、 Gradle → Existing Gradle Project を選択します。次の画面で、プロジェクトのルートの場所を選択します。次の画面では、見つかったモジュールのリストが表示されるので、生成されたプロジェクトを選択して Finish をクリックします。

別のターミナルで、次を実行します:

コマンドラインインタフェース

quarkus dev

Gradle

./gradlew --console=plain quarkusDev

そして、生産性の高い環境をお楽しみください。

IntelliJ IDEA

IntelliJ IDEAの場合:

IntelliJ IDEAの内部から File → New → Project From Existing Sources… を選択するか、ウェルカム・ダイアログからであれば、 Import project を選択してください。
プロジェクトのルートを選択します。
Import project from external model を選択して Gradle
Next を数回クリックします (必要に応じてさまざまなオプションを確認してください)。
最後の画面でFinishをクリックします。

別の端末や組込端末で、次を実行します:

コマンドラインインタフェース

quarkus dev

Gradle

./gradlew --console=plain quarkusDev

お楽しみください！

Apache NetBeans

NetBeansの場合:

File → Open Project を選択
プロジェクトのルートを選択します。
Open Project をクリックしてください。

別のターミナルまたは組込ターミナルで、プロジェクトのルートに移動して次を実行します:

コマンドラインインタフェース

quarkus dev

Gradle

./gradlew --console=plain quarkusDev

お楽しみください！

Visual Studio Code

VS Codeでプロジェクトディレクトリーを開きます。Java Extension Pack(Javaエクステンションのセットをグループ化したもの)をインストールしている場合、プロジェクトはGradleプロジェクトとして読み込まれます。

オフラインでの開発やテストのための依存ファイルのダウンロード

Quarkusのエクステンションの依存関係は、アプリケーションの実行時クラスパス上で終わる実行時エクステンションの依存関係と、ビルドクラスパスを作成するためにアプリケーションのビルド時にQuarkusによってのみ解決されるデプロイメント（またはビルド時）エクステンションの依存関係に分けられます。アプリケーション開発者は、Quarkusのエクステンションの実行時アーティファクトにのみ依存関係を表現することが期待されます。

オフラインでQuarkusアプリケーションを構築してテストするというユースケースを可能にするために、プラグインには quarkusGoOffline タスクが含まれており、コマンドラインから次のように呼び出すことができます。

./gradlew quarkusGoOffline

このタスクは、アプリケーションの実行時、ビルド時、テスト、開発モードのすべての依存関係をGradleのキャッシュに解決します。実行すると、 --offline フラグを付けて quarkus タスクを安全に実行できるようになります。

ネイティブ実行可能ファイルの構築

ネイティブ実行可能ファイルにより、Quarkusアプリケーションはコンテナーやサーバーレスのワークロードに最適です。

GRAALVM_HOME を設定し、最新リリースのGraalVM バージョン 22.3 を指していることを確認してください。(必ずGraalVMのJava 11バージョンを使用してください)。

ネイティブ実行可能ファイルの作成:

コマンドラインインタフェース

quarkus build --native

Gradle

./gradlew build -Dquarkus.package.type=native

ネイティブ実行可能ファイルは、 build/ に存在します。

ネイティブ関連のプロパティーは、 application.properties ファイルにコマンドライン引数として追加するか、 quarkusBuild タスクに追加することができます。 quarkusBuild タスクの設定は以下のように行います:

Groovy DSL

quarkusBuild {
    nativeArgs {
        containerBuild = true (1)
        builderImage = "quay.io/quarkus/ubi-quarkus-graalvmce-builder-image:22.3-java17" (2)
    }
}

1	`quarkus.native.container-build` プロパティーを `true`
2	`quarkus.native.build-image` プロパティーに `quay.io/quarkus/ubi-quarkus-native-image:22.3-java17` をセット

Kotlin DSL

tasks.quarkusBuild {
    nativeArgs {
        "container-build" to true (1)
        "builder-image" to "quay.io/quarkus/ubi-quarkus-graalvmce-builder-image:22.3-java17" (2)
    }
}

1	`quarkus.native.container-build` プロパティーを `true`
2	`quarkus.native.build-image` プロパティーに `quay.io/quarkus/ubi-quarkus-native-image:22.3-java17` をセット

Gradle Groovy DSL を使用する場合、プロパティーキーは小文字のキャメルケース表記に従わなければなりません。例: container-build は無効なので、 containerBuild で置き換えてください。この制限は Gradle Kotlin DSL には適用されません。

コンテナーフレンドリーな実行可能ファイルをビルドする

ネイティブ実行可能ファイルは、お使いのオペレーティングシステムに固有のものになります。コンテナー内で実行される実行ファイルを作成するには、次のようにします。

コマンドラインインタフェース

quarkus build --native --no-tests -Dquarkus.native.container-build=true
# The --no-tests flag is required only on Windows and macOS.

Gradle

./gradlew build -Dquarkus.package.type=native -Dquarkus.native.container-build=true

生成される実行ファイルは64bitのLinux実行ファイルになるので、OSによっては実行できなくなる可能性があります。しかし、Dockerコンテナーにコピーするので問題ありません。この場合、ビルド自体もDockerコンテナー内で動作するので、ローカルにGraalVMをインストールする必要はないことに注目してください。

デフォルトでは、 quay.io/quarkus/ubi-quarkus-graalvmce-builder-image:22.3-java17 Dockerイメージを使用してネイティブ実行可能ファイルが生成されます。

異なるDockerイメージでネイティブ実行可能ファイルをビルドしたい場合(例えば、異なるGraalVMのバージョンを使用するなど)、 -Dquarkus.native.builder-image=<image name> のbuild引数を使用してください。

利用可能なDockerイメージのリストは、 quay.ioにあります。特定のQuarkusのバージョンは、利用可能なすべてのイメージと互換性がない場合があることに注意してください。

ネイティブテストの実行

次のようにネイティブテストを実行します:

./gradlew testNative

このタスクは quarkusBuild に依存しているので、テストを実行する前にネイティブイメージを生成します。

デフォルトでは、 native-test のソースセットは、 main と test のソースセットに基づいています。ソースセットを追加することも可能です。たとえば、統合テストが integrationTest のソースセットにある場合は、次のように指定します。

Groovy DSL

quarkus {
    sourceSets {
        extraNativeTest = sourceSets.integrationTest
    }
}

Kotlin DSL

quarkus {
    sourceSets {
        setExtraNativeTest(sourceSets["integrationTest"])
    }
}

結合テストの実行

（ @QuarkusIntegrationTest でアノテーションされた）Quarkus結合テストは、Quarkusが生成したアーティファクトで実行されます。これらのテストは、 src/integrationTest/java ディレクトリに配置し、それを使用して実行することができます。

./gradlew quarkusIntTest

このタスクは test と quarkusBuild タスクに依存しています。最終的なアーティファクトは、テストを実行する前に生成されます。

fast-jar の使用

fast-jar がデフォルトの quarkus パッケージタイプになりました。 ./gradlew build コマンドの結果、 build の下に quarkus-app という名前の新しいディレクトリが作成されます。

アプリケーションは次のようにで実行できます: java -jar target/quarkus-app/quarkus-run.jar

生成された jar を正常に実行するためには、 quarkus-app ディレクトリのすべての内容が必要です。いずれかのファイルが欠落していると、アプリケーションが起動しなかったり、正しく機能しない可能性があります。

fast-jar パッケージングでは、どの依存関係のjarにクラスやリソースが含まれているかという情報がインデックス化されているため、レガシーのQuarkus jarよりも起動が少し速く、メモリ消費量もわずかに少ないアーティファクトを作成できます。このため、クラスやリソースをロードする際に、レガシー jar が必要とするクラスパス上のすべての jar を検索する必要がなくなります。

UberJar のビルド

Quarkus Gradleプラグインは、以下のように --uber-jar 引数を指定して UberJar の生成をサポートしています。

コマンドラインインタフェース

quarkus build -Dquarkus.package.type=uber-jar

Gradle

./gradlew build -Dquarkus.package.type=uber-jar

UberJar を作成する際に、 --ignored-entry 引数を使用して生成された jar から除外したいエントリーを指定することができます。

./gradlew quarkusBuild -Dquarkus.package.type=uber-jar --ignored-entry=META-INF/file1.txt

エントリーは、生成された Uber-Jar のルートからの相対的なものです。追加の --ignored-entry 引数を追加することで、複数のエントリーを指定することができます。

マルチモジュールプロジェクトでの作業

デフォルトでは、Quarkusは別のモジュール内のCDI Bean を検出しません。

マルチモジュールプロジェクトのモジュールでCDI Bean検出を有効にするベストの方法は、モジュールが、メインアプリケーションモジュールで、すでにquarkus-maven-pluginで設定されていない限り、 META-INF/beans.xml ファイルをインクルードすることです。モジュールが、メインアプリケーションモジュールで、すでにquarkus-maven-pluginで設定されている場合は、自動的にインデックスが作成されます。

あるいは、 META-INF/beans.xml ファイルの代わりに使える非公式の Gradle Jandex プラグインもあります。

このトピックの詳細については、CDIガイドの Bean Discovery セクションを参照してください。

アプリケーションの発行

Gradle で正しい依存関係のバージョンが使用されていることを担保するために、BOM はビルドファイル内で enforcedPlatform として宣言されています。デフォルトでは、 maven-publish プラグインは、この enforcedPlatform を理由にアプリケーションの公開を阻止します。 build.gradle ファイルに以下の設定を追加することで、この検証をスキップすることができます。

Groovy DSL

tasks.withType(GenerateModuleMetadata).configureEach {
    suppressedValidationErrors.add('enforced-platform')
}

Kotlin DSL

tasks.withType<GenerateModuleMetadata>().configureEach {
    suppressedValidationErrors.add("enforced-platform")
}

新規プロジェクトの作成
- JVMモードでのカスタムテスト設定プロファイル
エクステンションへの対応
開発モード
- リモート開発モード
デバッグ
IDEでのインポート
オフラインでの開発やテストのための依存ファイルのダウンロード
ネイティブ実行可能ファイルの構築
- コンテナーフレンドリーな実行可能ファイルをビルドする
ネイティブテストの実行
結合テストの実行
fast-jar の使用
UberJar のビルド
- マルチモジュールプロジェクトでの作業
アプリケーションの発行