初めてのアプリケーションの作成
Hello World Quarkus アプリの作成方法を説明します。 このガイドでは、以下の内容を説明します。
-
アプリケーション開発の開始
-
Jakarta RESTのエンドポイントの作成
-
Bean の注入
-
機能テスト
-
アプリケーションのパッケージ化
1. 前提条件
このガイドを完成させるには、以下が必要です:
-
約15分
-
IDE
-
JDK 17+がインストールされ、
JAVA_HOME
が適切に設定されていること -
Apache Maven 3.9.8
-
使用したい場合は、 Quarkus CLI
Maven が意図した Java を使用していることの確認
複数の JDK がインストールされている場合、 Maven が意図した java を利用するとは限らず、予期しない結果になる可能性があります。 Maven がどの JDK を使用するかは、 |
2. アーキテクチャ
このガイドでは、hello
エンドポイントを提供する簡単なアプリケーションを作成します。依存性の注入を示すために、このエンドポイントでは greeting
Bean を使用します。
このガイドでは、エンドポイントのテストについても解説します。
3. ソリューション
プロジェクトのブートストラップ 以降の指示に従って、ステップバイステップでアプリケーションを作成することをお勧めします。
ただし、アプリケーションの完成例にそのまま進んでも構いません。
Git レポジトリをクローンするか、 アーカイブ をダウンロードします:
git clone https://github.com/quarkusio/quarkus-quickstarts.git
ソリューションは getting-started
ディレクトリ にあります。
4. プロジェクトの開始
新しい Quarkus プロジェクトを作成する最も簡単な方法は、ターミナルを開いて以下のコマンドを実行することです。
Windowsユーザーの場合:
-
cmdを使用する場合、(バックスラッシュ
\
を使用せず、すべてを同じ行に書かないでください)。 -
Powershellを使用する場合は、
-D
パラメータを二重引用符で囲んでください。例:"-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
が存在することが分かります。
<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-rest</artifactId>
</dependency>
implementation("io.quarkus:quarkus-rest")
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 Quarkus REST";
}
}
これは非常にシンプルなRESTエンドポイントで、"/hello "へのリクエストに対して "Hello from Quarkus 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, rest]
アプリケーションが起動したら、提供されたエンドポイントにリクエストを送信することができます。
$ curl -w "\n" http://localhost:8080/hello
Hello from Quarkus REST
CTRL+C
を押してアプリケーションを停止することも、アプリケーションを起動したまま高速なホットリロードを行うことも可能です。
curl -w "\n" で自動的に改行が追加されるようにします。この例では |
6. 依存性注入の使用
Quarkus の依存性注入は、Quarkus のアーキテクチャに合わせて調整された CDI ベースの依存性注入ソリューションである ArC をベースにしています。 CDI が初めての方は、 CDI入門 ガイドをお読みになることをお勧めします。
Quarkus は CDI 機能のサブセットのみを実装しており、非標準の機能や特定の API が付属しています。詳細は、 コンテキストと依存性注入ガイド を参照してください。
ArC は quarkus-rest
の依存関係として提供されているので、既に手元にあります。
アプリケーションを変更してコンパニオン 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 Quarkus REST";
}
}
アプリケーションを停止しなくても、ライブリロード機能によって変更が自動的にデプロイされますが、アプリケーションを停止した場合は、次のようにアプリケーションを再起動します。
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 Quarkus REST"));
}
@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 heavily utilizes Jandex at build time, to discover various classes or annotations. One immediately recognizable application of this, is CDI bean discovery. As a result, most of the Quarkus extensions will not work properly if this build time discovery isn’t properly setup.
このインデックスは、 Maven と Gradle プラグインにより、 Quarkus が設定されているプロジェクトにデフォルトで作成されます。
外部モジュール (例えば、すべてのドメインオブジェクトのための外部ライブラリ) を使用する予定がある場合は、Jandex プラグインを追加するか (変更できる場合)、 application.properties
内の quarkus.index-dependency
プロパティーを使って (モジュールを変更できない場合に便利です)、これらのモジュールをインデックス作成プロセスに知らせておく必要があります。
詳細は、CDI ガイドの Bean の検出 セクションを必ずお読みください。
10. パッケージ化とアプリケーションの実行
このアプリケーションは、以下の方法でパッケージ化されています。
quarkus build
./mvnw install
./gradlew build
これは /target
にいくつかの出力ファイルを生成します。
-
getting-started-1.0.0-SNAPSHOT.jar
: プロジェクトのクラスとリソースだけを含み、Maven ビルドによって生成される通常のアーティファクトです。 -
getting-started-1.0.0-SNAPSHOT-runner.jar
: 実行可能な jar です。依存関係がtarget/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バージョン、バージョン管理、オペレーティングシステムに関する情報を提供します。公開される情報の詳細レベルは、設定可能です。
All CDI beans implementing the InfoContributor
will be picked up and their data will be appended to the endpoint.
12.1.1. 設定リファレンス
ビルド時に固定される構成プロパティ - 他のすべての構成プロパティは実行時にオーバーライド可能
Configuration property |
タイプ |
デフォルト |
---|---|---|
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 |
ブーリアン |
|
Additional properties to be added to the build section Environment variable: Show more |
Map<String,String> |
|
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 |
ブーリアン |
|
13. 次のステップ
This guide covered the creation of an application using Quarkus. However, there is much more. We recommend continuing the journey by creating your second Quarkus application, with Dev Services and persistence. You can learn about creating a native executable and packaging it in a container with the building a native executable guide. If you are interested in reactive, we recommend the getting started with reactive guide, where you can see how to implement reactive applications with Quarkus.
また、ツールガイド のドキュメントでは、以下について説明しています。
-
単一のコマンドラインでプロジェクトの雛形を生成する方法
-
development mode (ホットリロード) を有効にする方法
-
よく利用する IDE でプロジェクトをインポートする
-
その他