チュートリアルの作成
架空のエクステンションからのアノテーションを使用する Quarkus アプリケーションの作成、実行、およびテストをユーザーに説明する新しいチュートリアルを作成します。
前提条件
-
約15分
-
An editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or using a plugin.
-
You should be familiar with the overview of what a Tutorial is.
-
Have the Quarkus style and content guidelines handy as a reference for required syntax and other conventions.
1. タイトルとファイル名の決定
-
チュートリアルのタイトルを決めます。この作業例では、
Serve Http requests using the Acme extension
を使用します。 -
ファイル名を決めます。この例では、
acme-serve-http-requests-tutorial.adoc
を使用します。-
acme-
は、このガイドを acme エクステンションに関連する他のリソースとグループ化する -
serve-http-requests
はドキュメントのタイトルから派生したものである -
-tutorial.adoc
は、このドキュメントがチュートリアルであることを示す
-
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 | Specify the web category, as our imaginary extension works with Http requests. |
5 | 架空の acme エクステンションは実験的なものであるため、ヘッダーにエクステンションステータスの宣言を含めます。 |
ドキュメントのプレビューには、選択したタイトルがスタイル付きヘッダーとしてページの上部に含まれている必要があります。
4. 概要の追加
チュートリアルの読者に、チュートリアルの手順に従うことで何を達成できるのかを知らせる必要があります。この概要は簡潔である必要があり、適切な動詞 (作成する、ビルドする、デプロイするなど) を使用して期待感を高める必要があります。これにより、読者はチュートリアルのコンテンツに興味があるかないかを判断できるはずです。
実験的な acme エクステンションからの一意のアノテーションを使用して 2 つのエンドポイントを定義するアプリケーションを作成します。
単純な HTTP エンドポイントと、server-sent events (SSE) を発行するエンドポイントです。
また、Quarkus の開発モードを使用して、繰り返し開発とテストを行う予定です。
ドキュメントのプレビューには、ヘッダーのすぐ後の段落に概要が含まれている必要があります。
5. エクステンションステータスの説明テキストを含める
acme
エクステンションは実験的なものであるため、エクステンションのステータステキストを提供する {includes}/extension-status.adoc
を含めます。これは、ヘッダーで定義されているエクステンションステータス属性を使用しています。
include::{includes}/extension-status.adoc[]
The preview of your document should now include an admonition box below the abstract explaining that the plugin is experimental technology, and describing what can be expected in terms of stability or support for experimental technologies.
6. 前提条件の定義
チュートリアルを完了するために必要なリソースをユーザーに伝える必要があります。
開発活動を説明するチュートリアルは、前提条件を説明するときに一貫した言語が使用されるように {includes}/prerequisites.adoc
を使用する必要があります。prerequisites-
属性を宣言することで、最終的なテキストをカスタマイズすることができます。
== 前提条件
:prerequisites-time: 30 minutes // <1> :prerequisites-docker: // <2> :prerequisites-no-graalvm: // <3> include::{includes}/prerequisites.adoc[] (4)
`curl` コマンドラインユーティリティーは、エンドポイントを手動でテストするためにも使用されます。
1 | 架空のチュートリアルが完了するまでに約 30 分かかることを宣言します。 |
2 | 無意味な acme エクステンションにもコンテナーランタイムが必要であることを宣言します。 |
3 | For simplicity in this tutorial, we will avoid GraalVM and Mandrel prerequisites. |
4 | 前提条件を説明するテキストを提供する共通ファイルを含めます。 |
第 2 レベルの Prerequistes
見出しは、ドキュメントプレビューのエクステンションステータスボックスの直後に表示される必要があります。これには、以下を記載する必要があります。
-
このチュートリアルの所要時間が約 30 分であること。
-
IDE、JDK (バージョンを含む)、maven (maven バージョンのプレースホルダーを含む)、動作するコンテナーランタイム、および (オプションで) Quarkus CLI が必要であること。
7. チュートリアルを完了するための手順の説明
このプロセスにはいくつかの部分があります。各手順は、理解可能/観察可能な結果 (「出力はこのようになります…」など) で終了する必要があることを覚えておいてください。
7.1. 最初の手順の定義
最初の手順のヘッダーを指定する前に、セクションの番号付けを有効にします。
:sectnums: (1)
:sectnumlevels: 3
== Create a new project (2)
以下のコマンドで新規プロジェクトを作成します: (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 | Define the artifact id (Maven or 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 javax.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 callouts are shown as comments on some lines, and their numbering is not sequential.
-
AsciiDoc content regions are defined by tag pairs (
tag::
andend::
) in comments surrounding different sections of code.
7.3. 簡潔な後続の手順の提供
それでは、架空の @Anvil
アノテーションを使用して、単純なエンドポイントを作成するよう学習者に指示しましょう。
7.3.1. ソースコードファイルの作成
エンドポイントを作成してファイルに追加するために必要な手順から始めます。
== Hello, World! as an Acme REST service
`@Anvil` アノテーションを使用して、Http エンドポイントを作成してみましょう。
新しいソースファイル `src/main/java/org/acme/MyAcmeApplication.java` を作成し、`MyAcmeApplication` Bean を以下のように定義します。
[source,java]
----
include::{doc-examples}/acme-serve-http-requests-MyAcmeApplication.java[tags=*;!goodbye]
----
<1> この Bean の CDI ライフサイクルを指定します。
`@ApplicationScoped` にはアプリケーションに使用される 1 つの Bean インスタンスがあります。
<2> `@Anvil` アノテーションは、このケースでは `/hello` というメソッド名から派生した uri による単純な Http GET リクエストを常に意味します。
`optional` 値は、`name` パラメーターが不要であることを示しています。
以下は、これらの手順に関する注意事項です。
-
リストから
goodbye
メソッドを除外するために Asciidoc タグ付き領域を使用しながら、ソースファイルからのコードを含めています。 -
代替の CDI ライフサイクルに関する詳細には触れずに、
@ApplicationScoped
が何を意味するのかについて、いくつかのコンテキストを示しています。 -
このチュートリアルで取り上げる特定のケースで
@Anvil
が提供するものについて説明します。
Be careful with the amount of explanation given in a tutorial. Include enough information in the tutorial to help the user determine what other resource (howto , concept , or reference ) they should look at next.
|
プレビューには、新しいセクション 2. Hello, World! as an Acme REST service
が含まれている必要があります。これには、goodbye
メソッドが省略された src/main/java/org/acme/MyAcmeApplication.java
のコンテンツが含まれています。
7.3.2. 継続的な開発とテストについて調べる
ここで、ユーザーに Quarkus 開発モードを開始する手順を説明します。一般的なインクルードが、ほとんどの作業を行います。
== Dev Mode: Hello, World!
Quarkus の反復開発モードを使用してアプリケーションを実行してみましょう。
include::{includes}/devtools/dev.adoc[]
開発モードのコンソール出力で準備が整ったことを確認したら、`curl` を使って `hello` エンドポイントを呼び出します:
[source,shell]
----
$ curl -w "\n" http://localhost:8080/hello Hello, World!
----
パラメーターとして名前を渡します:
[source,bash,subs=attributes+]
----
$ curl localhost:8080/hello -d '{"name": "bananas"}' Hello, bananas!
----
チュートリアルの残りの期間中、開発モードを起動したままにしておくと、コードを変更するたびに継続的にフィードバックを受けることができます。
`CTRL-C` を使用して開発モードを終了します。
ここでは、いくつかのことを提供しています。
-
開発モードを開始する方法を説明する共通テキストを使用しています。
-
定義したエンドポイントの出力をテストするために
curl
を使用する方法を説明しています。
プレビューには、新しいセクション "3. Dev Mode: Hello, World!" が含まれているはずです。このセクションには、Quarkus の開発モードを起動する 3 つのメソッド (cli、maven、gradle) が含まれている必要があります。また、curl コンソールコマンドと出力を含むコードブロック、および開発モードを終了する方法が含まれている必要があります。
7.3.3. テストの追加
次に、アプリケーションにテストを追加する手順をユーザーに説明しましょう。
== Testing: Hello, World!
それでは、`@Anvil` エンドポイントで動作するテストを作成してみましょう。
新しいソースファイル `src/test/java/org/acme/MyAcmeApplicationTest.java` を作成し、以下のように `MyAcmeApplicationTest` を定義します。
[source,java]
----
include::{doc-examples}/acme-serve-http-requests-MyAcmeApplicationTest.java[tags=*;!goodbye]
----
保存後、開発コンソールはテストの存在を検出するはずですが、デフォルトでは実行されていません。
コンソール画面の下部に、実行中のテストが一時停止されたことを示すメッセージが表示されます。
テストを再開するには `r` を押します。
テストの実行中にステータスの変更を確認でき、1 つのテストが実行されて成功したことを示すメッセージで終了するはずです。
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
`@Toaster` アノテーションを使用して、Server Sent Events をサポートするエンドポイントを追加してみましょう。
[source,java]
----
include::{doc-examples}/acme-serve-http-requests-MyAcmeApplication.java[tag=goodbye]
----
<1> `@Toaster` アノテーションは、このメソッドが Server-Sent Events を発行することを示します。
<2> `Multi` は、Quarkus が使用するイベント駆動型のリアクティブストリームライブラリーである Mutiny が提供する、複数のイベントの非同期パブリッシャーです。
== Testing: Goodbye, Sweet Planet!
`@Toaster` エンドポイントで動作するテストを作成してみましょう。
以下のメソッドを `src/test/java/org/acme/MyAcmeApplicationTest.java` に追加します。
[source,java]
----
include::{doc-examples}/acme-serve-http-requests-MyAcmeApplicationTest.java[tag=goodbye]
----
保存後、開発コンソールは追加のテストの存在を検出し、両方を実行する必要があります。
2 つのテストが実行され、両方とも正常に実行されたというメッセージが表示されるはずです。
以下の点に注意してください。
-
We’re using the AsciiDoc region tag to include only one region of the target file.
-
概念の詳細については説明しません。
-
この例では、
@Toaster
アノテーションが何を行っているのかについて説明しています。 -
Multi
という用語は、ユーザーが他の関連資料 (ハウツー、コンセプト、またはリファレンス) にたどりつけるような形で定義しています。
-
プレビューには、2 つの新しいセクション 5. Goodbye, Sweet Planet! Server sent events with Acme
および 6. Testing: Goodbye, Sweet Planet!
が含まれているはずです。
2 つの新しいコードリストは、以前は省略されていたメソッドに注目する必要があります。つまり、src/main/java/org/acme/MyAcmeApplication.java
の goodbye
と src/main/java/org/acme/MyAcmeApplicationTest.java
の testGoodbyeEndpoint
です。
8. 概要セクションの提供
:sectnums!: (1)
== まとめ
おめでとうございます! `@Anvil` および `@Toaster` アノテーションを使用して、架空のエンドポイントを作成するために acme エクステンションを使用するプロジェクトを作成しました。 (2)
1 | セクション番号付けをオフにします。 |
2 | ユーザーの健闘を称えましょう! |
プレビューには、番号のない Summary
セクションが含まれているはずです。
まとめ
おめでとうございます! あなたは、架空のエクステンションから半信半疑のメリットを持つアノテーションを使用するアプリケーションの作成方法を説明するチュートリアルを作成しました。
Compare your result against the complete worked example:
////
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[]
:categories: web
:extension-status: experimental
In this tutorial, we will 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 test.
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.