Gradleを使ってQuarkusアプリをビルドする
新規プロジェクトの作成
Gradleプロジェクトを生成するには、 Quarkus CLIまたはQuarkus Mavenプラグインを使用できます:
Kotlin DSLを使用したい場合は、 gradle の代わりに gradle-kotlin-dsl を使用してください。
|
Quarkusプロジェクトのスキャフォールドは、プロジェクトにGradleラッパー( スタンドアロンのGradleを使用したい場合は、Gradle 7.5.1 を使用してください。 |
プロジェクトは、渡されたartifactIdにちなんだ名前のディレクトリに生成されます。
ネイティブモードとJVMモード用の一対のDockerfilesも src/main/docker
で生成されます。これらのDockerfileには、イメージをビルドしてコンテナを実行する手順が書かれています。
JVMモードでのカスタムテスト構成プロファイル
デフォルトでは、JVMモードのQuarkusテストは、 test
設定プロファイルを使用して実行されます。Quarkusの設定プロファイルに慣れていない場合は、 設定プロファイル のドキュメントで必要な情報がすべて説明されていますので、そちらを参照してください。
しかし、以下に示す Gradle ビルド設定でテスト用のカスタム設定プロファイルを使用することは可能です。これは例えば、デフォルトのテストデータベースではない特定のデータベースを使ってテストを実行する必要がある場合に便利です。
今のところ、ネイティブモードでカスタムテスト設定プロファイルを使用することはできません。ネイティブテストは常に |
エクステンションへの対応
Quarkusプロジェクトの内部から、利用可能なエクステンションのリストを取得することができます。
quarkus extension
./gradlew listExtensions
以下を使ってエクステンションを有効化できます。
quarkus extension add 'hibernate-validator'
./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-*'
./gradlew addExtension --extensions='smallrye-*'
開発モード
Quarkusには開発モードが組み込まれています。以下のコマンドで起動することができます:
quarkus dev
./gradlew --console=plain quarkusDev
この方法で実行する場合、継続的テストの使い勝手は同じにはなりません。gradleはデーモンとして実行されるため、Quarkusは「きれいな」テスト出力を描くことができず、出力のログを取るだけになってしまうからです。
その後、アプリケーションのソース、リソース、および設定を更新することができます。変更は実行中のアプリケーションに自動的に反映されます。変更がすぐに反映されるので、UIやデータベースにまたがった開発をするのに最適です。
quarkusDev
は、バックグラウンドでのコンパイルによるホットデプロイを可能にします。つまり、Java ファイルやリソースファイルを変更してブラウザを更新すると、これらの変更が自動的に有効になります。これは、設定プロパティーファイルのようなリソースファイルにも適用されます。ブラウザをリフレッシュする行為は、ワークスペースのスキャンをトリガし、変更が検出された場合、Javaファイルがコンパイルされ、アプリケーションが再配置されると、あなたの要求は再配置されたアプリケーションによって処理されます。コンパイルやデプロイに問題がある場合は、エラーページでお知らせします。
CTRL+C
を叩いてアプリケーションを停止させます。
開発環境が動作する作業ディレクトリーを変更することができます:
デフォルトでは、 |
デフォルトでは、 コマンドラインインタフェース
Gradle
|
このプラグインは quarkusDev
の設定も公開しています。この設定を使って依存関係を宣言すると、その依存関係の使用が開発モードに制限されます。 quarkusDev
の設定は以下のように使用できます。
リモート開発モード
開発モードをリモートで使用することができるので、コンテナー環境(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をビルドするのと同じ方法でビルドできます。つまり、次を実行します。
quarkus build
./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
これでブラウザを更新するたびに、ローカルで行った変更がリモートアプリにすぐに表示されるようになりました。
すべての設定項目を以下に示します。
ビルド時に固定される設定プロパティ - その他の設定プロパティはランタイムでオーバーライド可能です。
型 |
デフォルト |
|
---|---|---|
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: |
boolean |
|
The names of additional resource files to watch for changes, triggering a reload on change. Directories are not supported. Environment variable: |
list of string |
|
Password used to use to connect to the remote dev-mode application Environment variable: |
string |
|
URL used to use to connect to the remote dev-mode application Environment variable: |
string |
|
The amount of time to wait for a remote dev connect or reconnect Environment variable: |
|
|
The amount of time to wait between attempts when connecting to the server side of remote dev Environment variable: |
|
|
The maximum number of attempts when connecting to the server side of remote dev Environment variable: |
int |
|
期間フォーマットについて
期間のフォーマットは標準の 数値で始まる期間の値を指定することもできます。この場合、値が数値のみで構成されている場合、コンバーターは値を秒として扱います。そうでない場合は、 |
デバッグ
開発モードでは、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アプリケーションを実行することもできます。 コマンドラインインタフェース
Gradle
次に、デバッガーを |
IDEへのインポート
プロジェクトを生成 したら、お気に入りのIDEでインポートすることができます。唯一の条件は、Gradleプロジェクトをインポートできることです。
Eclipse
Eclipse で、 File → Import
をクリックします。ウィザードで、 Gradle → Existing Gradle Project
を選択します。次の画面で、プロジェクトのルートの場所を選択します。次の画面では、見つかったモジュールのリストが表示されるので、生成されたプロジェクトを選択して Finish
をクリックします。
別のターミナルで、次を実行します:
quarkus dev
./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
./gradlew --console=plain quarkusDev
お楽しみください!
Apache NetBeans
NetBeansの場合:
-
File → Open Project
を選択 -
プロジェクトのルートを選択します。
-
Open Project
をクリックしてください。
別のターミナルまたは組込ターミナルで、プロジェクトのルートに移動して次を実行します:
quarkus dev
./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アプリケーションはコンテナーやサーバーレスのワークロードに最適です。
Make sure to have GRAALVM_HOME
configured and pointing to the latest release of GraalVM version 22.3 (Make sure to use a Java 11 version of GraalVM).
ネイティブ実行可能ファイルの作成:
quarkus build --native
./gradlew build -Dquarkus.package.type=native
ネイティブ実行可能ファイルは、 build/
に存在します。
ネイティブ関連のプロパティーは、 application.properties
ファイルにコマンドライン引数として追加するか、 quarkusBuild
タスクに追加することができます。 quarkusBuild
タスクの設定は以下のように行います:
Gradle Groovy DSL を使用する場合、プロパティーキーは小文字のキャメルケース表記に従わなければなりません。例: |
コンテナーフレンドリーな実行ファイルをビルドする
ネイティブ実行可能ファイルは、お使いのオペレーティングシステムに固有のものになります。コンテナー内で実行される実行ファイルを作成するには、次のようにします。
quarkus build --native --no-tests -Dquarkus.native.container-build=true
# The --no-tests flag is required only on Windows and macOS.
./gradlew build -Dquarkus.package.type=native -Dquarkus.native.container-build=true
生成される実行ファイルは64bitのLinux実行ファイルになるので、OSによっては実行できなくなる可能性があります。しかし、Dockerコンテナーにコピーするので問題ありません。この場合、ビルド自体もDockerコンテナー内で動作するので、ローカルにGraalVMをインストールする必要はないことに注目してください。
By default, the native executable will be generated using the 異なるDockerイメージでネイティブ実行可能ファイルをビルドしたい場合(例えば、異なるGraalVMのバージョンを使用するなど)、 The list of the available Docker images can be found on quay.io. Be aware that a given Quarkus version might not be compatible with all the images available. |
ネイティブテストの実行
次のようにネイティブテストを実行します:
./gradlew testNative
このタスクは quarkusBuild
に依存しているので、テストを実行する前にネイティブイメージを生成します。
デフォルトでは、 |
結合テストの実行
( @QuarkusIntegrationTest
でアノテーションされた)Quarkus結合テストは、Quarkusが生成したアーティファクトで実行されます。これらのテストは、 src/integrationTest/java
ディレクトリに配置し、それを使用して実行することができます。
./gradlew quarkusIntTest
This task depends on both test
and quarkusBuild
tasks. The final artifact will be produced before running tests.
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
./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 セクションを参照してください。