The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

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

新規プロジェクトの作成

To scaffold a Gradle project you can either use the Quarkus CLI or the Quarkus Maven plugin:

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

For more information about how to install the Quarkus CLI and use it, please refer to the Quarkus CLI guide.

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:2.11.1.Final:create \
    -DprojectGroupId=my-groupId \
    -DprojectArtifactId=my-artifactId \
    -Dextensions="resteasy-reactive,resteasy-reactive-jackson" \
    -DbuildTool=gradle
If you just launch mvn io.quarkus.platform:quarkus-maven-plugin:2.11.1.Final:create the Maven plugin asks for user inputs. You can disable this interactive mode (and use default values) by passing -B to the Maven command.
If you prefer using the Kotlin DSL, use gradle-kotlin-dsl instead of gradle.

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

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

The project is generated in a directory named after the passed artifactId.

A pair of Dockerfiles for native and JVM modes are also generated in src/main/docker. Instructions to build the image and run the container are written in those Dockerfiles.

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

By default, Quarkus tests in JVM mode are run using the test configuration profile. If you are not familiar with Quarkus configuration profiles, everything you need to know is explained in the Configuration Profiles Documentation.

しかし、以下に示す 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プロジェクトの内部から、利用可能なエクステンションのリストを取得することができます。

CLI
quarkus extension
Gradle
./gradlew listExtensions

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

CLI
quarkus extension add 'hibernate-validator'
Gradle
./gradlew addExtension --extensions="hibernate-validator"

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

io.quarkus:quarkus-agroal エクステンション名は、エクステンションのGAV名です。しかし、部分的な名前を渡すことができ、Quarkusは適切なエクステンションを見つけるために最善を尽くします。例えば、 agroalAgroalagroio.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?
[...]

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

CLI
quarkus extension add 'smallrye-*'
Gradle
./gradlew addExtension --extensions="smallrye-*"

開発モード

Quarkus comes with a built-in development mode. You can start it with:

CLI
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 オプションを次のように使用します。

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

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

CLI
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.

The remote side does not need to include Maven or any other development tools. The normal fast-jar Dockerfile that is generated with a new Quarkus application is all you need. If you are using bare metal launch the Quarkus runner jar, do not attempt to run normal dev mode.

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

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

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

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

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

Configuration property

タイプ

デフォルト

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

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

list of string

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

Environment variable: QUARKUS_LIVE_RELOAD_PASSWORD

string

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

Environment variable: QUARKUS_LIVE_RELOAD_URL

string

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

Environment variable: QUARKUS_LIVE_RELOAD_CONNECT_TIMEOUT

Duration

30S

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

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 をサスペンドせずに起動します。

You can also run a Quarkus application in debug mode with a suspended JVM using:

CLI
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 をクリックします。

In a separated terminal, run:

CLI
quarkus dev
Gradle
./gradlew --console=plain quarkusDev

and enjoy a highly productive environment.

IntelliJ IDEA

In IntelliJ IDEA:

  1. From inside IntelliJ IDEA select File → New → Project From Existing Sources…​ or, if you are on the welcome dialog, select Import project.

  2. プロジェクトのルートを選択します。

  3. Import project from external model を選択して Gradle

  4. Next を数回(必要に応じてオプションを確認)

  5. 最後の画面でFinishをクリックします。

In a separated terminal or in the embedded terminal, run:

CLI
quarkus dev
Gradle
./gradlew --console=plain quarkusDev

楽しんで!

Apache NetBeans

NetBeansの場合:

  1. File → Open Project を選択

  2. プロジェクトのルートを選択します。

  3. Open Project をクリックしてください。

In a separated terminal or the embedded terminal, go to the project root and run:

CLI
quarkus dev
Gradle
./gradlew --console=plain quarkusDev

楽しんで!

Visual Studio Code

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

Downloading dependencies for offline development and testing

Quarkus extension dependencies are divided into the runtime extension dependencies that end up on the application runtime classpath and the deployment (or build time) extension dependencies that are resolved by Quarkus only at application build time to create the build classpath. Application developers are expected to express dependencies only on the runtime artifacts of Quarkus extensions.

To enable the use-case of building and testing a Quarkus application offline, the plugin includes the quarkusGoOffline task that could be called from the command line like this:

./gradlew quarkusGoOffline

This task will resolve all the runtime, build time, test and dev mode dependencies of the application to the Gradle cache. Once executed, you will be able to safely run quarkus task with --offline flag.

ネイティブ実行可能ファイルのビルド

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

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

Create a native executable using:

CLI
quarkus build --native
Gradle
./gradlew build -Dquarkus.package.type=native

A native executable will be present in build/.

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

Groovy DSL
quarkusBuild {
    nativeArgs {
        containerBuild = true (1)
        builderImage = "quay.io/quarkus/ubi-quarkus-native-image:22.1-java11" (2)
    }
}
1 quarkus.native.container-build プロパティーを true
2 Set quarkus.native.builder-image property to quay.io/quarkus/ubi-quarkus-native-image:22.1-java11
Kotlin DSL
tasks.quarkusBuild {
    nativeArgs {
        "container-build" to true (1)
        "builder-image" to "quay.io/quarkus/ubi-quarkus-native-image:22.1-java11" (2)
    }
}
1 quarkus.native.container-build プロパティーを true
2 Set quarkus.native.builder-image property to quay.io/quarkus/ubi-quarkus-native-image:22.1-java11

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

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

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

CLI
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

The produced executable will be a 64-bit Linux executable, so depending on your operating system it may no longer be runnable. However, it’s not an issue as we are going to copy it to a Docker container. Note that in this case the build itself runs in a Docker container too, so you don’t need to have GraalVM installed locally.

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

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

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

ネイティブテストの実行

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

./gradlew testNative

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

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

Groovy DSL
quarkus {
    sourceSets {
        extraNativeTest = sourceSets.integrationTest
    }
}
Kotlin DSL
quarkus {
    sourceSets {
        setExtraNativeTest(sourceSets["integrationTest"])
    }
}

Running integration tests

Quarkus integration tests (annotated with @QuarkusIntegrationTest) will run on the artifact produced by Quarkus. Those tests can be placed in a src/integrationTest/java directory and executed using:

./gradlew quarkusIntTest

This task depends on both check and quarkusBuild tasks. The final artifact will be produced before running tests.

fast-jar の使用

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

You can run the application using: java -jar build/quarkus-app/quarkus-run.jar.

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

UberJar のビルド

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

CLI
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 を検出しません。

The best way to enable CDI bean discovery for a module in a multi-module project would be to include a META-INF/beans.xml file, unless it is the main application module already configured with the quarkus-maven-plugin, in which case it will be indexed automatically.

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

More information on this topic can be found on the Bean Discovery section of the CDI guide.

アプリケーションの発行

In order to make sure the right dependency versions are being used by Gradle, the BOM is declared as an enforcedPlatform in your build file. By default, the maven-publish plugin will prevent you from publishing your application due to this enforcedPlatform. This validation can be skipped by adding the following configuration in your build file:

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