初めてのアプリケーションの作成
Hello World Quarkus アプリケーションの作成方法を説明します。 このガイドでは、以下の内容を取り扱います。
-
アプリケーション開発の開始
-
Jakarta RESTのエンドポイントの作成
-
Bean の注入
-
機能テスト
-
アプリケーションのパッケージ化
1. 前提条件
このガイドを完成させるには、以下が必要です:
-
約15分
-
IDE
-
JDK 11+ がインストールされ、
JAVA_HOME
が適切に設定されていること -
Apache Maven 3.9.3
-
使用したい場合は、 Quarkus CLI
Maven が意図した Java を使用していることの確認
複数の JDK がインストールされている場合、 Maven が意図した java を利用するとは限らず、予期しない結果になる可能性があります。 Maven がどの JDK を使用するかは、 |
2. アーキテクチャ
このガイドでは、hello
エンドポイントを提供する簡単なアプリケーションを作成します。依存性の注入の動作を示すために、このエンドポイントでは greeting
Bean を使用します。

このガイドでは、エンドポイントのテストについても解説します。
3. ソリューション
プロジェクトのブートストラップ 以降の指示に従って、ステップバイステップでアプリケーションを作成することをお勧めします。
ただし、アプリケーションの完成例にそのまま進んでも構いません。
Git レポジトリをクローンするか、 アーカイブ をダウンロードします:
git clone https://github.com/quarkusio/quarkus-quickstarts.git
The solution is located in the getting-started
directory.
4. プロジェクトの開始
新しい Quarkus プロジェクトを作成する最も簡単な方法は、ターミナルを開いて以下のコマンドを実行することです。
Windowsユーザーの場合:
-
If using cmd, (don’t use backward slash
\
and put everything on the same line) -
If using Powershell, wrap
-D
parameters in double quotes e.g."-DprojectArtifactId=getting-started"
./getting-started
に以下の内容が生成されます。
-
Maven の構造
-
/hello
で公開されるorg.acme.getting.start.GreetingResource
リソース -
関連するユニットテスト
-
アプリケーション起動後に
http://localhost:8080
でアクセス可能な Web ページ -
src/main/docker
に配置されるnative
とjvm
の両方のモード用のDockerfile
ファイルの例 -
アプリケーションの設定ファイル
生成されたら、pom.xml
を確認します。 Quarkus の BOM がインポートされており、 これによって Quarkus の依存関係のバージョンを省略することができます。 また、アプリケーションのパッケージ化を行う quarkus-maven-plugin
と、開発モードを提供する quarkus-maven-plugin
も存在することが確認できます。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>${quarkus.platform.artifact-id}</artifactId>
<version>${quarkus.platform.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>${quarkus.platform.group-id}</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.platform.version}</version>
<extensions>true</extensions>
<executions>
<execution>
<goals>
<goal>build</goal>
<goal>generate-code</goal>
<goal>generate-code-tests</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Gradleプロジェクトでも、同様の設定があります。
-
Quarkus Gradle プラグイン
-
Quarkus BOM 用の
enforcedPlatform
ディレクティブ
依存関係の部分に注目すると、REST アプリケーションの開発を可能にするエクステンションがあることがわかります。
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-resteasy-reactive</artifactId>
</dependency>
implementation("io.quarkus:quarkus-resteasy-reactive")
4.1. Jakarta RESTリソース
プロジェクト作成時には、以下の内容で src/main/java/org/acme/getting/started/GreetingResource.java
ファイルが作成されます。
package org.acme;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
@Path("/hello")
public class GreetingResource {
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
return "Hello from RESTEasy Reactive";
}
}
これは "/hello" へのリクエストに対して "Hello RESTEasy" と返す、非常にシンプルな REST エンドポイントです。
素のJakarta RESTとの差異
Quarkus では、 |
5. アプリケーションの実行
ここまでで、アプリケーションを実行する準備が整いました。
quarkus dev
./mvnw quarkus:dev
./gradlew --console=plain quarkusDev
[INFO] --------------------< org.acme:getting-started >---------------------
[INFO] Building getting-started 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ getting-started ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] skip non existing resourceDirectory <path>/getting-started/src/main/resources
[INFO]
[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ getting-started ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 2 source files to <path>/getting-started/target/classes
[INFO]
[INFO] --- quarkus-maven-plugin:<version>:dev (default-cli) @ getting-started ---
Listening for transport dt_socket at address: 5005
2019-02-28 17:05:22,347 INFO [io.qua.dep.QuarkusAugmentor] (main) Beginning quarkus augmentation
2019-02-28 17:05:22,635 INFO [io.qua.dep.QuarkusAugmentor] (main) Quarkus augmentation completed in 288ms
2019-02-28 17:05:22,770 INFO [io.quarkus] (main) Quarkus started in 0.668s. Listening on: http://localhost:8080
2019-02-28 17:05:22,771 INFO [io.quarkus] (main) Installed features: [cdi, resteasy-reactive]
アプリケーションが起動したら、提供されたエンドポイントにリクエストを送信することができます。
$ curl -w "\n" http://localhost:8080/hello
Hello from RESTEasy Reactive
CTRL+C
を押してアプリケーションを停止することも、アプリケーションを起動したまま高速なホットリロードを行うことも可能です。
curl -w "\n" で自動的に改行が追加されるようにします。この例では |
6. 依存性注入の使用
Quarkus の依存性注入は、Quarkus のアーキテクチャに合わせて調整された CDI ベースの依存性注入ソリューションである ArC をベースにしています。 CDI に馴染みのない方は、CDI入門 ガイドをお読みになることを推奨します。
Quarkus は CDI 機能のサブセットのみを実装しており、非標準の機能や特定の API が付属しています。詳細は、 コンテキストと依存性注入ガイド を参照してください。
ArC は quarkus-resteasy
の依存関係として提供されるため、新たに追加する必要はありません。
アプリケーションを修正してコンパニオンクラスの Bean を追加してみます。以下の内容で src/main/java/org/acme/getting/started/GreetingService.java
ファイルを作成します。
package org.acme;
import jakarta.enterprise.context.ApplicationScoped;
@ApplicationScoped
public class GreetingService {
public String greeting(String name) {
return "hello " + name;
}
}
GreetingResource
クラスを編集して GreetingService
を注入し、それを使用して新しいエンドポイントを作成します。
package org.acme;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
@Path("/hello")
public class GreetingResource {
@Inject
GreetingService service;
@GET
@Produces(MediaType.TEXT_PLAIN)
@Path("/greeting/{name}")
public String greeting(String name) {
return service.greeting(name);
}
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
return "Hello from RESTEasy Reactive";
}
}
アプリケーションを停止しなくても、ライブリロード機能によって変更が自動的にデプロイされますが、アプリケーションを停止した場合は、次のようにアプリケーションを再起動します。
quarkus dev
./mvnw quarkus:dev
./gradlew --console=plain quarkusDev
その後、エンドポイントが期待通りに hello quarkus
を返すことを確認します。
$ curl -w "\n" http://localhost:8080/hello/greeting/quarkus
hello quarkus
7. 開発モード
quarkus:dev
は、開発モードで Quarkus を実行します。これにより、 Java ファイルやリソースファイルを変更してブラウザを更新すると、これらの変更が自動的に反映されます。 これは、設定プロパティーファイルなどのリソースファイルに対しても機能します。 ブラウザをリフレッシュすると、ワークスペースのスキャンがトリガーされ、変更が検出された場合、 Java ファイルが再コンパイルされ、アプリケーションが再デプロイされます。リクエストは、再デプロイされたアプリケーションによって処理されます。コンパイルやデプロイに問題がある場合は、エラーページで通知します。
また、これによってデバッガーがポート 5005
で待ち受けを始めます。デバッガーがアタッチされるのを待ってから実行する場合は、コマンドラインで -Dsuspend
を渡してください。デバッガーを全く必要としない場合は -Ddebug=false
を使います。
8. テスト
ここまでは問題ありませんが、念のためにテストを行います。
生成されたビルドファイルには、2つのテストの依存関係が示されています。
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-junit5</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.rest-assured</groupId>
<artifactId>rest-assured</artifactId>
<scope>test</scope>
</dependency>
testImplementation("io.quarkus:quarkus-junit5")
testImplementation("io.rest-assured:rest-assured")
Quarkus は Junit 5 テストをサポートしています。
Maven の場合、デフォルトでは JUnit 5 に対応していないため、 Surefire Maven Plugin のバージョンを設定する必要があります。
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>${surefire-plugin.version}</version>
<configuration>
<systemPropertyVariables>
<java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
<maven.home>${maven.home}</maven.home>
</systemPropertyVariables>
</configuration>
</plugin>
また、 java.util.logging
システムプロパティーを設定して、テストが正しいログマネージャーを使用することを確認し、 maven.home
からカスタム設定が適用されることを確認します (存在する場合)。
生成されたプロジェクトには簡単なテストが含まれています。以下の内容に合わせて src/test/java/org/acme/getting/started/GreetingResourceTest.java
を編集します。
package org.acme;
import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;
import java.util.UUID;
import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;
@QuarkusTest
public class GreetingResourceTest {
@Test (1)
public void testHelloEndpoint() {
given()
.when().get("/hello")
.then()
.statusCode(200) (2)
.body(is("Hello from RESTEasy Reactive"));
}
@Test
public void testGreetingEndpoint() {
String uuid = UUID.randomUUID().toString();
given()
.pathParam("name", uuid)
.when().get("/hello/greeting/{name}")
.then()
.statusCode(200)
.body(is("hello " + uuid));
}
}
1 | QuarkusTest ランナーを使用し、テストの前にアプリケーションを起動するように JUnit に指示します。 |
2 | HTTP レスポンスのステータスコードと内容を確認します。 |
これらのテストでは RestAssured を使用していますが、普段利用しているライブラリーを自由に使用することも可能です。
これらは Maven を使って実行することができます。
./mvnw test
また、IDE から直接テストを実行することもできます (最初にアプリケーションを停止したことを確認してください)。
デフォルトでは、実行中のアプリケーションと競合しないように、テストはポート 8081
で実行されます。 RestAssured は、この 8081 ポートを使用するように自動的にを設定されます。別のクライアントを使用したい場合は、@TestHTTPResource
アノテーションを使用して、テストされたアプリケーションの URL をテストクラスのフィールドに直接注入する必要があります。このフィールドは String
、 URL
、 URI
のいずれかの型になります。このアノテーションにはテストパスの値を指定することもできます。例えば、/myservlet
にマップされたサーブレットをテストしたい場合、次のようにテストに追加します。
@TestHTTPResource("/myservlet")
URL testUrl;
テストポートは、 quarkus.http.test-port
設定プロパティーで制御できます。 Quarkus はまた、依存性注入を使用できない場合のためにベースとなるテスト URL に設定される test.url
システムプロパティーを作成します。
9. マルチモジュールプロジェクトや外部モジュールとの連携
Quarkus はビルド時に Jandex を多用して、さまざまなクラスやアノテーションを検出しています。このことがすぐに認識できるアプリケーションの1つは、 CDI Bean のディスカバリーです。 結果、このビルド時のディスカバリーが適切に設定されていないと、Quarkus のエクステンションのほとんどが正しく動作しません。
このインデックスは、 Maven と Gradle プラグインにより、 Quarkus が設定されているプロジェクトにデフォルトで作成されます。
外部モジュール (例えば、すべてのドメインオブジェクトのための外部ライブラリ) を使用する予定がある場合は、 Jandex プラグインを追加するか (変更できる場合)、 application.properties
内の quarkus.index-dependency
プロパティーを使って (モジュールを変更できない場合に有用) 、これらのモジュールをインデックス作成プロセスに知らせておく必要があります。
詳細は、CDI ガイドの Bean の検出 セクションを必ずお読みください。
10. パッケージ化とアプリケーションの実行
このアプリケーションは、以下の方法でパッケージ化されています。
quarkus build
./mvnw install
./gradlew build
これは /target
にいくつかの出力ファイルを生成します。
-
プロジェクトのクラスとリソースだけを含み、 Maven ビルドによって生成される通常のアーティファクトである
getting-started-1.0.0-SNAPSHOT.jar
。これは、実行可能な jar ではありません。 -
実行可能 jar である
quarkus-run.jar
jar ファイルを含むquarkus-app
ディレクトリ。依存関係はquarkus-app/lib/
のサブディレクトリにコピーされるため über-jar ではないことに注意してください。
java -jar target/getting-started-1.0.0-SNAPSHOT-runner.jar
でアプリケーションを実行することができます。
アプリケーションをどこかに ( 典型的にはコンテナーに ) デプロイしたい場合は、 quarkus-app ディレクトリ全体をデプロイする必要があります。
|
アプリケーションを実行する前に、 CTRL+C でホットリロードモードを停止することを忘れないでください 。停止しないと、ポートが衝突します。
|
11. バナーの設定
デフォルトでは、通常モードまたは開発モードで Quarkus アプリケーションが起動すると、 ASCII アートバナーが表示されます。バナーを無効にするには、 application.properties
で quarkus.banner.enabled=false
を設定するか、 Dquarkus.banner.enabled=false
の Java システムプロパティーを設定する、 あるいは QUARKUS_BANNER_ENABLED
環境変数を false
に設定します。 さらに、 src/main/resources
にバナーファイルを配置し、 application.properties
に quarkus.banner.path=nam-of-file
を設定することで、ユーザーはカスタムのバナーを提供することができます。
12. 非アプリケーションエンドポイント
さまざまなQuarkusエクステンションが、アプリケーションに関するさまざまな情報を提供する非アプリケーションエンドポイントを提供しています。そのようなエクステンションの例として、 health 、 metrics 、 OpenAPI 、infoエクステンションがあります。
これらの非アプリケーションエンドポイントは、通常、 /q
のプレフィックスで次のようにアクセスします:
-
/q/health
-
/q/metrics
-
/q/openapi
-
/q/info
しかし、ユーザーは、セキュリティリスクをもたらす可能性のあるものを、専用の 管理インターフェイス を使用して、別のTCPポートで公開することを選択することもできます。
12.1. Info endpoint
アプリケーションに quarkus-info
のエクステンションが含まれている場合、Quarkusはデフォルトで /q/info
のエンドポイントを公開し、ビルド、Javaバージョン、バージョン管理、オペレーティングシステムに関する情報を提供します。公開される情報の詳細レベルは、設定可能です。
12.1.1. 設定リファレンス
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
タイプ |
デフォルト |
|
---|---|---|
Whether the info endpoint will be enabled Environment variable: Show more |
ブーリアン |
|
The path under which the info endpoint will be located Environment variable: Show more |
string |
|
Whether git info will be included in the info endpoint Environment variable: Show more |
ブーリアン |
|
Controls how much information is present in the git section Environment variable: Show more |
|
|
Whether build info will be included in the info endpoint Environment variable: Show more |
ブーリアン |
|
Whether os info will be included in the info endpoint Environment variable: Show more |
ブーリアン |
|
Whether java info will be included in the info endpoint Environment variable: Show more |
ブーリアン |
|
Additional properties to be added to the build section Environment variable: Show more |
|
13. 次のステップ
このガイドでは、Quarkus を使用したアプリケーションの作成について説明しました。 しかし、まだまだ多くのことがあります。 ネイティブ実行可能ファイルのビルド で、ネイティブ実行可能ファイルの作成とコンテナーへのパッケージ化について学習することを推奨します。 リアクティブに興味がある場合は、リアクティブアプリケーションを Quarkus で実装する方法を解説した リアクティブ入門ガイド をお勧めします。
また、ツールガイド のドキュメントでは、以下について説明しています。
-
単一のコマンドラインでプロジェクトの雛形を生成する方法
-
development mode (ホットリロード) を有効にする方法
-
よく利用する IDE でプロジェクトをインポートする
-
その他