Red Hat ビルドの Quarkus のスタートガイド
前書き
アプリケーション開発者は、Red Hat ビルドの Quarkus を使用して、サーバーレス環境および OpenShift 環境で実行される Java で書かれたマイクロサービスベースのアプリケーションを作成できます。これらのアプリケーションのメモリーフットプリントは小さくなり、起動時間は高速化されます。
本ガイドでは、Apache Maven を使用して hello HTTP エンドポイントを公開する簡単な Quarkus プロジェクトを作成、テスト、パッケージ化、および実行する方法を説明します。ディペンデンシーインジェクション (依存性の注入) を実証するために、このエンドポイントは greeting Bean を使用します。

前提条件
-
OpenJDK (JDK) 11 がインストールされ、
JAVA_HOME環境変数が Java SDK の場所を指定していること。Red Hat ビルドの Open JDK は、Red Hat カスタマーポータルの Software Downloads ページから入手可能です (ログインが必要です)。 - Apache Maven 3.6.2 以降がインストールされていること。Maven は Apache Maven Project の Web サイトから入手できます。
Getting Started の演習の完全なサンプルについては、Quarkus quickstart archive をダウンロードするか、Quarkus Quickstarts Git リポジトリーをクローンしてください。この例は getting-started ディレクトリーにあります。
第1章 Red Hat ビルドの Quarkus
Red Hat ビルドの Quarkus は、コンテナーおよび Red Hat OpenShift Container Platform と使用するために最適化された Kubernetes ネイティブ Java スタックです。Quarkus は、Eclipse MicroProfile、Apache Kafka、RESTEasy (JAX-RS)、Hibernate ORM (JPA)、Spring、Infinispan、Apache Camel などの一般的な Java 標準、フレームワーク、およびライブラリーと連携するように設計されています。
Quarkus のディペンデンシーインジェクション (依存性の注入) ソリューションは、CDI (コンテキストとディペンデンシーインジェクション) をベースとし、エクステンションフレームワークを備えているので、機能の拡張、およびフレームワークの設定、起動、アプリケーションへの統合が可能です。
Quarkus は、コンテナーファーストという手法で Java アプリケーションをビルドします。この手法により、Java で書かれたマイクロサービスベースのアプリケーションのビルドが大幅に容易になるほか、これらのアプリケーションがサーバーレスコンピューティングフレームワークで実行している関数を呼び出すことができるようになります。これにより、Quarkus アプリケーションのメモリーフットプリントは小さくなり、起動時間は高速化されます。
第2章 Apache Maven および Quarkus
Apache Maven は、ソフトウェアプロジェクトの作成、管理、ビルドを行う Java アプリケーションの開発で使用される分散型ビルド自動化ツールです。Maven は Project Object Model (POM) ファイルと呼ばれる標準の設定ファイルを使用して、プロジェクトの定義やビルドプロセスの管理を行います。POM ファイルは、モジュールおよびコンポーネントの依存関係、ビルドの順番、結果となるプロジェクトパッケージングのターゲットを定義し、XML ファイルを使用して出力します。この結果、プロジェクトが適切かつ統一された状態でビルドされるようになります。
Maven リポジトリー
Maven リポジトリーには、Java ライブラリー、プラグイン、その他のビルドアーティファクトが格納されています。デフォルトのパブリックリポジトリーは Maven 2 Central Repository ですが、複数の開発チームの間で共通のアーティファクトを共有する目的で、社内のプライベートおよび内部リポジトリーを使用することができます。また、サードパーティーのリポジトリーも利用できます。
Quarkus プロジェクトでオンライン Maven リポジトリーを使用するか、または Red Hat ビルドの Quarkus の Maven リポジトリーをダウンロードすることができます。
Maven プラグイン
Maven プラグインは、1 つ以上のゴールを達成する POM ファイルの定義された部分です。Quarkus アプリケーションは以下の Maven プラグインを使用します。
-
Quarkus Maven プラグイン (
quarkus-maven-plugin): Maven による Quarkus プロジェクトの作成を実現、uber-JAR ファイルの生成をサポート、そして開発モードを提供します。 -
Maven Surefire プラグイン (
maven-surefire-plugin): ビルドライフサイクルのテストフェーズで使用され、アプリケーションでユニットテストを実行します。プラグインは、テストレポートが含まれるテキストファイルと XML ファイルを生成します。
2.1. オンラインリポジトリーの Maven の settings.xml ファイルの設定
ユーザーの settings.xml ファイルを設定して、オンライン Quarkus リポジトリーを Quarkus Maven プロジェクトで使用することができます。これは推奨される手法です。リポジトリーマネージャーまたは共有サーバー上のリポジトリーと使用する Maven 設定は、プロジェクトの制御および管理を行いやすくします。
Maven の settings.xml ファイルを変更してリポジトリーを設定する場合、変更はすべての Maven プロジェクトに適用されます。
手順
テキストエディターまたは統合開発環境 (IDE) で、Maven の
~/.m2/settings.xmlファイルを開きます。注記~/.m2/ディレクトリーにsettings.xmlファイルがない場合は、$MAVEN_HOME/.m2/conf/ディレクトリーのsettings.xmlファイルを~/.m2/ディレクトリーにコピーします。以下の行を
settings.xmlファイルの<profiles>要素に追加します。<!-- Configure the Quarkus Maven repository --> <profile> <id>red-hat-enterprise-maven-repository</id> <repositories> <repository> <id>red-hat-enterprise-maven-repository</id> <url>https://maven.repository.redhat.com/ga/</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>red-hat-enterprise-maven-repository</id> <url>https://maven.repository.redhat.com/ga/</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories> </profile>以下の行を
settings.xmlファイルの<activeProfiles>要素に追加して、ファイルを保存します。<activeProfile>red-hat-enterprise-maven-repository</activeProfile>
2.2. Quarkus Maven リポジトリーのダウンロードおよび設定
オンライン Maven リポジトリーを使用しない場合は、Quarkus Maven リポジトリーをダウンロードして設定し、Maven を使用して Quarkus アプリケーションを作成できます。Quarkus Maven リポジトリーには、Java 開発者がアプリケーションのビルドに使用する必要があるものが数多く含まれています。この手順では、settings.xml ファイルを編集して Quarkus Maven リポジトリーを設定する方法を説明します。
Maven の settings.xml ファイルを変更してリポジトリーを設定する場合、変更はすべての Maven プロジェクトに適用されます。
手順
- Red Hat カスタマーポータルの Software Downloads ページから、Quarkus Maven リポジトリーの ZIP ファイルをダウンロードします (ログインが必要です)。
- ダウンロードしたアーカイブを展開します。
-
~/.m2/ディレクトリーに移動し、テキストエディターまたは統合開発環境 (IDE) で Maven のsettings.xmlファイルを開きます。 以下の行を
settings.xmlファイルの<profiles>要素に追加します。ここで、QUARKUS_MAVEN_REPOSITORYはダウンロードした Quarkus Maven リポジトリーのパスになります。QUARKUS_MAVEN_REPOSITORYの形式は、file://$PATHでなければなりません (例:file:///home/userX/rh-quarkus-1.3.4.SP1-maven-repository/maven-repository)。<!-- Configure the Quarkus Maven repository --> <profile> <id>red-hat-enterprise-maven-repository</id> <repositories> <repository> <id>red-hat-enterprise-maven-repository</id> <url>QUARKUS_MAVEN_REPOSITORY</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>red-hat-enterprise-maven-repository</id> <url>QUARKUS_MAVEN_REPOSITORY</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories> </profile>以下の行を
settings.xmlファイルの<activeProfiles>要素に追加して、ファイルを保存します。<activeProfile>red-hat-enterprise-maven-repository</activeProfile>
Maven リポジトリーに古いアーティファクトが含まれる場合は、プロジェクトをビルドまたはデプロイしたときに以下のいずれかの Maven エラーメッセージが表示されることがあります。ここで、ARTIFACT_NAME は不明なアーティファクトの名前、PROJECT_NAME はビルドを試みているプロジェクトの名前になります。
-
Missing artifact PROJECT_NAME -
[ERROR] Failed to execute goal on project ARTIFACT_NAME; Could not resolve dependencies for PROJECT_NAME
この問題を解決するには、~/.m2/repository ディレクトリーにあるローカルリポジトリーのキャッシュバージョンを削除し、最新の Maven アーティファクトを強制的にダウンロードします。
第3章 Getting Started プロジェクトの作成
getting-started プロジェクトでは、Apache Maven および Quarkus Maven プラグインを使用して、簡単な Quarkus アプリケーションを使い始めることができます。
手順
コマンドターミナルで以下のコマンドを入力し、Maven が JDK 11 を使用していること、そして Maven のバージョンが 3.6.2 以上であることを確認します。
mvn --version
- 上記のコマンドで JDK 11 が返されない場合は、JDK 11 へのパスを PATH 環境変数に追加し、上記のコマンドを再度入力します。
プロジェクトを生成するには、以下のコマンドのいずれかを入力します。
注記Apple macOS および Microsoft Windows は、本番環境ではサポートされません。
Linux または Apple macOS を使用している場合は、以下のコマンドを入力します。
mvn io.quarkus:quarkus-maven-plugin:1.3.4.Final-redhat-00004:create \ -DprojectGroupId=org.acme \ -DprojectArtifactId=getting-started \ -DplatformGroupId=com.redhat.quarkus \ -DplatformVersion=1.3.4.Final-redhat-00004 \ -DclassName="org.acme.quickstart.GreetingResource" \ -Dpath="/hello" cd getting-startedMicrosoft Windows のコマンドラインを使用している場合は、以下のコマンドを入力します。
mvn io.quarkus:quarkus-maven-plugin:1.3.4.Final-redhat-00004:create -DprojectGroupId=org.acme -DprojectArtifactId=getting-started -DplatformGroupId=com.redhat.quarkus -DplatformVersion=1.3.4.Final-redhat-00004 -DclassName="org.acme.quickstart.GreetingResource" -Dpath="/hello"
Microsoft Windows Powershell を使用している場合は、以下のコマンドを入力します。
mvn io.quarkus:quarkus-maven-plugin:1.3.4.Final-redhat-00004:create "-DprojectGroupId=org.acme" "-DprojectArtifactId=getting-started" "-DplatformGroupId=com.redhat.quarkus" "-DclassName=org.acme.quickstart.GreetingResource" "-Dpath=/hello"
これらのコマンドにより、
./getting-startedディレクトリーに以下の要素が作成されます。- Maven の構造
-
/helloで公開されるorg.acme.quickstart.GreetingResourceリソース - 関連するユニットテスト
-
アプリケーションの起動後に
http://localhost:8080でアクセス可能なランディングページ -
src/main/dockerのDockerfileファイルの例 - アプリケーション設定ファイル
ディレクトリー構造が作成されたら、テキストエディターで
pom.xmlファイルを開き、ファイルの内容を確認します。<dependencyManagement> <dependencies> <dependency> <groupId>com.redhat.quarkus</groupId> <artifactId>quarkus-universe-bom</artifactId> <version>${quarkus-plugin.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <build> <plugins> <plugin> <groupId>io.quarkus</groupId> <artifactId>quarkus-maven-plugin</artifactId> <version>${quarkus-plugin.version}</version> <executions> <execution> <goals> <goal>build</goal> </goals> </execution> </executions> </plugin> <plugin> <artifactId>maven-compiler-plugin</artifactId> <version>${compiler-plugin.version}</version> </plugin> <plugin> <artifactId>maven-surefire-plugin</artifactId> <version>${surefire-plugin.version}</version> <configuration> <systemProperties> <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager> </systemProperties> </configuration> </plugin> </plugins> </build>Quarkus BOM は
pom.xmlファイルにインポートされます。そのため、pom.xmlファイルに個別の Quarkus 依存関係のバージョンを記述する必要はありません。さらに、アプリケーションをパッケージ化し、開発モードを提供するquarkus-maven-pluginプラグインがあることを確認できます。pom.xmlファイルで、quarkus-resteasyの依存関係を確認します。この依存関係により、REST アプリケーションを開発できます。<dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-resteasy</artifactId> </dependency>src/main/java/org/acme/quickstart/GreetingResource.javaファイルを確認します。package org.acme.quickstart; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; import javax.ws.rs.core.MediaType; @Path("/hello") public class GreetingResource { @GET @Produces(MediaType.TEXT_PLAIN) public String hello() { return "hello"; } }このファイルには、Java API for RESTful Web Services (JAX-RS) のほか、
/helloへの要求に対してhelloを返す非常に簡単な REST エンドポイントが含まれます。注記Quarkus では、JAX-RS の
Applicationクラスはサポートされますが、必須ではありません。さらに、リクエストごとに 1 つのインスタンスが作成されるのではなく、GreetingResourceクラスのインスタンスが 1 つだけ作成されます。このインスタンスは、別の*Scopedアノテーションを使用して設定できます。たとえば、ApplicationScoped、RequestScopedなどを使用できます。
第4章 Quarkus Getting Started プロジェクトのコンパイル
Quarkus Getting Started プロジェクトを作成したら、Hello アプリケーションをコンパイルし、=hello エンドポイントが hello を返すことを確認できます。
この例では、Quarkus の組み込み開発モードを使用しています。開発モードでは、アプリケーションの実行中にアプリケーションソースおよび設定を更新できます。変更が実行中のアプリケーションに反映されます。
前提条件
- Quarkus Getting Started プロジェクトを作成していること。
手順
開発モードで Quarkus Hello アプリケーションをコンパイルするには、プロジェクトディレクトリーから以下のコマンドを入力します。
./mvnw compile quarkus:dev
以下の例は、このコマンドの出力を示しています。
2020-04-02 10:53:44,263 INFO [io.quarkus] (main) getting-started 1.0-SNAPSHOT (powered by Quarkus 1.3.4.Final-redhat-00004) started in 0.946s. Listening on: http://0.0.0.0:8080 2020-04-02 10:53:44,267 INFO [io.quarkus] (main) Profile dev activated. Live Coding activated. 2020-04-02 10:53:44,267 INFO [io.quarkus] (main) Installed features: [cdi, resteasy]
提供されたエンドポイントを要求するには、新しいターミナルウィンドウに以下のコマンドを入力します。
curl -w "\n" http://localhost:8080/hello hello
注記この例では、
"\n"属性を使用して、コマンドの出力の前に新しい行を自動的に追加します。これにより、ターミナルで '%' 文字が出力されたり、出力結果と次のコマンドプロンプトが同じ行に表示されたりすることを防ぎます。- アプリケーションを停止するには、CTRL+C を押します。
第5章 Quarkus ディペンデンシーインジェクション (依存性の注入) の使用
ディペンデンシーインジェクション (依存性の注入) により、クライアントによる消費とは完全に独立した方法で、サービスが使用されるようになります。クライアントの動作からクライアントの依存関係の作成を分離させるので、プログラム設計の結合度を弱めることができます。
Red Hat ビルドの Quarkus におけるディペンデンシーインジェクション (依存性の注入) は、Quarkus ArC をベースとしています。Quarkus ArC とは、Quarkus アーキテクチャーに合わせた CDI ベースのビルドタイム指向のディペンデンシーインジェクションソリューションのことです。Arc は quarkus-resteasy の推移的な依存関係であり、quarkus-resteasy はお客様のプロジェクトの依存関係であるため、ArC はすでにダウンロードされています。
前提条件
- Quarkus Getting Started プロジェクトを作成していること。
手順
アプリケーションを変更し、コンパニオン Bean を追加するには、以下の内容で
src/main/java/org/acme/quickstart/GreetingService.javaファイルを作成します。package org.acme.quickstart; import javax.enterprise.context.ApplicationScoped; @ApplicationScoped public class GreetingService { public String greeting(String name) { return "hello " + name; } }src/main/java/org/acme/quickstart/GreetingResource.javaを編集してGreetingServiceをインジェクトし、これを使用して新しいエンドポイントを作成します。package org.acme.quickstart; import javax.inject.Inject; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; import javax.ws.rs.core.MediaType; import org.jboss.resteasy.annotations.jaxrs.PathParam; @Path("/hello") public class GreetingResource { @Inject GreetingService service; @GET @Produces(MediaType.TEXT_PLAIN) @Path("/greeting/{name}") public String greeting(@PathParam String name) { return service.greeting(name); } @GET @Produces(MediaType.TEXT_PLAIN) public String hello() { return "hello"; } }アプリケーションを停止した場合には、以下のコマンドを入力して再起動します。
./mvnw compile quarkus:dev
エンドポイントが
hello quarkusを返すことを確認するには、新しいターミナルウィンドウに以下のコマンドを入力します。curl -w "\n" http://localhost:8080/hello/greeting/quarkus hello quarkus
第6章 JUnit を使用した Quarkus アプリケーションのテスト
Quarkus Getting Started プロジェクトをコンパイルしたら、アプリケーションを JUnit 5 フレームワークでテストし、想定どおりに実行されることを確認します。Quarkus プロジェクトが生成した pom.xml ファイルには、テスト用の依存関係が 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>
quarkus-junit5 依存関係は、JUnit 5 テストフレームワークを制御する @QuarkusTest アノテーションを提供するため、テストに必要です。rest-assured 依存関係は必須ではありませんが、HTTP エンドポイントをテストする便利な方法を提供するため、統合されています。正しい URL を自動的に設定するので、何も設定する必要はありません。
これらのテストは REST-assured フレームワークを使用しますが、希望する場合は別のライブラリーを使用できます。
前提条件
- Quarkus Getting Started プロジェクトをコンパイルしていること。
手順
Surefire Maven プラグインのバージョンを設定します。
<plugin> <artifactId>maven-surefire-plugin</artifactId> <version>${surefire-plugin.version}</version> <configuration> <systemProperties> <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager> </systemProperties> </configuration> </plugin>デフォルトの Surefire Maven プラグインバージョンは、JUnit 5 をサポートしません。
-
java.util.loggingシステムプロパティーを設定して、テストが適切なログマネージャーを使用するようにします。 src/test/java/org/acme/quickstart/GreetingResourceTest.javaファイルを以下の内容に一致するように編集します。package org.acme.quickstart; 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 public void testHelloEndpoint() { given() .when().get("/hello") .then() .statusCode(200) .body(is("hello")); } @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)); } }注記QuarkusTestランナーを使用することで、テストを開始する前に JUnit にアプリケーションを起動するよう指示します。Maven からこれらのテストを実行するには、以下のコマンドを入力します。
./mvnw test
注記IDE からテストを実行することもできます。その場合は、最初にアプリケーションを停止してください。
デフォルトでは、テストはポート
8081で実行されるため、実行中のアプリケーションと競合しません。Quarkus では、RestAssured依存関係はこのポートを使用するように設定されています。別のクライアントを使用する場合は、@TestHTTPResourceアノテーションを使用して、テスト済みアプリケーションの URL をTestクラスのフィールドに直接インジェクトします。このフィールドには、タイプstring、URL、またはURIを使用できます。このアノテーションにテストパスを指定することもできます。たとえば、/myservletにマップされたサーブレットをテストするには、以下の行をテストに追加します。@TestHTTPResource("/myservlet") URL testUrl;-
必要な場合は、
quarkus.http.test-port設定プロパティーにテストポートを指定します。
Quarkus は、インジェクションを使用できない状況のベーステスト URL に設定される test.url という名前のシステムプロパティーも作成します。
第7章 Quarkus Getting Started アプリケーションのパッケージ化および実行
Quarkus Getting Started プロジェクトをコンパイルしたら、JAR ファイルでパッケージ化し、コマンドラインから実行できます。
前提条件
- Quarkus Getting Started プロジェクトをコンパイルしていること。
手順
Quarkus Getting Started プロジェクトをパッケージ化するには、
rootディレクトリーで以下のコマンドを入力します。./mvnw package
このコマンドは、以下の JAR ファイルを
/targetディレクトリーに生成します。-
getting-started-1.0-SNAPSHOT.jar: プロジェクトのクラスおよびリソースが含まれます。これは、Maven ビルドで生成される通常のアーティファクトです。 -
getting-started-1.0-SNAPSHOT-runner.jar: 実行可能な JAR ファイルです。依存関係はtarget/libディレクトリーにコピーされるため、このファイルは uber-JAR ファイルではない点に注意してください。
-
- 開発モードを実行している場合は、CTRL+C を押して開発モードを停止します。停止しないと、ポートの競合が発生します。
アプリケーションを実行するには、以下のコマンドを入力します。
java -jar target/getting-started-1.0-SNAPSHOT-runner.jar
注記runnerJAR ファイルからのMANIFEST.MFファイルのClass-Pathエントリーは、libディレクトリーからの JAR ファイルを明示的に記述します。別の場所からアプリケーションをデプロイする場合は、runnerJAR ファイルとlibディレクトリーをコピーする必要があります。
第8章 その他のリソース
- Maven を使用した Quarkus アプリケーションの作成に関する詳細は、『Apache Maven を使用した Quarkus アプリケーションの作成』 を参照してください。
- Red Hat OpenShift Container Platform での Quarkus Maven アプリケーションのデプロイに関する詳細は、『Red Hat OpenShift Container Platform での Quarkus アプリケーションのデプロイ』 を参照してください。
- Maven Surefire プラグインの詳細は、Apache Maven Project の Web サイトを参照してください。
- JUnit 5 テストフレームワークの詳細は、JUnit 5 の Web サイトを参照してください。
- REST-assured の詳細は、REST-assured の Web サイトを参照してください。
改訂日時: 2020-11-18 01:18:15 UTC