The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
このページを編集

チュートリアルの作成

架空のエクステンションからのアノテーションを使用する Quarkus アプリケーションの作成、実行、およびテストをユーザーに説明する新しいチュートリアルを作成します。

前提条件

  • 約15分

  • 組込機能またはプラグインを使用して、AsciiDocの構文の強調表示とプレビューを提供するエディターまたは IDE。

  • チュートリアル とは何かについての概要に精通している必要があります。

  • 必要な構文やその他の規約のリファレンスとして Quarkus スタイル・コンテンツガイドライン を使用してください。

1. タイトルとファイル名の決定

  1. チュートリアルのタイトルを決めます。この作業例では、Serve Http requests using the Acme extension を使用します。

  2. ファイル名を決めます。この例では、 acme-serve-http-requests-tutorial.adoc を使用します。

    • acme- は、このガイドを acme エクステンションに関連する他のリソースとグループ化します

    • serve-http-requests はドキュメントのタイトルから派生したものです

    • -tutorial この文書がチュートリアルであることを示します (オプション)

    • .adoc asciidocファイルであることを示します

2. チュートリアルテンプレートのコピー

docs/src/main/diataxis/_templates/template-tutorial.adoc を Quarkus リポジトリーから acme-serve-http-requests-tutorial.adoc という名前の新しいファイルにコピーします。

3. ドキュメントヘッダーの更新

[id="acme-serve-http-requests-tutorial"] (1)
= Serve Http requests using the Acme extension (2)
include::_attributes.adoc[] (3)
:categories: web (4)
:extension-status: experimental (5)
1 ファイル名をセクションのユニークIDとして使用します。
2 タイトルを最上位の見出しとして追加します。
3 一貫したフォーマットを定義し、ソースの移植性を提供する際に役立つ追加の属性を含めます。
4 web カテゴリを指定します。この想像上のエクステンションは、Http リクエストで動作します。
5 架空の acme エクステンションは実験的なものであるため、ヘッダーにエクステンションステータスの宣言を含めます。
ドキュメントのプレビュー

ドキュメントのプレビューには、選択したタイトルがスタイル付きヘッダーとしてページの上部に含まれている必要があります。

4. 概要の追加

チュートリアルの読者に、チュートリアルの手順に従うことで何を達成できるのかを知らせる必要があります。この概要は簡潔である必要があり、適切な動詞 (作成する、ビルドする、デプロイするなど) を使用して期待感を高める必要があります。これにより、読者はチュートリアルのコンテンツに興味があるかないかを判断できるはずです。

Create an application that uses unique annotations from the experimental acme extension to define two endpoints:
a simple HTTP endpoint and an endpoint that emits server-sent events (SSE).
We will also use Quarkus dev mode for iterative development and testing.
ドキュメントのプレビュー

ドキュメントのプレビューには、ヘッダーのすぐ後の段落に概要が含まれている必要があります。

5. エクステンションステータスの説明テキストを含める

acme エクステンションは実験的なものであるため、エクステンションのステータステキストを提供する {includes}/extension-status.adoc を含めます。これは、ヘッダーで定義されているエクステンションステータス属性を使用しています。

include::{includes}/extension-status.adoc[]
ドキュメントのプレビュー

ドキュメントのプレビューには、アブストラクトの下に、プラグインが実験的な技術であることを説明し、実験的な技術の安定性またはサポートに関して何が期待できるかを説明する警告ボックスが含まれているはずです。

6. 前提条件の定義

チュートリアルを完了するために必要なリソースをユーザーに伝える必要があります。

開発活動を説明するチュートリアルは、前提条件を説明するときに一貫した言語が使用されるように {includes}/prerequisites.adoc を使用する必要があります。prerequisites- 属性を宣言することで、最終的なテキストをカスタマイズすることができます。

== Prerequisites

:prerequisites-time: 30 minutes (1)
:prerequisites-docker: (2)
:prerequisites-no-graalvm: (3)
include::{includes}/prerequisites.adoc[] (4)

The `curl` command line utility is also used to manually test the endpoint.
1 架空のチュートリアルが完了するまでに約 30 分かかることを宣言します。
2 無意味な acme エクステンションにもコンテナーランタイムが必要であることを宣言します。
3 このチュートリアルでは、簡単のために、graalvm/mandrel の前提条件を避けることにします。
4 前提条件を説明するテキストを提供する共通ファイルを含めます。
ドキュメントのプレビュー

第 2 レベルの Prerequistes 見出しは、ドキュメントプレビューのエクステンションステータスボックスの直後に表示される必要があります。これには、以下を記載する必要があります。

  • このチュートリアルの所要時間が約 30 分であること。

  • IDE、JDK (バージョンを含む)、maven (maven バージョンのプレースホルダーを含む)、動作するコンテナーランタイム、および (オプションで) Quarkus CLI が必要であること。

7. チュートリアルを完了するための手順の説明

このプロセスにはいくつかの部分があります。各手順は、理解可能/観察可能な結果 (「出力はこのようになります…​」など) で終了する必要があることを覚えておいてください。

7.1. 最初の手順の定義

最初の手順のヘッダーを指定する前に、セクションの番号付けを有効にします。

:sectnums: (1)
:sectnumlevels: 3
== Create a new project (2)

Create a new project with the following command: (3)

:create-app-artifact-id: acme-quickstart (4)
:create-app-extensions: acme (5)
include::{includes}/devtools/create-app.adoc[] (6)
1 セクション番号付けを有効にします。
2 最初の手順の第 2 レベルの見出しを作成します。
3 手順を簡単に説明します。
4 アーティファクトIDの定義 (MavenまたはGradle)
5 このプロジェクトに必要なエクステンションを一覧表示します。
6 共通テキストを使用して、プロジェクトの作成方法を説明します。
ドキュメントのプレビュー

ドキュメントのプレビューには、1. Create a new project という新しいセクションが追加されているはずです。このセクションには、Quarkus CLI と maven の両方を使用して新しいプロジェクトを作成するための手順が含まれています。

7.2. ソースファイルの使用

このチュートリアルでは、タグを使用して別の Java ファイルからのコードを含めます。

これは野心的な例と考えてください。ソースは、ソースコードブロックに直接含まれることが一般的です。Java ファイルからソースを含めることには利点がありますが、参照されたコードが存在する場所に関して解決しなければならない詳細事項があります。ヘルプやアイデアをお待ちしています。

acme-serve-http-requests-MyAcmeApplication.java というファイルを作成しましょう。これは有効な Java ファイル名ではありませんが、チュートリアルソースの隣にうまく配置されています。構文チェックには IDE マジックを使用します。

そのファイルに以下のコードを追加してみましょう。

// tag::application[]
package org.acme;

import jakarta.enterprise.context.ApplicationScoped;

import org.acme.corp.Anvil;
import org.acme.corp.Toaster;

import io.smallrye.mutiny.Multi;

@ApplicationScoped // <1>
public class MyAcmeApplication {

    @Anvil(optional = {"name"}) // <2>
    public String hello(String name) {
        return String.format("Hello, %s!", (name == null ? "World" : name));
    }

    // tag::goodbye[]
    @Toaster // <1>
    public Multi<String> longGoodbye(String name) {
        return Multi.createFrom().items("Goodbye", ",", "Sweet", "Planet", "!"); // <2>
    }
    // end::goodbye[]
}
// end::application[]

このコードサンプルには、注意すべき点がいくつかあります。

  • AsciiDocのcalloutは、一部の行でコメントとして表示され、その番号は連番ではありません。

  • AsciiDocのコンテンツ領域は、コードの異なるセクションを囲むコメント内のタグペア( tag::end:: )で定義されます。

7.3. 簡潔な後続の手順の提供

それでは、架空の @Anvil アノテーションを使用して、単純なエンドポイントを作成するよう学習者に指示しましょう。

7.3.1. ソースコードファイルの作成

エンドポイントを作成してファイルに追加するために必要な手順から始めます。

== Hello, World! as an Acme REST service

Let's create a Http endpoint using the `@Anvil` annotation.

Create a new source file, `src/main/java/org/acme/MyAcmeApplication.java`, and define the `MyAcmeApplication` bean as follows:

[source,java]
----
include::{doc-examples}/acme-serve-http-requests-MyAcmeApplication.java[tags=*;!goodbye]
----

<1> Specify the CDI lifecycle of this bean.
An `@ApplicationScoped` bean has a single bean instance that is used for the application.
<2> The `@Anvil` annotation always implies a simple Http GET request with the uri derived from the method name, `/hello` in this case.
The `optional` value indicates that the `name` parameter is not required.

以下は、これらの手順に関する注意事項です。

  • リストから goodbye メソッドを除外するために Asciidoc タグ付き領域を使用しながら、ソースファイルからのコードを含めています。

  • 代替の CDI ライフサイクルに関する詳細には触れずに、@ApplicationScoped が何を意味するのかについて、いくつかのコンテキストを示しています。

  • このチュートリアルで取り上げる特定のケースで @Anvil が提供するものについて説明します。

チュートリアルでの説明の量に注意してください。チュートリアルには、ユーザーが次に参照すべき他のリソース (ハウツー、コンセプト、リファレンス) はどれなのかを判断する上で役立つ十分な情報を含むようにしてください。
ドキュメントのプレビュー

プレビューには、新しいセクション 2. Hello, World! as an Acme REST service が含まれている必要があります。これには、goodbye メソッドが省略された src/main/java/org/acme/MyAcmeApplication.java のコンテンツが含まれています。

7.3.2. 継続的な開発とテストについて調べる

ここで、ユーザーに Quarkus 開発モードを開始する手順を説明します。一般的なインクルードが、ほとんどの作業を行います。

== Dev Mode: Hello, World!

Let's run our application using Quarkus' iterative development mode:

include::{includes}/devtools/dev.adoc[]

Once the console output from dev mode indicates that things are ready, use `curl` to invoke the `hello` endpoint:

[source,shell]
----
$ curl -w "\n" http://localhost:8080/hello
Hello, World!
----

Pass the name as a parameter:

[source,bash,subs=attributes+]
----
$ curl localhost:8080/hello -d '{"name": "bananas"}'
Hello, bananas!
----

You can leave dev mode running throughout the rest of the tutorial for continuous feedback as you make changes to code.
Use `CTRL-C` to exit dev mode.

ここでは、いくつかのことを提供しています。

  • 開発モードを開始する方法を説明する共通テキストを使用しています。

  • 定義したエンドポイントの出力をテストするために curl を使用する方法を説明しています。

ドキュメントのプレビュー

プレビューには、新しいセクション "3. Dev Mode: Hello, World!" が含まれているはずです。このセクションには、Quarkus の開発モードを起動する 3 つのメソッド (cli、maven、gradle) が含まれている必要があります。また、curl コンソールコマンドと出力を含むコードブロック、および開発モードを終了する方法が含まれている必要があります。

7.3.3. テストの追加

次に、アプリケーションにテストを追加する手順をユーザーに説明しましょう。

== Testing: Hello, World!

Let's create a test to work with our `@Anvil` endpoint.

Create a new source file, `src/test/java/org/acme/MyAcmeApplicationTest.java`, and define `MyAcmeApplicationTest` as follows:

[source,java]
----
include::{doc-examples}/acme-serve-http-requests-MyAcmeApplicationTest.java[tags=*;!goodbye]
----

After saving, the dev console should detect the presence of tests, but it isn't running by default.
The bottom of the console screen will display a message indicating that running tests have been paused.

Press `r` to resume testing.
You should see the status change as tests are running, and it should finish with a message indicating that 1 test was run and that it was successful.

Asciidoc リージョンタグを使用して、リストからメソッドを除外しています (これは後で追加します)。

ドキュメントのプレビュー

プレビューには、新しいセクション 4. Testing: Hello, World! が含まれている必要があります。これには、testGoodbyeEndpoint メソッドが省略された src/main/java/org/acme/MyAcmeApplicationTest.java のコンテンツが含まれています。

7.3.4. 機能の追加

架空の @Toaster アノテーションを使用して別のエンドポイントを作成し、対応するテストを提供するための別の手順を追加してみましょう。

== Goodbye, Sweet Planet! Server sent events with Acme

Let's add an endpoint that supports Server Sent Events using the `@Toaster` annotation:

[source,java]
----
include::{doc-examples}/acme-serve-http-requests-MyAcmeApplication.java[tag=goodbye]
----
<1> The `@Toaster` annotation indicates that this method emits Server-Sent Events.
<2> A `Multi` is an asynchronous publisher of multiple events provided by Mutiny, the event-driven reactive streams library used by Quarkus.

== Testing: Goodbye, Sweet Planet!

Let's create a test to work with our `@Toaster` endpoint.

Add the following method to `src/test/java/org/acme/MyAcmeApplicationTest.java`:

[source,java]
----
include::{doc-examples}/acme-serve-http-requests-MyAcmeApplicationTest.java[tag=goodbye]
----

After saving, the dev console should detect the presence of the additional test, and run both.
You should see a message that 2 tests were run, and both were successful.

以下の点に注意してください。

  • AsciiDoc リージョンタグを使用して、ターゲットファイルのリージョンを 1 つだけ含めています。

  • 概念の詳細については説明しません。

    • この例では、@Toaster アノテーションが何を行っているのかについて説明しています。

    • Multi という用語は、ユーザーが他の関連資料 (ハウツー、コンセプト、またはリファレンス) にたどりつけるような形で定義しています。

ドキュメントのプレビュー

プレビューには、2 つの新しいセクション 5. Goodbye, Sweet Planet! Server sent events with Acme および 6. Testing: Goodbye, Sweet Planet! が含まれているはずです。

2 つの新しいコードリストは、以前は省略されていたメソッドに注目する必要があります。つまり、src/main/java/org/acme/MyAcmeApplication.javagoodbyesrc/main/java/org/acme/MyAcmeApplicationTest.javatestGoodbyeEndpoint です。

8. 概要セクションの提供

:sectnums!: (1)
== Summary

Congratulations! You have created a project that uses the acme extension to create fanciful endpoints using the `@Anvil` and `@Toaster` annotations. (2)
1 セクション番号付けをオフにします。
2 ユーザーの健闘を称えましょう!
ドキュメントのプレビュー

プレビューには、番号のない Summary セクションが含まれているはずです。

まとめ

おめでとうございます! あなたは、架空のエクステンションから半信半疑のメリットを持つアノテーションを使用するアプリケーションの作成方法を説明するチュートリアルを作成しました。

結果を完璧な作業例と比較してください:

////
This document is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
[id="acme-serve-http-requests-tutorial"]
= Serve Http requests using the Acme extension
include::_attributes.adoc[]
:diataxis-type: tutorial
:categories: web
:extension-status: experimental

Create an application that uses unique annotations from the experimental acme extension to define two endpoints:
a simple HTTP endpoint and an endpoint that emits server-sent events (SSE).
We will also use Quarkus dev mode for iterative development and testing.

include::{includes}/extension-status.adoc[]

== Prerequisites

:prerequisites-time: 30 minutes
:prerequisites-docker:
:prerequisites-no-graalvm:

include::{includes}/prerequisites.adoc[]

The `curl` command line utility is also used to manually test the endpoint.

:sectnums:
:sectnumlevels: 3
== Create a new project

Create a new project with the following command:

:create-app-artifact-id: acme-quickstart
:create-app-extensions: acme
include::{includes}/devtools/create-app.adoc[]

== Hello, World! as an Acme Http service

Let's create a Http endpoint using the `@Anvil` annotation.

Create a new source file, `src/main/java/org/acme/MyAcmeApplication.java`,
and define the `MyAcmeApplication` bean as follows:

[source,java]
----
include::{examples}/acme-serve-http-requests-MyAcmeApplication.java[tags=*;!goodbye]
----

<1> Specify the CDI lifecycle of this bean.
An `@ApplicationScoped` bean has a single bean instance that is used for the application.
<2> The `@Anvil` annotation always implies a simple Http GET request with the uri derived from the method name, `/hello` in this case.
The `optional` value indicates that the `name` parameter is not required.

== Dev Mode: Hello, World!

Let's run our application using Quarkus' iterative development mode:

include::{includes}/devtools/dev.adoc[]

Once the console output from dev mode indicates that things are ready, use `curl` to invoke the `hello` endpoint:

[source,shell]
----
$ curl -w "\n" http://localhost:8080/hello
Hello, World!
----

Pass the name as a parameter:

[source,bash,subs=attributes+]
----
$ curl localhost:8080/hello -d '{"name": "bananas"}'
Hello, bananas!
----

You can leave dev mode running throughout the rest of the tutorial for continuous feedback as you make changes to code.
Use `CTRL-C` to exit dev mode.

== Testing: Hello, World!

Let's create a test to work with our `@Anvil` endpoint.

Create a new source file, `src/test/java/org/acme/MyAcmeApplicationTest.java`, and define `MyAcmeApplicationTest` as follows:

[source,java]
----
include::{examples}/acme-serve-http-requests-MyAcmeApplicationTest.java[tags=*;!goodbye]
----

After saving, the dev console should detect the presence of tests, but it isn't running by default.
The bottom of the console screen will display a message indicating that running tests have been paused.

Press `r` to resume testing.
You should see the status change as they are running, and it should finish with a message indicating that 1 test was run and that it was successful.

== Goodbye, Sweet Planet! Server sent events with Acme

Let's add an endpoint that supports Server Sent Events using the `@Toaster` annotation:

[source,java]
----
include::{examples}/acme-serve-http-requests-MyAcmeApplication.java[tag=goodbye]
----
<1> The `@Toaster` annotation indicates that this method emits Server-Sent Events.
<2> A `Multi` is an asynchronous publisher of multiple events provided by Mutiny, the event-driven reactive streams library used by Quarkus.

== Testing: Goodbye, Sweet Planet!

Let's create a test to work with our `@Toaster` endpoint.

Add the following method to `src/test/java/org/acme/MyAcmeApplicationTest.java`:

[source,java]
----
include::{examples}/acme-serve-http-requests-MyAcmeApplicationTest.java[tag=goodbye]
----

After saving, the dev console should detect the presence of the additional test, and run both.
You should see a message that 2 tests were run, and both were successful.

:sectnums!:
== Summary

Congratulations!
You have created a project that uses the acme extension to create fanciful endpoints using the `@Anvil` and `@Toaster` annotations.

関連コンテンツ