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 を使用していることの確認

If you have multiple JDK’s installed, it is not certain Maven will pick up the expected java and you could end up with unexpected results. You can verify which JDK Maven uses by running 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.11.1.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=getting-started \
    -Dextensions="resteasy-reactive"
cd getting-started

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

Windows ユーザー

  • cmd を使っている場合 (バックスラッシュは使わず、全て同じ行にしてください)

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

以下のように ./getting-started に生成されます。

  • Maven の構造

  • org.acme.getting.start.GreetingResource リソースは、/hello で公開されます。

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

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

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

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

生成されたら、pom.xml を確認してください。 Quarkus の BOM のインポートが存在することが分かります。これにより、異なる Quarkus の依存関係のバージョンを省略できます。さらに、アプリケーションのパッケージングと開発モードを処理する 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>

In a Gradle project, you would find a similar setup:

  • the Quarkus Gradle plugin

  • an enforcedPlatform directive for the Quarkus BOM

依存関係の部分に注目すると、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";
    }
}

It’s a very simple REST endpoint, returning "Hello from RESTEasy Reactive" to requests on "/hello".

バニラ JAX-RS との違い

Quarkus では、Application クラスを作成する必要がありません。作成は可能ですが、必須ではありません。加えて、リソースは 1 つのみが作成され、リクエスト毎に 1 つではありません。これは、異なる *Scoped アノテーション (ApplicationScopedRequestScoped など) を使用することで設定可能です。

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

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

CLI
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" を使用して、結果と次のコマンドプロンプトが同じ行に表示されるのを防止しています。

6. インジェクションの使用

Quarkus の依存性注入は、Quarkus のアーキテクチャに合わせて調整された CDI ベースの依存性注入ソリューションである ArC をベースにしています。 CDI が初めての方は、 CDI入門 ガイドをお読みになることをお勧めします。

Quarkus は CDI 機能のサブセットのみを実装しており、非標準の機能や特定の API が追加されています。詳細は、 Contexts and Dependency Injection ガイド を参照してください。

ArC comes as a dependency of quarkus-resteasy-reactive so you already have it handy.

アプリケーションを変更してコンパニオン 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)
    public String hello() {
        return "hello";
    }
}

If you stopped the application (keep in mind you don’t have to do it, changes will be automatically deployed by our live reload feature), restart the application with:

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

Then check that the endpoint returns hello quarkus as expected:

$ curl -w "\n" http://localhost:8080/hello/greeting/quarkus
hello quarkus

7. 開発モード

quarkus:dev は、開発モードで Quarkus を実行します。これにより、Java ファイルやリソースファイルを変更してブラウザを更新すると、これらの変更が自動的に反映されます。 これは、設定プロパティーファイルなどのリソースファイルに対しても機能します。 ブラウザをリフレッシュすると、ワークスペースのスキャンがトリガーされ、変更が検出された場合、Java ファイルが再コンパイルされ、アプリケーションが再デプロイされます。リクエストは、再デプロイされたアプリケーションによって処理されます。コンパイルやデプロイに問題がある場合は、エラーページで通知します。

これはポート 5005 のデバッガーもリッスンします。デバッガーがアタッチされるのを待ってから実行する場合は、コマンドラインで -Dsuspend を渡してください。デバッガーを全く必要としない場合は -Ddebug=false を使います。

8. テスト

さて、ここまでは問題ありませんが、念のためにテストをした方がいいでしょう。

生成された pom.xml ファイルでは、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 レスポンスのステータスコードと内容を確認します。

These tests use RestAssured, but feel free to use your favorite library.

これらは 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 Discovery セクションを必ずお読みください。

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

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

CLI
quarkus build
Maven
./mvnw clean package
Gradle
./gradlew build

これは /target にいくつかの出力を生成します。

  • getting-started-1.0.0-SNAPSHOT.jar: プロジェクトのクラスとリソースだけを含み、Maven ビルドによって生成される通常のアーティファクトです。

  • 実行可能 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) ことを忘れないでください 。停止しないと、ポートが衝突します。

By default, when a Quarkus application starts (in regular or dev mode), it will display an ASCII art banner. The banner can be disabled by setting quarkus.banner.enabled=false in application.properties, by setting the -Dquarkus.banner.enabled=false Java System Property, or by setting the QUARKUS_BANNER_ENABLED environment variable to false. Furthermore, users can supply a custom banner by placing the banner file in src/main/resources and configuring quarkus.banner.path=name-of-file in application.properties.

12. 次のステップ

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

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

  • 単一のコマンドラインでプロジェクトをスキャフォールドする方法

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

  • お気に入りの IDE でプロジェクトをインポートする

  • その他もろもろ