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

エクステンションcodestart

このガイドでは、エクステンションのためにQuarkus Codestartを作成および設定する方法について説明します。

説明

"Extension Codestarts" is the name we gave to our Quarkus extension quickstart code generation system. It aims to provide a personalized getting started experience with Quarkus. A Quarkus extension is able to provide one or more well-defined codestarts which will contain the necessary resources and code required to start using that particular extension.

エクステンションcodestartは、Quarkusのツールで適用できます。

  • code.quarkus.io([code]とタグ付けされたエクステンションを探す)

  • QuarkusのMavenプラグイン:

    mvn io.quarkus.platform:quarkus-maven-plugin:create
  • QuarkusのCLI:

    quarkus create app

仕組

プロジェクトを開始する際には、言語、ビルドツール、フレームワークを選択し、dockerfile、CI、依存関係、コードを追加していきます。

Codestartsは、プロジェクトの生成に貢献する際に同じように働き、2つのカテゴリーに分けられます。

"ベース" のコードスタート(この組み合わせを選択):

  • project: プロジェクトの骨組(例:Quarkusプロジェクト)

  • buildtool: ビルドツール(例:Maven、Gradle、Gradle with Kotlin DSL)

  • language: コーディング言語(例:Java、Kotlin、Scala)

  • config: 設定の種類(例:yaml、properties)

追加のcodestart(好きなだけ、上乗せできます):

  • tooling:プロジェクトを改善するために追加できるもの(例:dockerfiles、github-actionなど)

  • code: どのQuarkusエクステンションもスターターコードを提供可能です。ユーザーはそれを有効にするかどうかを決めることができます。

各コードスタートは以下から構成されています:

  1. codestartのユニークな名前、つまり my-codestart

  2. codestartファイルを置くディレクトリ、つまり my-codestart/

  3. codestart.yml ファイル

  4. 共通の構造と命名規則に従ったいくつかのテンプレート(オプション)

Quarkus ExtensionのCodestartはどこにありますか?

  • Quarkusのコアレポジトリでは、エクステンションのcodestartはすべて同じ モジュールに入っています。

  • RESTEasy、RESTEasy Reactive、Spring Webエクステンションのcodestartは、 ベースのコードスタートの一部です。

  • その他のエクステンションの場合、codestartは通常、ランタイム・モジュールに配置されます(別のcodestartアーティファクトを生成するよう、 pom.xml に特別な指示があります)。

ベースcodestart

ベース codestartには、プロジェクト、ビルドツール、言語、設定、ツールの各ファイルを作成するためのテンプレートが含まれています。

エクステンションcodestartの作成

前述したように、プロジェクトの基本ファイル(pom.xml、dockerfileなど)は、Quarkusコアが提供する基本コードスタートですでに生成されています。このおかげで、私たちは重要なこと、つまりエクステンションのスターターコードにのみ集中することができます。

codestartにはビジネスロジックは含まれず、代わりにスタブデータやコンパイルされるhello worldが含まれている必要があります。このアイデアは、エクステンションを使用するすべての人に、出発点となるコードを提供することです。

Quarkus CoreでのエクステンションのCodestartの書き方

  • 既存の Quarkusコアエクステンションのcodestartの1つをコピーします。コードがウェブリソースを公開する必要がある場合は、 resteasy-qute-codestart が良いベースとなるでしょう。そうでない場合は、 config-yaml-codestart がより良い出発点となるでしょう。詳細は ディレクトリ構造を参照してください。

  • codestart.ymlを編集します。

  • エクステンションのメタデータにエクステンションバインディングを作成します (例)これにより、ユーザーがエクステンションを選択したときにコードスタートが追加されます

  • readme README.md セクションのテンプレートを追加します

  • コードを言語フォルダに追加します(少なくともjavaとkotlinを用意することをお勧めします)。 パッケージ名: org.acmeからの動的パッケージ名生成. として org.acme を使用する必要があります* 。必要であれば テンプレート(Qute) を使用することも可能です。

  • オプションで、 index.html セクションテンプレート( index-html)を追加します。

  • オプションで、いくつかのリソースを追加します(言語に依存しない場合は ./base ディレクトリ)。

  • オプションで、 app-configを追加します。

  • integration-testを作成

  • エクステンションcodestartの生成

Quarkiverseまたはスタンドアロンでのエクステンション Codestart の作成

For extensions hosted outside the Quarkus core[https://github.com/quarkusio/quarkus] repository, codestarts will typically be located in the runtime module (with special instruction in the pom.xml to generate a separate codestart artifact). Here is an example extension with a codestart and its tests.

エクステンションcodestartの生成

codestartをツールで利用できるようにするには、Mavenでビルドする必要があります。

  • まず、codestartを追加し、関連するエクステンションのメタデータymlファイルを更新し、すべて(coreの場合はcodestartとエクステンション)をビルドします。

  • また、Quarkus coreでは、 devtools/bom-descriptor-json モジュールを再ビルドして、codestartをplatform descriptorのエクステンションにバインドする必要があります。

テストの際に

buildAllProjects (Quarkus coreでは、 @EnabledIfSystemProperty(named = "build-projects", matches = "true") でcodestart開発を補助するために 結合テストを使用することが出来ます。これは、codestartがすでに別のテストで QuarkusCodestartBuildIT から一緒にビルドされているためです)。

このテストを実行する際に -Dbuild-projects=true を使用して、codestart で実際のプロジェクトを生成します。それをIDEで開き、コードを変更してcodestartにコピーし直します(結果に満足するまで繰り返します)。

Quarkusツールの使用

開発中にローカルのエクステンションのcodestartを生成するためのツールを使用することは、 Quarkiverse/Standalone エクステンション (それまでは、テストを使用したり、 #21165のアップデートに従うことができます) ではまだ利用できません。

CLIやMavenプラグインを使って、codestartでプロジェクトを生成:

  • CLIを使用する場合は、プラットフォームのスナップショットを使用するために、CLIの引数に -P=io.quarkus:quarkus-bom:999-SNAPSHOT を追加する必要があるでしょう。

  • CLIコマンドの例: quarkus create app -x smallrye-health --code --java -P=io.quarkus:quarkus-bom:999-SNAPSHOT

  • 同等のMavenプラグイン: mvn io.quarkus:quarkus-maven-plugin:2.3.0.Final:create -Dextensions=smallrye-health -DplatformVersion=999-SNAPSHOT

具体的なトピック

org.acmeからの動的パッケージ名生成

エクステンションの codestart のソースでは、パッケージ名として org.acme を使用する必要があります。生成されたプロジェクトでは、ユーザーが指定したパッケージが使用されます (そして、 org.acme を自動的に置き換えます)。

すべてのソースファイル(.java, .kt, .scala)で自動置換されます。また、パッケージディレクトリも自動的に調整されます。何らかの理由で、他の種類のファイルがユーザーパッケージ名を必要とする場合は、そのファイルに qute-templatesを使用し、 {project.package-name} データプレースホルダーを使用する必要があります( grpc protoファイルに例があります)。

codestart.yml

# the codestart unique name
name: resteasy-example
# the codestart reference (the name is used if not set)
ref: resteasy
# the type of codestart (other types are used for other project files)
type: code
# public metadata for this example (they will also be accessible from this codestart qute templates by using the key: {title})
metadata:
  title: RESTEasy JAX-RS example
  description: Rest is easy peasy with this Hello World RESTEasy resource.
  related-guide-section: https://quarkus.io/guides/getting-started#the-jax-rs-resources
  # the path is optional and used by the generated index.html if present
  path: /some-path
language:
  base:
    # Specify the extension and possibly other required dependencies
    dependencies:
      - io.quarkus:quarkus-resteasy
    # And maybe test dependencies?
    test-dependencies:
      - io.rest-assured:rest-assured

ディレクトリ構造

codestart.yml は唯一の必須ファイルです。
  • codestart.yml はcodestartのルートに配置される必要があります。

  • ./base 指定された言語とは独立して処理されるすべてのファイルを含みます

  • ./[java/kotlin/scala] は、指定された言語が選択されている場合にのみ処理されるすべてのファイルを含みます(baseをオーバーライドします)

Dynamic Config Keys in Codestart

gen-info.time: time of generation (in millis)

input.selected-extensions[].name|description|guide: list of selected extensions with info

input.selected-extensions-ga: Set of String with the list of extensions groupId:artifactId, usefull for dynamic codestarts depending on selected extensions

input.provided-code[].name|tags|title|description|related-guide: list of selected codestarts with info

Static Config Keys in Codestart

quarkus.platform.group-id: BOM groupId

quarkus.platform.artifact-id: BOM ArtifactId

quarkus.platform.version: BOM Version

project.group-id: Project groupId

project.artifact-id: project ArtifactId

project.version: Project Version

project.package-name: Project Package name

quarkus.maven-plugin.group-id: Quarkus Maven plugin groupId

quarkus.maven-plugin.artifact-id: Quarkus Maven plugin ArtifactId

quarkus.maven-plugin.version: Quarkus Maven plugin version.

quarkus.gradle-plugin.id: Quarkus gradle pluginId

quarkus.gradle-plugin.version: Quarkus gradle plugin version

quarkus.version: Quarkus version

java.version: Java version

kotlin.version: Kotlin version

scala.version: scala version

scala-maven-plugin.version: scala maven plugin version

maven-compiler-plugin.version: Maven compiler plugin version

maven-surefire-plugin.version: Maven surefire plugin version

ファイルの命名規則

  • .tpl.qute は、Quteで処理され、データを使用することができます(出力ファイル名から .tpl.qute が削除されます)。

  • readme.md, src/main/resources/application.yml, src/main/resources/META-INF/resources/index.html などの特定の共通ファイルは、プロジェクトのために選択されたコードスター トで見つかった収集されたフラグメントから生成されます。

  • 他のファイルはコピーされます。

テンプレート(Qute)

Codestartは、ダイナミックレンダリングのために Qute テンプレート MyClass.tpl.qute.java を使用することができます。

これらのテンプレートは、以下を含むデータを使用することができます:

  • 生成するcodestartの data (および公開 metadata )( codestart.yml で指定されている)

  • プロジェクトの生成に使用されたすべてのcodestartから shared-data をマージしたもの

  • ユーザー入力

  • いくつかの動的に生成されたデータ(例: dependenciestest-dependencies

README.md

base ディレクトリに README.mdREADME.tpl.qute.md を追加することが出来ます。他のものに追加されます。つまり、エクステンション codestart に関連する情報を追加するだけです。

base/readme.tpl.qute.md

{#include readme-header /}

[Optionally, Here you may add information about how to use the example, settings, ...]
{#include readme-header /} は、Quarkusプロジェクトのcodestartにあるテンプレートを使用し、 codestart.yml のメタデータから標準的な情報を表示します。

アプリケーション設定 application.yml

慣習として、Quarkusの設定は常にyamlファイル( base/src/main/resources/application.yml)として提供する必要があります。

設定は:

  • 他のエクステンションcodestartの設定にマージされます

  • 選択されたエクステンションに応じて、生成時に選択された設定タイプ(yamlまたはproperties)に自動的に変換されます

index.htmlとwebエクステンションのcodestart

Extension codestartsでは、このファイルを追加することで、生成されるindex.htmlにスニペットを提供することができます。

base/src/main/resources/META-INF/resources/index.entry.qute.html:

{#include index-entry /}
{#include index-entry /} は、Quarkusプロジェクトのcodestartにあるテンプレートを使用し、 codestart.yml のメタデータから標準的な情報を表示します。

結合テスト

エクステンション codestarts のテストに役立つエクステンションが用意されています QuarkusCodestartTest 。テストする方法を提供します:

  • スナップショットテストを用いて、生成されたプロジェクトコンテンツ(不変のモックデータを含む)

  • 生成されたプロジェクトのビルドと実行(実データを使用)、ビルドを実行するヘルパー付き

すべてのテストの前に、このエクステンションは、指定された言語で、指定されたcodestartで、モックされたデータと実際のデータを使ってQuarkusプロジェクトを生成します。生成されたプロジェクトは、 target/quarkus-codestart-test ディレクトリにあります。 real-data のプロジェクトは IDE で開くことができますし、ターミナルで操作することもできます。 実データは、エクステンションcodestartの開発を繰り返し行う最も簡単な方法です。

このエクステンションは、プロジェクトのビルド buildAllProjects や、特定の言語のプロジェクト buildProject(Language language) をテストするヘルパーを提供します。また、スナップショットテスト でコンテンツをテストするヘルパーも提供しています。

ConfigYamlCodestartTestは、Quarkus coreの良い例です。

スナップショットテスト

スナップショット テストとは、テストによって生成されるコンテンツが、あるリビジョンから別のリビジョン、つまりコミット間で変更されないようにする方法です。つまり、コミットごとに生成されるコンテンツは、不変であり、決定性がある必要があります(これが、モックされたデータを使用する理由です)。このようなチェックを行うために、生成されたコンテンツのスナップショットを自動生成し、後続のテスト実行時に期待される出力の参照先としてコミットします。テンプレートが変更された場合は、生成されたスナップショットの変更もコミットします。このようにして、レビューの際には、適用されたコードの変更が、生成された出力に対して期待される効果を持つことを確認することができます。

エクステンションは、コンテンツをチェックするためのヘルパーを提供します:

  • checkGeneratedSource() は、すべての言語(または特定の言語)のスナップショットに対してクラスを検証します。

  • checkGeneratedTestSource() は、すべての言語(または特定の言語)のスナップショットに対してテストクラスを検証します。

  • assertThatGeneratedFileMatchSnapshot() は、プロジェクトファイルをスナップショットと照合します。

  • 上記のメソッドの戻り値に AbstractPathAssert.satisfies(checkContains("some content")) または任意の Path アサートを使用して、ファイルに特定のコンテンツが含まれているかどうかを確認することもできます。

  • assertThatGeneratedTreeMatchSnapshots() では、特定の言語のプロジェクトのファイル構造(ツリー)を、そのスナップショットと比較することができます。

ローカルファイルシステム上の既存のスナップショットファイルを最初に生成または更新するためには、codestartの開発中にローカルでテストを実行する際に、 -Dsnap を追加する必要があります。これらはコミットの一部として追加する必要があり、そうしないとCI上でテストが通過しません。

作成のコツ

  • あなたのエクステンションcodestartは、buildtoolやdockerfilesから独立していなければなりません/しなければなりません。

  • エクステンションcodestartは、互いに干渉することなく(組み合わせて)一緒に使えるべきです。

  • クラス名がすべてのエクステンションのcodestartでユニークであることを担保してください。

  • パッケージ名には org.acme のみを使用してください。

  • RESTのパスには、ユニークなパス /[unique] を使用してください。

  • 設定は src/main/resources/application.yml ymlに記述してください。

    これは、他の codestarts のコンフィグとマージされ、選択された設定タイプ (yaml または properties) に自動的に変換されます。

  • javaから始めて、後で別のPRでkotlinを追加することもできます(忘れないようにissueを作成してください)。

  • 質問がある場合は、 https://quarkusio.zulipchat.com/ で @ia3andy に ping してください。