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

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

Hello World Quarkus アプリの作成方法を説明します。 このガイドでは、以下の内容を説明します。

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

  • Jakarta RESTのエンドポイントの作成

  • Bean の注入

  • 機能テスト

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

1. 前提条件

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

  • 約15分

  • IDE

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

  • Apache Maven 3.9.6

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

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

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

2. アーキテクチャ

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

Architecture

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

3. ソリューション

プロジェクトのブートストラップ 以降の指示に従って、ステップバイステップでアプリケーションを作成することをお勧めします。

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

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

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

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

4. プロジェクトの開始

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

コマンドラインインタフェース
quarkus create app org.acme:getting-started \
    --extension='rest'
cd getting-started

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

Quarkus CLIのインストールと使用方法の詳細については、 Quarkus CLI ガイドを参照してください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.9.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=getting-started \
    -Dextensions='rest'
cd getting-started

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

Windowsユーザーの場合:

  • cmdを使用する場合、(バックスラッシュ \ を使用せず、すべてを同じ行に書かないでください)。

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

./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 が存在することが分かります。

<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 アプリケーションの開発を可能にするエクステンションがあることがわかります。

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest</artifactId>
</dependency>
build.gradle
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 では、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, rest]

アプリケーションが起動したら、提供されたエンドポイントにリクエストを送信することができます。

$ curl -w "\n" http://localhost:8080/hello
Hello from Quarkus REST

CTRL+C を押してアプリケーションを停止することも、アプリケーションを起動したまま高速なホットリロードを行うことも可能です。

curl -w "\n" で自動的に改行が追加されるようにします。

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

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
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 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 をテストクラスのフィールドに直接注入する必要があります。このフィールドは 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. パッケージ化とアプリケーションの実行

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

コマンドラインインタフェース
quarkus build
Maven
./mvnw install
Gradle
./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 でホットリロードモードを停止することを忘れないでください 。停止しないと、ポートが衝突します。

デフォルトでは、通常モードまたは開発モードで 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エクステンションが、アプリケーションに関するさまざまな情報を提供する非アプリケーションエンドポイントを提供しています。そのようなエクステンションの例として、 healthmetricsOpenAPI 、infoエクステンションがあります。

これらの非アプリケーションエンドポイントは、通常、 /q のプレフィックスで次のようにアクセスします:

  • /q/health

  • /q/metrics

  • /q/openapi

  • /q/info

しかし、ユーザーは、セキュリティリスクをもたらす可能性のあるものを、専用の 管理インターフェイス を使用して、別のTCPポートで公開することを選択することもできます。

12.1. Info endpoint

アプリケーションに quarkus-info のエクステンションが含まれている場合、Quarkusはデフォルトで /q/info のエンドポイントを公開し、ビルド、Javaバージョン、バージョン管理、オペレーティングシステムに関する情報を提供します。公開される情報の詳細レベルは、設定可能です。

InfoContributor を実装している全てのCDI Beanがピックアップされ、そのデータがエンドポイントに追加されます。

12.1.1. 設定リファレンス

ビルド時に固定される構成プロパティ - 他のすべての構成プロパティは実行時にオーバーライド可能

Configuration property

タイプ

デフォルト

Whether the info endpoint will be enabled

Environment variable: QUARKUS_INFO_ENABLED

Show more

ブーリアン

true

The path under which the info endpoint will be located

Environment variable: QUARKUS_INFO_PATH

Show more

string

info

Whether git info will be included in the info endpoint

Environment variable: QUARKUS_INFO_GIT_ENABLED

Show more

ブーリアン

true

Controls how much information is present in the git section

Environment variable: QUARKUS_INFO_GIT_MODE

Show more

standard, full

standard

Whether build info will be included in the info endpoint

Environment variable: QUARKUS_INFO_BUILD_ENABLED

Show more

ブーリアン

true

Whether os info will be included in the info endpoint

Environment variable: QUARKUS_INFO_OS_ENABLED

Show more

ブーリアン

true

Whether java info will be included in the info endpoint

Environment variable: QUARKUS_INFO_JAVA_ENABLED

Show more

ブーリアン

true

Additional properties to be added to the build section

Environment variable: QUARKUS_INFO_BUILD

Show more

Map<String,String>

13. 次のステップ

このガイドでは、Quarkusを使用したアプリケーションの作成について説明しました。 しかし、まだ多くのことがあります。 引き続き、開発サービスと永続性を備えた 2つ目のQuarkusアプリケーション を作成することをお勧めします。 ネイティブ実行可能ファイルの作成とコンテナへのパッケージ化については、 ネイティブ実行可能ファイルの作成ガイド を参照してください。 リアクティブに興味がある場合は、Quarkusでリアクティブアプリケーションを実装する方法を確認できる、 リアクティブを始めるガイド をお勧めします。

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

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

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

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

  • その他

関連コンテンツ