Quarkus アプリケーションの設定
はじめに
アプリケーション開発者は、Red Hat ビルドの Quarkus を使用して、OpenShift 環境およびサーバーレス環境で実行される Java で書かれたマイクロサービスベースのアプリケーションを作成できます。ネイティブ実行可能ファイルにコンパイルされたアプリケーションは、メモリーのフットプリントが小さく、起動時間は高速です。
本ガイドでは、Eclipse MicroProfile Config メソッドまたは YAML 形式を使用して Quarkus アプリケーションを設定する方法を説明します。この手順には、Quarkus の config-quickstart
演習を使用して作成された設定例が含まれます。
前提条件
OpenJDK (JDK) 11 がインストールされ、
JAVA_HOME
環境変数が Java SDK の場所を指定している。- Red Hat ビルドの Open JDK は、Red Hat カスタマーポータルの Software Downloads ページからダウンロードできます (ログインが必要です)。
Apache Maven 3.8.1 以降がインストールされている。
- Maven は Apache Maven Project の Web サイトからダウンロードできます。
Maven が、Quarkus Maven リポジトリー のアーティファクトを使用するように設定されている。
- Maven の設定方法は、Quarkus スタートガイド を参照してください。
Red Hat ドキュメントへのフィードバック (英語のみ)
技術的な内容に関するフィードバックに感謝します。ご意見をお聞かせください。コメントの追加、Insights の提供、誤字の修正、および質問を行う必要がある場合は、ドキュメントで直接行うこともできます。
Red Hat アカウントがあり、カスタマーポータルにログインしている必要があります。
カスタマーポータルからドキュメントのフィードバックを送信するには、以下の手順を実施します。
- Multi-page HTML 形式を選択します。
- ドキュメントの右上にある Feedback ボタンをクリックします。
- フィードバックを提供するテキストのセクションを強調表示します。
- ハイライトされたテキストの横にある Add Feedback ダイアログをクリックします。
- ページの右側のテキストボックスにフィードバックを入力し、Submit をクリックします。
フィードバックを送信すると、自動的に問題の追跡が作成されます。Submit をクリックすると表示されるリンクを開き、問題の監視を開始するか、さらにコメントを追加します。
貴重なフィードバックにご協力いただきありがとうございます。
多様性を受け入れるオープンソースの強化
Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。
第1章 Red Hat ビルドの Quarkus 設定オプション
設定オプションを使用すると、1 つの設定ファイルでアプリケーションの設定を変更できます。Quarkus は、必要に応じて関連するプロパティーをグループ化し、プロファイルの切り替えを可能にする設定プロファイルをサポートします。
Eclipse MicroProfile プロジェクトの MicroProfile Config 仕様を使用して、設定プロパティーをアプリケーションに注入し、コードに定義されたメソッドを使用して設定できます。デフォルトでは、Quarkus は src/main/resources
ディレクトリーにある application.properties
ファイルからプロパティーを読み取ります。
config-yaml
依存関係をプロジェクト pom.xml
ファイルに追加することにより、YAML 形式を使用して application.yaml
ファイルにアプリケーションプロパティーを追加できます。
Quarkus は、さまざまなソースからアプリケーションプロパティーを読み取ることもできます (例: ファイルシステム、データベース、または Java アプリケーションによってロードできるソースなど)。
第2章 設定クイックスタートプロジェクトの作成
config-quickstart
プロジェクトでは、Apache Maven および Quarkus Maven プラグインを使用して、簡単な Quarkus アプリケーションを使い始めることができます。以下の手順では、Quarkus Maven プロジェクトの作成方法を説明します。
手順
Maven が JDK 11 を使用し、Maven のバージョンが 3.8.1 以降であることを確認します。
mvn --version
このコマンドで JDK 11 が返されない場合は、お使いのシステムで JDK 11 がインストールされているディレクトリーが
PATH
環境変数に含まれていることを確認します。export PATH=$PATH:/path/to/jdk-11
プロジェクトを生成するには、以下のコマンドを入力します。
mvn io.quarkus:quarkus-maven-plugin:1.11.7.Final-redhat-00009:create \ -DprojectGroupId=org.acme \ -DprojectArtifactId=config-quickstart \ -DplatformGroupId=com.redhat.quarkus \ -DplatformVersion=1.11.7.Final-redhat-00009 \ -DclassName="org.acme.config.GreetingResource" \ -Dpath="/greeting" cd config-quickstart
このコマンドは、
config-quickstart
ディレクトリーに以下の項目を作成します。- Maven プロジェクトディレクトリー構造
-
An
org.acme.config.GreetingResource
リソース -
アプリケーションの起動後に
http://localhost:8080
でアクセス可能なランディングページ - ネイティブモードおよび JVM モードでアプリケーションをテストするための関連するユニットテスト
-
src/main/docker
ディレクトリーのDockerfile.jvm
、Dockerfile.native
、およびDockerfile.fast-jar
ファイルの例 アプリケーションの設定ファイル
注記このチュートリアルで使用する Quarkus Maven プロジェクトを Quarkus quickstart archive からダウンロードしたり、
Quarkus Quickstarts
Git リポジトリーをクローンしたりすることもできます。この演習はconfig-quickstart
ディレクトリーにあります。
第3章 Quarkus アプリケーションの設定ファイルのサンプルの生成
すべての利用可能な設定値と、アプリケーションが使用するように設定されたエクステンションのドキュメントで application.properties.example
ファイルを作成できます。新しいエクステンションのインストール後にこの手順を繰り返し、追加された設定オプションを確認できます。
前提条件
- Quarkus Maven プロジェクトがある。
手順
application.properties.example
ファイルを作成するには、以下のコマンドを入力します。./mvnw quarkus:generate-config
このコマンドは、
src/main/resources/
ディレクトリーにapplication.properties.example
ファイルを作成します。このファイルには、インストールしたエクステンションで公開されるすべての設定オプションが含まれます。これらのオプションはコメントアウトされ、該当する場合はデフォルト値があります。以下の例は、
application.properties.example
ファイルからの HTTP ポート設定エントリーを示しています。#quarkus.http.port=8080
第4章 Quarkus アプリケーションへの設定値の注入
Red Hat ビルドの Quarkus は MicroProfile Config 機能 を使用して、設定データをアプリケーションに注入します。コンテキストおよび依存性注入 (CDI) を使用するか、コードに定義されたメソッドを使用して、設定にアクセスできます。
@ConfigProperty
アノテーションを使用して、オブジェクトプロパティーをアプリケーションの MicroProfile ConfigSources ファイルのキーにマップできます。この手順では、個別のプロパティー設定を Quarkus config-quickstart
プロジェクトに注入する方法を説明します。
前提条件
-
config-quickstart
プロジェクトを作成している。
手順
-
src/main/resources/application.properties
ファイルを開きます。 設定プロパティーを設定ファイルに追加します。
<key>
はプロパティー名に、<value>
はプロパティーの値に置き換えます。<key>=<value>
以下の例は、Quarkus
config-quickstart
プロジェクトでgreeting.message
プロパティーおよびgreeting.name
プロパティーの値を設定する方法を示しています。src/main/resources/application.properties
greeting.message = hello greeting.name = quarkus
重要Quarkus プロパティーの接頭辞として
quarkus
を使用します。GreetingResource.java
ファイルを確認し、次のインポートステートメントが含まれていることを確認します。import org.eclipse.microprofile.config.inject.ConfigProperty; import java.util.Optional;
次の例に示すように、
@ConfigProperty
で注釈を付けて、対応するプロパティーを定義します。src/main/java/org/acme/config/GreetingResource.java
@ConfigProperty(name = "greeting.message") 1 String message; @ConfigProperty(name = "greeting.suffix", defaultValue="!") 2 String suffix; @ConfigProperty(name = "greeting.name") Optional<String> name; 3
注記設定した値を注入するには、
@ConfigProperty
を使用します。@ConfigProperty
でアノテーションが付けられたメンバーには、@Inject
アノテーションは必要ありません。hello
メソッドを編集して、次のメッセージを返します。src/main/java/org/acme/config/GreetingResource.java
@GET @Produces(MediaType.TEXT_PLAIN) public String hello() { return message + " " + name.orElse("world") + suffix; }
開発モードでアプリケーションをコンパイルして起動します。
./mvnw quarkus:dev
エンドポイントがメッセージを返すことを確認するには、新しいターミナルウィンドウに以下のコマンドを入力します。
curl http://localhost:8080/greeting
このコマンドは、以下の出力を返します。
hello quarkus!
- アプリケーションを停止するには、CTRL+C を押します。
4.1. @ConfigProperties でのクラスのアノテーション
複数の関連する設定値を個別に注入する代わりに、@io.quarkus.arc.config.ConfigProperties
アノテーションを使用して設定プロパティーをグループ化できます。以下の手順では、Quarkus config-quickstart
プロジェクトでの @ConfigProperties
アノテーションの使用を示しています。
前提条件
-
config-quickstart
プロジェクトを作成している。
手順
GreetingResource.java
ファイルを確認し、次のインポートステートメントが含まれていることを確認します。src/main/java/org/acme/config/GreetingResource.java
import java.util.Optional; import javax.inject.Inject;
-
src/main/java/org/acme/config
ディレクトリーにGreetingConfiguration.java
ファイルを作成します。 ConfigProperties
とOptional
のインポートをGreetingConfiguration.java
ファイルに追加します。src/main/java/org/acme/config/GreetingConfiguration.java
import io.quarkus.arc.config.ConfigProperties; import java.util.Optional; import javax.inject.Inject;
GreetingConfiguration.java
ファイルにgreeting
プロパティーのGreetingConfiguration
クラスを作成します。src/main/java/org/acme/config/GreetingConfiguration.java
@ConfigProperties(prefix = "greeting") 1 public class GreetingConfiguration { private String message; private String suffix = "!"; 2 private Optional<String> name; public String getMessage() { return message; } public void setMessage(String message) { this.message = message; } public String getSuffix() { return suffix; } public void setSuffix(String suffix) { this.suffix = suffix; } public Optional<String> getName() { return name; } public void setName(Optional<String> name) { this.name = name; } }
@Inject
アノテーションを使用してGreetingConfiguration
クラスをGreetingResource
クラスに注入します。src/main/java/org/acme/config/GreetingResource.java
@Path("/greeting") public class GreetingResource { @Inject GreetingConfiguration config; @GET @Produces(MediaType.TEXT_PLAIN) public String hello() { return config.getMessage() + " " + config.getName().orElse("world") + config.getSuffix(); } }
開発モードでアプリケーションをコンパイルして起動します。
./mvnw quarkus:dev
重要クラスプロパティーの値を指定しないと、アプリケーションはコンパイルに失敗し、値が指定されていないことを示す
javax.enterprise.inject.spi.DeploymentException
を受け取ります。これは、Optional
フィールドおよびデフォルト値のフィールドには適用されません。エンドポイントがメッセージを返すことを確認するには、新しいターミナルウィンドウに以下のコマンドを入力します。
curl http://localhost:8080/greeting
以下のメッセージが表示されます。
hello quarkus!
- アプリケーションを停止するには、CTRL+C を押します。
4.2. ネストされたオブジェクト設定の使用
既存のクラス内でネストされたクラスを定義できます。この手順では、config-quickstart
プロジェクトでネストされたクラスの設定を作成する方法を説明します。
前提条件
-
config-quickstart
プロジェクトを作成している。
手順
GreetingConfiguration.java
ファイルを確認し、次のインポートステートメントが含まれていることを確認します。src/main/java/org/acme/config/GreetingConfiguration.java
import io.quarkus.arc.config.ConfigProperties; import java.util.Optional; import java.util.List;
@ConfigProperties
アノテーションを使用して、GreetingConfiguration.java
ファイルに設定を追加します。次の例は、
GreetingConfiguration
クラスとそのプロパティーの設定を示しています。src/main/java/org/acme/config/GreetingConfiguration.java
@ConfigProperties(prefix = "greeting") public class GreetingConfiguration { public String message; public String suffix = "!"; public Optional<String> name; }
次の例に示すように、
GreetingConfiguration
クラス内にネストされたクラスを追加します。src/main/java/org/acme/config/GreetingConfiguration.java
@ConfigProperties(prefix = "greeting") public class GreetingConfiguration { public String message; public String suffix = "!"; public Optional<String> name; public ContentConfig content; public static class ContentConfig { public Integer prizeAmount; public List<String> recipients; } }
この例は、ネストされたクラス
ContentConfig
を示しています。フィールドの名前 (ここではcontent
) が、オブジェクトにバインドされるプロパティーの名前を決定します。application.properties
ファイルでgreeting.content.prize-amount
およびgreeting.content.recipients
設定プロパティーを設定します。次の例は、
GreetingConfiguration
クラスとContentConfig
クラスのプロパティーの値を示しています。src/main/resources/application.properties
greeting.message = hello greeting.name = quarkus greeting.content.prize-amount=10 greeting.content.recipients=Jane,John
@Inject
アノテーションを使用してGreetingConfiguration
クラスをGreetingResource
クラスに注入し、/greeting
エンドポイントが返すメッセージ文字列を更新し、追加した新しいgreeting.content.prize-amount
プロパティーおよびgreeting.content.recipients
プロパティーに設定した値をメッセージに表示させます。src/main/java/org/acme/config/GreetingResource.java
@Path("/greeting") public class GreetingResource { @Inject GreetingConfiguration config; @GET @Produces(MediaType.TEXT_PLAIN) public String hello() { return config.message + " " + config.name.orElse("world") + config.suffix + "\n" + config.content.recipients + " receive total of candies: " + config.content.prizeAmount; } }
開発モードでアプリケーションをコンパイルして起動します。
./mvnw quarkus:dev
重要クラスプロパティーの値を指定しないと、アプリケーションはコンパイルに失敗し、値が指定されていないことを示す
javax.enterprise.inject.spi.DeploymentException
を受け取ります。これは、Optional
フィールドおよびデフォルト値のフィールドには適用されません。エンドポイントがメッセージを返すことを確認するには、新しいターミナルウィンドウに以下のコマンドを入力します。
curl http://localhost:8080/greeting
1 行目に挨拶、2 行目に賞金の受賞者と賞金額が書かれたメッセージを受信します。
hello quarkus! Jane,John receive total of candies: 10
- アプリケーションを停止するには、CTRL+C を押します。
@ConfigProperties
のアノテーションが付けられたクラスは、以下に示す例のような Bean Validation のアノテーションを付けることができます。
@ConfigProperties(prefix = "greeting") public class GreetingConfiguration { @Size(min = 20) public String message; public String suffix = "!"; }
プロジェクトには quarkus-hibernate-validator
依存関係が含まれている必要があります。
4.3. @ConfigProperties でのインターフェイスのアノテーション
プロパティーを管理する代替方法は、インターフェイスとして定義することです。インターフェイスに @ConfigProperties
のアノテーションを付けると、そのインターフェイスは他のインターフェイスを拡張でき、インターフェイス階層全体のメソッドを使用してプロパティーをバインドできます。
この手順では、Quarkus config-quickstart
プロジェクトのインターフェイスとしての GreetingConfiguration
クラスの実装について説明します。
前提条件
-
config-quickstart
プロジェクトを作成している。
手順
GreetingConfiguration.java
ファイルを確認し、次のインポートステートメントが含まれていることを確認します。src/main/java/org/acme/config/GreetingConfiguration.java
import io.quarkus.arc.config.ConfigProperties; import org.eclipse.microprofile.config.inject.ConfigProperty; import java.util.Optional;
GreetingConfiguration
クラスをインターフェイスとしてGreetingConfiguration.java
ファイルに追加します。src/main/java/org/acme/config/GreetingConfiguration.java
@ConfigProperties(prefix = "greeting") public interface GreetingConfiguration { @ConfigProperty(name = "message") 1 String message(); @ConfigProperty(defaultValue = "!") String getSuffix(); 2 Optional<String> getName(); 3 }
@Inject
アノテーションを使用してGreetingConfiguration
クラスをGreetingResource
クラスに注入します。src/main/java/org/acme/config/GreetingResource.java
@Path("/greeting") public class GreetingResource { @Inject GreetingConfiguration config; @GET @Produces(MediaType.TEXT_PLAIN) public String hello() { return config.message() + " " + config.getName().orElse("world") + config.getSuffix(); } }
開発モードでアプリケーションをコンパイルして起動します。
./mvnw quarkus:dev
重要クラスプロパティーの値を指定しないと、アプリケーションはコンパイルに失敗し、値が指定されていないことを示す
javax.enterprise.inject.spi.DeploymentException
を受け取ります。これは、Optional
フィールドおよびデフォルト値のフィールドには適用されません。エンドポイントがメッセージを返すことを確認するには、新しいターミナルウィンドウに以下のコマンドを入力します。
curl http://localhost:8080/greeting
以下のメッセージが表示されます。
hello quarkus!
- アプリケーションを停止するには、CTRL+C を押します。
第5章 コードからの設定へのアクセス
コードに定義されたメソッドを使用すると、設定にアクセスできます。CDI Bean リソースまたは JAX-RS リソースのいずれかのクラスから、動的ルックアップを実行したり、設定した値を取得したりできます。
org.eclipse.microprofile.config.ConfigProvider.getConfig()
メソッドを使用して設定にアクセスできます。Config object
の getValue
メソッドは、設定プロパティーの値を返します。
前提条件
- Quarkus Maven プロジェクトがある。
手順
以下のオプションのいずれかを使用して設定にアクセスします。
application.properties
ファイルですでに定義されているプロパティーの設定にアクセスするには、次の構文を使用します。DATABASE.NAME
は、databaseName
変数に割り当てられたプロパティーの名前です。String databaseName = ConfigProvider.getConfig().getValue("DATABASE.NAME", String.class);
application.properties
ファイルで定義されていない可能性があるプロパティーの設定にアクセスするには、次の構文を使用します。Optional<String> maybeDatabaseName = ConfigProvider.getConfig().getOptionalValue("DATABASE.NAME", String.class);
第6章 設定プロパティーの設定
デフォルトでは、Quarkus は src/main/resources
ディレクトリーにある application.properties
ファイルからプロパティーを読み取ります。ビルドプロパティーを変更する場合は、アプリケーションを必ず再パッケージしてください。
Quarkus はビルド時にほとんどのプロパティーを設定します。エクステンションはプロパティーを実行時に上書き可能であると定義できます (例: データベース URL、ユーザー名、ターゲット環境に固有のパスワード)。
前提条件
- Quarkus Maven プロジェクトがある。
手順
Quarkus プロジェクトをパッケージ化するには、以下のコマンドを入力します。
./mvnw clean package
以下のメソッドのいずれかを使用して、設定プロパティーを設定します。
システムプロパティーの設定
以下のコマンドを入力します。
<key>
は追加する設定プロパティーの名前に、<value>
はプロパティーの値に置き換えます。java -D<key>=<value> -jar target/myapp-runner.jar
たとえば、
quarkus.datasource.password
プロパティーの値を設定するには、以下のコマンドを入力します。java -Dquarkus.datasource.password=youshallnotpass -jar target/myapp-runner.jar
環境変数の設定
以下のコマンドを入力します。
<key>
は設定する設定プロパティーの名前に、<value>
はプロパティーの値に置き換えます。export <key>=<value> ; java -jar target/myapp-runner.jar
注記環境変数名は、Eclipse MicroProfile の変換ルールに従います。名前を大文字に変換し、英数字以外の文字をすべてアンダースコア (
_
) に置き換えます。環境ファイルの使用
現在の作業ディレクトリーに
.env
ファイルを作成し、設定プロパティーを追加します。<PROPERTY_KEY>
はプロパティー名に、<value>
はプロパティーの値に置き換えます。<PROPERTY_KEY>=<value>
注記開発モードでは、このファイルはプロジェクトの root ディレクトリーに置かれますが、バージョン管理でファイルを追跡しないことが推奨されます。プロジェクトのルートディレクトリーに
.env
ファイルを作成する場合は、プログラムがプロパティーとして読み取るキーおよび値を定義できます。application.properties
ファイルを使用します。アプリケーションが実行される
$PWD/config/application.properties
ディレクトリーに設定ファイルを配置し、そのファイルに定義されたランタイムプロパティーがデフォルト設定を上書きできるようにします。注記開発モードで
config/application.properties
機能を使用することもできます。config/application.properties
をtarget
ディレクトリーに配置します。ビルドツールからのクリーニング操作 (例:mvn clean
) は、config
ディレクトリーも削除します。
第7章 プロパティー式
プロパティー式は、設定内のプロパティーの値を置き換えるために使用できるプロパティー参照とプレーンテキスト文字列の組み合わせになります。
変数と同様に、Quarkus でプロパティー式を使用して、設定プロパティーの値をハードコーディングする代わりに置き換えることができます。プロパティー式は、java.util.Properties
がアプリケーションの設定ソースからプロパティーの値を読み取ると解決されます。
これは、コンパイル時に設定プロパティーが設定から読み取られる場合に、プロパティー式もコンパイル時に解決されることを意味します。設定プロパティーがランタイム時にオーバーライドされる場合、その値はランタイム時に解決されます。
プロパティー式は、複数の設定ソースを使用して解決できます。これは、ある設定ソースで定義されているプロパティーの値を使用して、別の設定ソースで使用するプロパティー式を拡張できることを意味します。
式のプロパティーの値を解決できず、式のデフォルト値を設定しない場合は、アプリケーションで NoSuchElementException
が発生します。
7.1. プロパティー式の使用例
このセクションでは、Quarkus アプリケーションを設定する際に、プロパティー式を使用して柔軟性を高める方法の例を紹介します。
設定プロパティーの値の置き換え:
プロパティー式を使用して、設定でプロパティー値のハードコーディングを回避できます。以下の例のように、
${<property_name>}
構文を使用して、設定プロパティーを参照する式を作成します。application.properties
remote.host=quarkus.io callable.url=https://${remote.host}/
callable.url
プロパティーの値はhttps://quarkus.io/
に解決されます。特定の設定プロファイルに固有のプロパティー値の設定:
以下の例では、
%dev
設定プロファイルとデフォルトの設定プロファイルは、異なるホストアドレスでデータソース接続 URL を使用するように設定されます。アプリケーションを起動する設定プロファイルに応じて、データソースドライバーは、プロファイルに設定したデータベース URL を使用します。application.properties
%dev.quarkus.datasource.jdbc.url=jdbc:mysql://localhost:3306/mydatabase?useSSL=false quarkus.datasource.jdbc.url=jdbc:mysql://remotehost:3306/mydatabase?useSSL=false
設定プロファイルごとにカスタム
application.server
プロパティーの異なる値を設定することにより、同じ結果を簡単な方法で実現できます。次に、例に示すように、アプリケーションのデータベース接続 URL でプロパティーを参照できます。application.properties
%dev.application.server=localhost application.server=remotehost quarkus.datasource.jdbc.url=jdbc:mysql://${application.server}:3306/mydatabase?useSSL=false
application.server
プロパティーは、アプリケーションの実行時に選択するプロファイルに応じて適切な値に解決されます。プロパティー式のデフォルト値の設定:
プロパティー式のデフォルト値を定義できます。Quarkus は、式を展開するために必要なプロパティーの値が設定ソースのいずれからも解決されない場合に、デフォルト値を使用します。次の構文を使用して、式のデフォルト値を設定できます。
${<expression>:<default_value>}
以下の例では、データソース URL のプロパティー式は、
application.server
プロパティーのデフォルト値としてmysql.db.server
を使用します。application.properties
quarkus.datasource.jdbc.url=jdbc:mysql://${application.server:mysql.db.server}:3306/mydatabase?useSSL=false
プロパティー式のネスト化:
プロパティー式を別のプロパティー式内にネスト化することで、プロパティー式を作成できます。ネスト化されたプロパティー式が展開されると、内部の式が最初に展開されます。
${<outer_property_expression>${<inner_property_expression>}}
複数のプロパティー式:
以下に示すように、2 つ以上のプロパティー式を結合することができます。
${<first_property>}${<second_property>}
プロパティー式と環境変数の組み合わせ:
プロパティー式を使用して、環境変数の値を置き換えることができます。以下の例の式は、
HOST
環境変数に設定される値をapplication.host
プロパティーの値として置き換えます。HOST
環境変数が設定されていない場合、application.host
はremote.host
プロパティーの値をデフォルトとして使用します。application.properties
remote.host=quarkus.io application.host=${HOST:${remote.host}}
第8章 設定プロファイルの使用
お使いの環境に応じて、異なる設定プロファイルを使用できます。設定プロファイルを使用すると、同じファイルに複数の設定を含めることができ、プロファイル名を使用してそれらを選択できます。Red Hat ビルドの Quarkus には 3 つの設定プロファイルがあります。さらに、独自のカスタムプロファイルを作成することもできます。
Quarkus のデフォルトプロファイル
- dev: 開発モードでのアクティブ化
- test: テストの実行時のアクティブ化
- prod: 開発またはテストモードで実行されていない場合のデフォルトプロファイル
前提条件
- Quarkus Maven プロジェクトがある。
手順
Java リソースファイルを開き、以下のインポートステートメントを追加します。
import io.quarkus.runtime.configuration.ProfileManager;
現在の設定プロファイルを表示するには、
ProfileManager.getActiveProfile()
メソッドを呼び出すログを追加します。LOGGER.infof("The application is starting with profile `%s`", ProfileManager.getActiveProfile());
注記@ConfigProperty("quarkus.profile")
メソッドを使用して、現在のプロファイルにアクセスすることはできません。
8.1. カスタム設定プロファイルの設定
設定プロファイルは、必要なだけ作成できます。同じファイルに複数の設定を含めることができ、プロファイル名を使用してそれらを選択できます。
手順
カスタムプロファイルを設定するには、
application.properties
ファイルのプロファイル名で設定プロパティーを作成します。<key>
はプロパティー名に、<value>
はプロパティーの値に、そして<profile>
はプロファイル名に置き換えます。%<profile>.<key>=<value>
以下の設定例では、
quarkus.http.port
の値はデフォルトで 9090 で、dev
プロファイルがアクティブ化されると 8181 になります。quarkus.http.port=9090 %dev.quarkus.http.port=8181
プロファイルを有効にするには、以下のいずれかの方法を使用します。
quarkus.profile
システムプロパティーを設定します。quarkus.profile
システムプロパティーを使用してプロファイルを有効にするには、以下のコマンドを入力します。mvn -Dquarkus.profile=<value> quarkus:dev
QUARKUS_PROFILE
環境変数を設定します。環境変数を使用してプロファイルを有効にするには、以下のコマンドを入力します。
export QUARKUS_PROFILE=<profile>
注記システムプロパティーの値は環境変数の値よりも優先されます。
アプリケーションを再パッケージしてプロファイルを変更するには、以下のコマンドを入力します。
./mvnw package -Dquarkus.profile=<profile> java -jar target/myapp-runner.jar
以下の例は、
prod-aws
プロファイルをアクティブ化するコマンドを示しています。./mvnw package -Dquarkus.profile=prod-aws java -jar target/myapp-runner.jar
デフォルトの Quarkus アプリケーションのランタイムプロファイルは、アプリケーションのビルドに使用されるプロファイルに設定されます。Red Hat ビルドの Quarkus は、環境モードに応じてプロファイルを自動的に選択します。たとえば、JAR としてアプリケーションを実行中の場合、Quarkus は prod
モードになります。
第9章 カスタム設定ソースの設定
デフォルトで、Quarkus アプリケーションはプロジェクトの src/main/resources
サブディレクトリー内の application.properties
ファイルからプロパティーを読み取ります。ただし、Quarkus は MicroProfile 設定をサポートしているため、他のソースからアプリケーションの設定を読み込むこともできます。org.eclipse.microprofile.config.spi.ConfigSource
および org.eclipse.microprofile.config.spi.ConfigSourceProvider
インターフェイスを実装するクラスを提供することで、設定した値にカスタム設定ソースを導入できます。以下の手順では、Quarkus プロジェクトにカスタム設定ソースを実装する方法を説明します。
前提条件
-
Quarkus
config-quickstart
プロジェクトがある。
手順
プロジェクト内に
ExampleConfigSourceProvider.java
ファイルを作成し、以下のインポートを追加します。src/main/java/org/acme/config/ExampleConfigSourceProvider.java
package org.acme.config; import java.util.Collections; import java.util.HashMap; import java.util.Map; import java.util.Set; import org.eclipse.microprofile.config.spi.ConfigSource; import org.eclipse.microprofile.config.spi.ConfigSourceProvider;
org.eclipse.microprofile.config.spi.ConfigSourceProvider
インターフェイスを実装するクラスを作成します。そのgetConfigSources
メソッドを上書きし、ConfigSource
オブジェクトの一覧を返します。以下の例は、
ConfigSourceProvider
およびConfigSource
インターフェイスのカスタム実装を示しています。src/main/java/org/acme/config/ExampleConfigSourceProvider.java
public class ExampleConfigSourceProvider implements ConfigSourceProvider { private final int times = 2; private final String name = "example"; private final String value = "value"; @Override public Iterable<ConfigSource> getConfigSources(ClassLoader forClassLoader) { InMemoryConfigSource configSource = new InMemoryConfigSource(Integer.MIN_VALUE, "example config source"); for (int i = 0; i < this.times; i++) { configSource.add(this.name + ".key" + (i + 1), this.value + (i + 1)); } return Collections.singletonList(configSource); } private static final class InMemoryConfigSource implements ConfigSource { private final Map<String, String> values = new HashMap<>(); private final int ordinal; private final String name; private InMemoryConfigSource(int ordinal, String name) { this.ordinal = ordinal; this.name = name; } public void add(String key, String value) { values.put(key, value); } @Override public Map<String, String> getProperties() { return values; } @Override public Set<String> getPropertyNames() { return values.keySet(); } @Override public int getOrdinal() { return ordinal; } @Override public String getValue(String propertyName) { return values.get(propertyName); } @Override public String getName() { return name; } } }
プロジェクトの
src/main/resources/META-INF/services/
サブディレクトリーにorg.eclipse.microprofile.config.spi.ConfigSourceProvider
という名前のファイルを作成し、作成したファイルにConfigSourceProvider
を実装するクラスの完全修飾名をファイルに入力します。src/main/resources/META-INF/services/org.eclipse.microprofile.config.spi.ConfigSourceProvider
org.acme.config.ExampleConfigSourceProvider
アプリケーションをコンパイルして起動する際に、作成した
ConfigSourceProvider
が登録およびインストールされていることを確認するには、この手順を実行する必要があります。以下のコマンドを入力して、開発モードでアプリケーションをコンパイルして起動します。
./mvnw quarkus:dev
/greeting
エンドポイントが想定されるメッセージを返すことを確認するには、新しいターミナルウィンドウに以下のコマンドを入力します。curl http://localhost:8080/greeting
アプリケーションがカスタム設定を正しく読み取ると、以下の応答が返されます。
hello quarkus!
第10章 カスタム設定コンバーターの設定値としての使用
org.eclipse.microprofile.config.spi.Converter<T>
を実装し、その完全修飾クラス名を META-INF/services/org.eclipse.microprofile.config.spi.Converter
に追加することで、カスタムタイプを設定値として保存できます。
前提条件
-
config-quickstart
プロジェクトを作成している。
手順
以下の例に示すように、
META-INF/services/org.eclipse.microprofile.config.spi.Converter
サービスファイルにコンバーターの完全修飾クラス名を含めます。org.acme.config.MicroProfileCustomValueConverter org.acme.config.SomeOtherConverter org.acme.config.YetAnotherConverter
converter クラスを実装し、convert メソッドを上書きします。
package org.acme.config; import org.eclipse.microprofile.config.spi.Converter; public class MicroProfileCustomValueConverter implements Converter<MicroProfileCustomValue> { @Override public MicroProfileCustomValue convert(String value) { return new MicroProfileCustomValue(Integer.valueOf(value)); } }
注記カスタムコンバータークラスは
public
で、引数なしのコンストラクターpublic
がなければなりません。カスタムコンバータークラスはabstract
であってはなりません。カスタムタイプを設定値として使用します。
@ConfigProperty(name = "configuration.value.name") MicroProfileCustomValue value;
10.1. カスタムコンバーターの優先度の設定
すべての Quarkus コアコンバーターのデフォルト優先度は 200 で、他のすべてのコンバーターは 100 です。ただし、javax.annotation.Priority
アノテーションを使用してカスタムコンバーターにより高い優先度を設定できます。
以下の手順は、優先度が 150 に割り当てられたカスタムコンバーター MicroProfileCustomValue
の実装を説明しています。これは、優先度が 100 である MicroProfileCustomValueConverter
よりも優先されます。
前提条件
-
config-quickstart
プロジェクトを作成している。
手順
以下のインポートステートメントをサービスファイルに追加します。
package org.acme.config; import javax.annotation.Priority; import org.eclipse.microprofile.config.spi.Converter;
クラスに
@Priority
アノテーションを付け、優先度の値を渡して、カスタムコンバーターの優先度を設定します。@Priority(150) public class MyCustomConverter implements Converter<MicroProfileCustomValue> { @Override public MicroProfileCustomValue convert(String value) { final int secretNumber; if (value.startsFrom("OBF:")) { secretNumber = Integer.valueOf(SecretDecoder.decode(value)); } else { secretNumber = Integer.valueOf(value); } return new MicroProfileCustomValue(secretNumber); } }
注記新しいコンバーターを追加する場合は、
META-INF/services/org.eclipse.microprofile.config.spi.Converter
サービスファイルにリストする必要があります。
第11章 YAML 設定サポートの追加
Red Hat ビルドの Quarkus は、Eclipse MicroProfile Config の SmallRye Config
実装により YAML 設定ファイルをサポートします。Quarkus Config YAML
エクステンションを追加し、プロパティーの代わりに YAML を使用して設定することができます。Quarkus は、application.yml
および application.yaml
を YAML ファイルの名前として使用することをサポートします。
YAML 設定ファイルは、application.properties
ファイルよりも優先されます。推奨される方法は、application.properties
ファイルを削除し、エラーを回避するために 1 種類のみの設定ファイルを使用することです。
手順
以下の方法のいずれかを使用して、プロジェクトに YAML エクステンションを追加します。
pom.xml
ファイルを開き、quarkus-config-yaml
エクステンションを依存関係として追加します。<dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-config-yaml</artifactId> </dependency>
コマンドラインから
quarkus-config-yaml
エクステンションを追加するには、プロジェクトディレクトリーから以下のコマンドを入力します。./mvnw quarkus:add-extension -Dextensions="quarkus-config-yaml"
11.1. YAML を使用したネストされたオブジェクト設定の使用
既存のクラス内でネストされたクラスを定義できます。この手順では、YAML 形式の設定ファイルを使用して、Quarkus アプリケーションのネスト化された設定プロパティーを設定する方法を示します。
前提条件
- Quarkus Maven プロジェクトがある。
- PostgreSQL データソースがある。
プロジェクトの
pom.xml
ファイルの依存関係として、以下のエクステンションがある。-
quarkus-rest-client
-
quarkus-jdbc-postgresql
-
quarkus-config-yaml
-
手順
-
src/main/resources/application.yaml
設定ファイルを開きます。 以下の例のように、ネストされたクラス設定プロパティーを
application.yaml
ファイルに追加します。src/main/resources/application.yaml
# Properties that configure the JDBC data source driver of your PostgreSQL data source quarkus: datasource: url: jdbc:postgresql://localhost:5432/some-database driver: org.postgresql.Driver username: quarkus password: quarkus # Property that configures the URL of the endpoint to which the rest client sends requests org: acme: restclient: CountriesService/mp-rest/url: https://restcountries.eu/rest # Property that configures the log message level for your application quarkus: log: category: # Do not use spaces in names of configuration properties that you place inside quotation marks "io.quarkus.category": level: INFO
コメントを使用して、
application.properties
で使用する場合と同じ方法で設定プロパティーを記述できることに留意してください。注記YAML 設定ファイル内のプロパティーをインデントするには、常にスペースを使用してください。YAML では、インデントにタブを使用できません。
11.2. YAML を使用したカスタム設定プロファイルの設定
Quarkus を使用すると、アプリケーションのさまざまな設定プロファイルに固有の設定プロパティーと値を設定できます。特定のプロファイルを使用してアプリケーションを起動し、特定の設定にアクセスできます。この手順では、YAML 形式で特定のプロファイルの設定を提供する方法を示します。
前提条件
- JDBC データソースドライバーで PostgreSQL データソースを使用するように設定された Quarkus Maven プロジェクトがある。
-
プロジェクトの
pom.xml
ファイルの依存関係としてquarkus-jdbc-postgresql
およびquarkus-config-yaml
エクステンションがある。
手順
-
src/main/resources/application.yaml
設定ファイルを開きます。 プロファイル依存設定を設定するには、
"%<profile_name>"
構文を使用してキーと値のペアを定義する前にプロファイル名を追加します。プロファイル名は必ず引用符で囲んでください。YAML では、特殊文字で始まるすべての文字列を引用符で囲む必要があります。以下の例では、開発モードで Quarkus アプリケーションを起動する際に、PostgreSQL データベースを
jdbc:postgresql://localhost:5432/some-database
URL で利用できるように設定されています。src/main/resources/application.yaml
"%dev": # Properties that configure the JDBC data source driver of your PostgreSQL data source quarkus: datasource: url: jdbc:postgresql://localhost:5432/some-database driver: org.postgresql.Driver username: quarkus password: quarkus
11.3. 設定キーの競合の管理
YAML などの構造化形式は、Configuration 名前空間の候補のサブセットのみをサポートします。以下の手順は、2 つの設定プロパティー (quarkus.http.cors
および quarkus.http.cors.methods
) における競合の解決方法を示しています。ここで、1 つのプロパティーはもう 1 つのプロパティーの接頭辞になります。
前提条件
- YAML 設定ファイルを読み取るように Quarkus プロジェクトが設定されている。
手順
- YAML 設定ファイルを開きます。
YAML プロパティーを別のプロパティーの接頭辞として定義するには、以下の例に示すようにプロパティーの範囲にティルデ (
~
) を追加します。quarkus: http: cors: ~: true methods: GET,PUT,POST
開発モードで Quarkus アプリケーションをコンパイルするには、プロジェクトディレクトリーから以下のコマンドを入力します。
./mvnw quarkus:dev
注記YAML キーは設定プロパティー名のアセンブリーに含まれないため、任意のレベルの競合する設定キーに使用できます。
第12章 機能テストの更新による設定の変更の検証
アプリケーションの機能をテストする前に、アプリケーションのエンドポイントに加えた変更を反映するように機能テストを更新する必要があります。以下の手順では、Quarkus config-quickstart
プロジェクトで testHelloEndpoint
メソッドを更新する方法を説明します。
手順
-
GreetingResourceTest.java
ファイルを開きます。 testHelloEndpoint
メソッドの内容を更新します。package org.acme.config; import io.quarkus.test.junit.QuarkusTest; import org.junit.jupiter.api.Test; import static io.restassured.RestAssured.given; import static org.hamcrest.CoreMatchers.is; @QuarkusTest public class GreetingResourceTest { @Test public void testHelloEndpoint() { given() .when().get("/greeting") .then() .statusCode(200) .body(is("hello quarkus!")); // Modified line } }
第13章 Quarkus アプリケーションのパッケージ化および実行
Quarkus プロジェクトをコンパイルしたら、JAR ファイルでパッケージ化し、コマンドラインから実行できます。
前提条件
- Quarkus プロジェクトをコンパイルしている。
手順
Quarkus プロジェクトをパッケージ化するには、
root
ディレクトリーで以下のコマンドを入力します。./mvnw clean package
このコマンドは、以下の JAR ファイルを
/target
ディレクトリーに生成します。-
config-quickstart-1.0-SNAPSHOT.jar
: プロジェクトのクラスおよびリソースが含まれます。これは、Maven ビルドで生成される通常のアーティファクトです。 -
config-quickstart-1.0-SNAPSHOT-runner.jar
: 実行可能な JAR ファイルです。依存関係はtarget/lib
ディレクトリーにコピーされるため、このファイルは uber-JAR ファイルではない点に注意してください。
-
- 開発モードを実行している場合は、CTRL+C を押して開発モードを停止します。停止しないと、ポートの競合が発生します。
アプリケーションを実行するには、以下のコマンドを入力します。
java -jar target/config-quickstart-1.0-SNAPSHOT-runner.jar
注記runner
JAR ファイルからのMANIFEST.MF
ファイルのClass-Path
エントリーは、lib
ディレクトリーからの JAR ファイルを明示的に記述します。別の場所からアプリケーションをデプロイする場合は、runner
JAR ファイルとlib
ディレクトリーをコピーする必要があります。
第14章 関連情報
改訂日時: 2023-05-16