設定リファレンスガイド

デフォルトでは、Quarkus は複数のソースから設定プロパティーを読み取ります (降順)。

最終的な設定は、これらすべてのソースによって定義されたプロパティーの集約です。設定プロパティーのルックアップは、使用可能な最も高い序数の設定ソースから始まり、一致するものが見つかるまで他のソースに下がっていきます。つまり、上位の序数設定ソースに別の値を設定するだけで、設定プロパティーが値をオーバーライドする可能性があります。たとえば、環境プロパティーを使用して設定されたプロパティーは、 application.properties ファイルを使用して提供された値をオーバーライドします。

The recommended way to expose configuration to a Quarkus application is by mapping it with an interface. With SmallRye Config Mappings, it is possible to group multiple configuration properties in a single interface that share the same prefix (or namespace). It supports the following set of features:

A Config Mapping requires an interface with minimal metadata configuration annotated with @io.smallrye.config.ConfigMapping:

A complex object type uses the following rules to map configuration values to their member values:

The Server interface can map configuration properties with the name server.host into the Server.host() method, server.port into Server.port() method, and server.ssl-port into Server.sslPort() method. The configuration property name to look up is constructed from the prefix and the method name (in kebab-case), separated by adot (.) character.

A @ConfigMapping can be injected into any CDI aware bean:

For non-CDI components, use the io.smallrye.config.SmallRyeConfig#getConfigMapping API to retrieve the config mapping instance:

While @ConfigMapping is the recommended approach, Quarkus also supports MicroProfile Config annotations to inject the configuration properties in the application.

If a configuration is associated with a default value (by way of the io.smallrye.config.WithDefault or org.eclipse.microprofile.config.inject.ConfigProperty.defaultValue), and no configuration value is supplied for the property, then rather than throwing an exception, the default value will be used. A default value is expressed as a String, and uses the same conversion mechanism used to process configuration values. Several Built-in Converters already exist for primitives, boxed primitives, and other classes; for example:

ご想像のとおり、これらのコンバーターは org.eclipse.microprofile.config.spi.Converter の実装です。したがって、これらのコンバーターは、次のような Microprofile またはカスタム実装プロバイダーの式ルールに準拠しています。

Note that when a combination of Optional* types and defaults are used, the defined default value will still be used and if no value is given for the property, the Optional* will be present and populated with the converted default value. However, when the property is explicitly empty, the default value is not used and the Optional will be empty. Consider this example:

この場合、 greeting.name は上記の Optional* になるように設定されているため、対応するプロパティー値は空の Optional になり、実行は通常どおり続行されます。これは、デフォルト値が設定されている場合でも当てはまります。プロパティーが設定で明示的にクリアされている場合、デフォルト値は 使用されません。

一方、以下の例では、

起動時に java.util.NoSuchElementException: SRCFG02004: Required property greeting.message not found が発生し、デフォルト値は割り当てられません。

The io.smallrye.config.SmallRyeConfig API allows to access the Config API programmatically. This API is mostly useful in situations where CDI injection is not available.

私たちはしばしば、ターゲット 環境 に応じてアプリケーションを異なるように設定する必要があります。たとえば、ローカルの開発環境と本番環境は異なるかもしれません。

設定プロファイルでは、同じファイルまたは個別のファイルで複数の設定を行い、プロファイル名を使用してそれらから選択できます。

Quarkus は、設定値のプロパティー式拡張を提供します。式文字列は、プレーン文字列と式セグメントの組み合わせであり、シーケンス ${ …​ } でラップされます。

これらの式は、プロパティーの読み込み時に解決されます。したがって、設定プロパティーがビルド時である場合、プロパティー式はビルド時に解決されます。設定プロパティーが実行時にオーバーライド可能になると、実行時に解決されます。

以下だとすると、

callable.url プロパティーの解決された値は https://quarkus.io/ です。

別の例としては、プロファイルで異なるデータベースサーバーを定義できます。

次のように簡略化できます。

さらに、式拡張エンジンは次のセグメントをサポートします。

式を展開できず、デフォルトが指定されていない場合、 NoSuchElementException が出力されます。

シークレット設定は、 ${handler::value} と表現することができます。 handler は、 value を解読または復号するための io.smallrye.config.SecretKeysHandler の名前です :

my.secret を読み出すと、 aes-gcm-nopadding という名前の SecretKeysHandler を使って、値 DJNrZ6LfpupFv6QbXyXhvzD8eVDnDa_kTliQBpuzTobDZxlg がデコードされます。

詳しくは、SmallRye Config Secret Keys のドキュメントをご確認ください。

Quarkus のデフォルトの設定ソースはランダムな UUID 値を提供します。起動時に UUID を生成します。そのため、開発モードでのリロードを含め、スタートアップ間で値が変化します。

生成された値には、 quarkus.uuid プロパティーを使用してアクセスできます。アクセスするには、expressions を使用します (${quarkus.uuid})。たとえば、一意のコンシューマーグループを使用して Kafka クライアントを設定する場合に便利です。

任意であり、ビルド時に値が設定されていたり、デフォルト値が設定されていたりする実行時プロパティーは、空の文字列をプロパティーに代入することで明示的に削除することができます。これは実行時プロパティーに のみ 影響し、値が必須ではないプロパティーで のみ 動作することに注意してください。

-Dremote.host= を指定して remote.host を検索すると、システムプロパティーが値をクリアしたため、例外がスローされます。

エスケープされていないコンマを含む設定値は、 Collection に変換できます。これは単純なケースでは機能しますが、面倒になり、より高度なケースでは制限されます。

インデックス付きプロパティーは、設定プロパティー名のインデックスを使用して、 Collection タイプの特定の要素をマップする方法を提供します。インデックス付き要素はプロパティー名の一部であり、値に含まれていないため、これを使用して、複雑なオブジェクトタイプを Collection 要素としてマップすることもできます。以下の例の場合、

インデックス付きプロパティーの構文では、プロパティー名と大かっこ [ ] を使用し、その間にインデックスを付けます。

Config#getValues("my.collection", String.class) を呼び出すと、値 dog、 cat、および turtle が含まれる List<String> が自動的に作成および変換されます。 Config#getValues("my.indexed.collection", String.class) を呼び出すと、まったく同じ結果が返されます。同じプロパティー名が両方の形式 (通常およびインデックス付き) に存在する場合、通常の値が優先されます。

インデックス付きのプロパティーは、ターゲットの Collection に追加される前に、インデックスで並べ替えられます。インデックスに含まれるギャップはターゲットの Collection に解決されません。つまり、 Collection の結果にはギャップのないすべての値が格納されます。

Quarkus自体は、アプリケーションと同じメカニズムで設定されます。Quarkusは、自身の設定のために quarkus. 名前空間を予約します。例えば、HTTPサーバーポートを設定するには、 quarkus.http.port を application.properties に設定します。Quarkusのすべての設定プロパティは 文書化されており、検索可能です。

アプリケーションのビルド後にビルド時の設定を変更する必要があるというまれな状況にある場合は、再オーグメンテーション を使用して、別のビルド時設定のオーグメンテーション出力を再ビルドする方法を確認してください。

設定ソースは通常、ビルド中に実際に使用されるよりも多くのオプションを提供するため、Quarkusのビルドプロセスで実際に使用された設定オプションを知ることは有益です。

Quarkus は、静的初期化フェーズ で CDI Bean に注入された設定プロパティー値を収集します。 収集された値はランタイムの初期化値と比較され、不一致が検出されるとアプリケーションの起動は失敗します。 どうしてそんなことが起こるのでしょうか? たとえば、 org.acme.MyBean という CDI Bean があるとします。 MyBean は foo という名前の @ConfigProperty を注入し、ネイティブビルド中に初期化されます。 ネイティブビルド中は設定プロパティーが存在しないため、デフォルト値 bar が使用されます。 しかし、後でアプリケーションが起動されると、プロパティーはシステムプロパティー -Dfoo=baz で定義されます。 これにより、一貫性のない状態と予期しない動作が発生します。 したがって、この状況になると Quarkus はデフォルトで失敗します。

注入されたフィールド/パラメータに @io.quarkus.runtime.annotations.StaticInitSafe のアノテーションを付けることで、静的初期化フェーズで注入された設定オブジェクトを安全に初期化できるようにマークすることができます。

Quarkus は SmallRye Config に依存しており、その機能を継承しています。

詳しくは、 SmallRye Configのドキュメント をご確認ください。

ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは実行時にオーバーライド可能