Back to Guides

バージョン:

このページを編集

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

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

アプリケーション開発の開始
Jakarta RESTのエンドポイントの作成
Bean の注入
機能テスト
アプリケーションのパッケージ化

1. 前提条件

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

約15分
IDE
JDK 17+がインストールされ、 JAVA_HOME が適切に設定されていること
Apache Maven 3.9.9
使用したい場合は、 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 プロジェクトを作成する最も簡単な方法は、ターミナルを開いて以下のコマンドを実行することです。

コマンドラインインタフェース

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

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 アノテーション (ApplicationScoped、RequestScoped など) を使用することで設定可能です。

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 をテストクラスのフィールドに直接注入する必要があります。このフィールドは 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 が設定されているプロジェクトにデフォルトで作成されます。

ただし、マルチモジュールプロジェクトで作業する場合は、 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.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	タイプ	デフォルト
`quarkus.info.enabled` Whether the info endpoint will be enabled Environment variable: `QUARKUS_INFO_ENABLED` Show more	ブーリアン	`true`
`quarkus.info.path` The path under which the info endpoint will be located Environment variable: `QUARKUS_INFO_PATH` Show more	string	`info`
`quarkus.info.git.enabled` Whether git info will be included in the info endpoint Environment variable: `QUARKUS_INFO_GIT_ENABLED` Show more	ブーリアン	`true`
`quarkus.info.git.mode` Controls how much information is present in the git section Environment variable: `QUARKUS_INFO_GIT_MODE` Show more	`standard`, `full`	`standard`
`quarkus.info.build.enabled` Whether build info will be included in the info endpoint Environment variable: `QUARKUS_INFO_BUILD_ENABLED` Show more	ブーリアン	`true`
`quarkus.info.build."property-key"` Additional properties to be added to the build section Environment variable: `QUARKUS_INFO_BUILD__PROPERTY_KEY_` Show more	Map<String,String>
`quarkus.info.os.enabled` Whether os info will be included in the info endpoint Environment variable: `QUARKUS_INFO_OS_ENABLED` Show more	ブーリアン	`true`
`quarkus.info.java.enabled` Whether java info will be included in the info endpoint Environment variable: `QUARKUS_INFO_JAVA_ENABLED` Show more	ブーリアン	`true`

Configuration property

タイプ

デフォルト

quarkus.info.enabled

Whether the info endpoint will be enabled

Environment variable: QUARKUS_INFO_ENABLED

ブーリアン

true

quarkus.info.path

The path under which the info endpoint will be located

Environment variable: QUARKUS_INFO_PATH

string

info

quarkus.info.git.enabled

Whether git info will be included in the info endpoint

Environment variable: QUARKUS_INFO_GIT_ENABLED

ブーリアン

true

quarkus.info.git.mode

Controls how much information is present in the git section

Environment variable: QUARKUS_INFO_GIT_MODE

standard, full

standard

quarkus.info.build.enabled

Whether build info will be included in the info endpoint

Environment variable: QUARKUS_INFO_BUILD_ENABLED

ブーリアン

true

quarkus.info.build."property-key"

Additional properties to be added to the build section

Environment variable: QUARKUS_INFO_BUILD__PROPERTY_KEY_

Map<String,String>

quarkus.info.os.enabled

Whether os info will be included in the info endpoint

Environment variable: QUARKUS_INFO_OS_ENABLED

ブーリアン

true

quarkus.info.java.enabled

Whether java info will be included in the info endpoint

Environment variable: QUARKUS_INFO_JAVA_ENABLED

ブーリアン

true

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 でプロジェクトをインポートする
その他

1. 前提条件
2. アーキテクチャ
3. ソリューション
4. プロジェクトの開始
- 4.1. Jakarta RESTリソース
5. アプリケーションの実行
6. 依存性注入の使用
7. 開発モード
8. テスト
9. マルチモジュールプロジェクトや外部モジュールとの連携
10. パッケージ化とアプリケーションの実行
11. バナーの設定
12. 非アプリケーションエンドポイント
- 12.1. Info endpoint
13. 次のステップ

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

1. 前提条件

2. アーキテクチャ

3. ソリューション

4. プロジェクトの開始

4.1. Jakarta RESTリソース

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

6. 依存性注入の使用

7. 開発モード

8. テスト

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

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

11. バナーの設定

12. 非アプリケーションエンドポイント

12.1. Info endpoint

12.1.1. 設定リファレンス

13. 次のステップ

関連コンテンツ

On the same topics