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

初めてのアプリケーションの作成

Hello World Quarkus アプリケーションの作成方法を説明します。 このガイドでは、以下の内容を取り扱います。

  • アプリケーション開発の開始

  • JAX-RS エンドポイントの作成

  • Bean の注入

  • 機能テスト

  • アプリケーションのパッケージ化

1. 前提条件

このガイドを完成させるには、以下が必要です:

  • 約15分

  • IDE

  • JDK 11+ がインストールされ、 JAVA_HOME が適切に設定されていること

  • Apache Maven 3.8.1+

  • 使用したい場合は、 Quarkus CLI

Maven が意図した Java を使用していることの確認

複数の JDK がインストールされている場合、 Maven が意図した java を利用するとは限らず、予期しない結果になる可能性があります。 Maven がどの JDK を使用するかは、mvn --version を実行することで確認することができます。

2. アーキテクチャ

このガイドでは、hello エンドポイントを提供する簡単なアプリケーションを作成します。依存性の注入の動作を示すために、このエンドポイントでは greeting Bean を使用します。

アーキテクチャ

このガイドでは、エンドポイントのテストについても解説します。

3. ソリューション

プロジェクトの開始 とそれ以降の解説に従って、段階的にアプリケーションを作成することを推奨します。

ただし、アプリケーションの完成例にそのまま進んでも構いません。

Git レポジトリをクローンするか、 アーカイブ をダウンロードします:

git clone https://github.com/quarkusio/quarkus-quickstarts.git

ソリューションは getting-started ディレクトリ にあります。

4. プロジェクトの開始

新しい Quarkus プロジェクトを作成する最も簡単な方法は、ターミナルを開いて以下のコマンドを実行することです。

Linux と MacOS ユーザー

CLI
quarkus create app org.acme:getting-started \
    --extension=resteasy-reactive
cd getting-started

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストール方法については、Quarkus CLIガイドをご参照ください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:2.12.3.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=getting-started \
    -Dextensions="resteasy-reactive"
cd getting-started

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

Windows ユーザー

  • cmd を使用する場合は、バックスラッシュ \ は使わず、一行で実行します。

  • Powershell を使用する場合は、 "-DprojectArtifactId=getting-started" のように -D パラメーターを二重引用符で囲みます。

./getting-started に以下の内容が生成されます。

  • Maven の構造

  • /hello で公開される org.acme.getting.start.GreetingResource リソース

  • 関連するユニットテスト

  • アプリケーション起動後に http://localhost:8080 でアクセス可能な Web ページ

  • src/main/docker に配置される nativejvm の両方のモード用の Dockerfile ファイルの例

  • アプリケーションの設定ファイル

生成されたら、pom.xml を確認します。 Quarkus の BOM がインポートされており、 これによって Quarkus の依存関係のバージョンを省略することができます。 また、アプリケーションのパッケージ化を行う quarkus-maven-plugin と、開発モードを提供する quarkus-maven-plugin も存在することが確認できます。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>${quarkus.platform.group-id}</groupId>
            <artifactId>quarkus-bom</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 アプリケーションの開発を可能にするエクステンションがあることがわかります。

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-reactive</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-resteasy-reactive")

4.1. JAX-RS リソース

プロジェクト作成時には、以下の内容で src/main/java/org/acme/getting/started/GreetingResource.java ファイルが作成されます。

package org.acme;

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 from RESTEasy Reactive";
    }
}

これは "/hello" へのリクエストに対して "Hello RESTEasy" と返す、非常にシンプルな REST エンドポイントです。

標準的な JAX-RS との違い

Quarkus では、Application クラスを作成する必要はありません。作成することは可能ですが、必須ではありません。さらに、リソースのインスタンスは 1 つだけ作成され、リクエストごとに 1 つ作成されるわけではありません。これは、さまざまな *Scoped アノテーション( ApplicationScopedRequestScoped など)を使用して設定することができます。

5. アプリケーションの実行

ここまでで、アプリケーションを実行する準備が整いました。

コマンドラインインタフェース
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./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" で自動的に改行が追加されるようにします。

この例では curl -w "\n" を使用して、結果とプロンプトが1行で表示されてしまうことを防止しています。

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 javax.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class GreetingService {

    public String greeting(String name) {
        return "hello " + name;
    }

}

GreetingResource クラスを編集して GreetingService を注入し、それを使用して新しいエンドポイントを作成します。

package org.acme;

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;

@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)
    @Path("/greeting/{name}")
    public String greeting(String name) {
        return service.greeting(name);
    }

アプリケーションを停止しなくても、ライブリロード機能によって変更が自動的にデプロイされますが、アプリケーションを停止した場合は、次のようにアプリケーションを再起動します。

コマンドラインインタフェース
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./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つのテストの依存関係が示されています。

pom.xml
<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>
build.gradle
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"));
    }

    @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 をテストクラスのフィールドに直接注入する必要があります。このフィールドは StringURLURI のいずれかの型になります。このアノテーションにはテストパスの値を指定することもできます。例えば、/myservlet にマップされたサーブレットをテストしたい場合、次のようにテストに追加します。

@TestHTTPResource("/myservlet")
URL testUrl;

テストポートは、 quarkus.http.test-port 設定プロパティーで制御できます。 Quarkus はまた、依存性注入を使用できない場合のためにベースとなるテスト URL に設定される test.url システムプロパティーを作成します。

9. マルチモジュールプロジェクトや外部モジュールとの連携

Quarkus はビルド時に Jandex を多用して、さまざまなクラスやアノテーションを検出しています。このことがすぐに認識できるアプリケーションの1つは、 CDI Bean のディスカバリーです。 結果、このビルド時のディスカバリーが適切に設定されていないと、Quarkus のエクステンションのほとんどが正しく動作しません。

このインデックスは、 Maven と Gradle プラグインにより、 Quarkus が設定されているプロジェクトにデフォルトで作成されます。

しかし、マルチモジュールプロジェクトで作業する場合は、 Maven または Gradle ガイドの マルチモジュールプロジェクトでの作業 のセクションを必ず読んでください。

外部モジュール (例えば、すべてのドメインオブジェクトのための外部ライブラリ) を使用する予定がある場合は、 Jandex プラグインを追加するか (変更できる場合)、 application.properties 内の quarkus.index-dependency プロパティーを使って (モジュールを変更できない場合に有用) 、これらのモジュールをインデックス作成プロセスに知らせておく必要があります。

詳細は、CDI ガイドの Bean の検出 セクションを必ずお読みください。

10. パッケージ化とアプリケーションの実行

このアプリケーションは、以下の方法でパッケージ化されています。

CLI
quarkus build
Maven
./mvnw clean package
Gradle
./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 でホットリロードモードを停止することを忘れないでください 。停止しないと、ポートが衝突します。

デフォルトでは、通常モードまたは開発モードで Quarkus アプリケーションが起動すると、 ASCII アートバナーが表示されます。バナーを無効にするには、 application.propertiesquarkus.banner.enabled=false を設定するか、 Dquarkus.banner.enabled=false の Java システムプロパティーを設定する、 あるいは QUARKUS_BANNER_ENABLED 環境変数を false に設定します。 さらに、 src/main/resources にバナーファイルを配置し、 application.propertiesquarkus.banner.path=nam-of-file を設定することで、ユーザーはカスタムのバナーを提供することができます。

12. 次のステップ

このガイドでは、Quarkus を使用したアプリケーションの作成について説明しました。 しかし、まだまだ多くのことがあります。 ネイティブ実行可能ファイルのビルド で、ネイティブ実行可能ファイルの作成とコンテナーへのパッケージ化について学習することを推奨します。 リアクティブに興味がある場合は、リアクティブアプリケーションを Quarkus で実装する方法を解説した リアクティブ入門ガイド をお勧めします。

また、ツールガイド のドキュメントでは、以下について説明しています。

  • 単一のコマンドラインでプロジェクトの雛形を生成する方法

  • development mode (ホットリロード) を有効にする方法

  • よく利用する IDE でプロジェクトをインポートする

  • その他