設定リファレンスガイド

システムプロパティーは、起動時に -D フラグを介してアプリケーションに渡すことができます。次の例では、値 youshallnotpass を属性 quarkus.datasource.password に割り当てます。

環境変数名は、 MicroProfile Config で指定された変換ルールに従います。 Config は、指定されたプロパティ名に対して 3 つの環境変数を検索します (例: foo.BAR.baz )：

SmallRye Configでは、 追加の変換ルール を指定しています。

dev モードの場合、このファイルはプロジェクトのルートに置くことができるが、通常パスワードやアクセストークン、APIキーなどの秘密が含まれているため、バージョン管理にはチェックイン しない ことをお勧めします。

Quarkus アプリケーション設定ファイルは、クラスパスリソース (たとえば、 src/main/resources/application.properties、 src/test/resources/application.properties) から、または application.properties エントリーが含まれる jar 依存関係から読み込まれます。見つかった各 application.properties は個別の ConfigSource として扱われ、他のすべてのソースと同じルールに従います (プロパティーごとのオーバーライド)。さらに、設定ファイルは $PWD/config/application.properties に存在する場合もあります。読み込みは config フォルダーから始まり、次にクラスパスの順序になります (アプリケーションソース内の application.properties ファイルがクラスローダー読み込み順序で優先されます)。

src/main/resources/META-INF/microprofile-config.properties にある MicroProfile Config 設定ファイル。

Quarkus は、設定プロパティーファイルをデフォルトの設定場所だけでなく、別の場所でもスキャンするための方法を提供します。

quarkus.config.locations 設定プロパティーは、コンマ , で区切られた複数の場所を受け入れます。 場所は、それぞれ有効な URI を表す必要があります。サポートされている URI スキームは次のとおりです。

読み込まれたすべてのソースは、 quarkus.config.locations 設定プロパティーを見つけたソースと同じ序数を使用します。たとえば、 quarkus.config.locations がシステムプロパティーとして設定されている場合、ロードされたすべてのソースの序数は 400 に設定されています (システムプロパティーは序数として 400 を使用します)。序数は、 config_ordinal と序数値を設定することで、設定ソースごとに直接オーバーライドできます。 config_ordinal プロパティーは、設定されているソースの序数にのみ影響します。ソースは、まず序数でソートされ、次に場所の順序、最後に読み込み順序でソートされます。

Quarkus は、他の設定フォーマットとストアをカバーする追加のエクステンションを提供します。

プロパティが（ defaultValue 属性によって）デフォルト値と関連付けられ、そのプロパティに対して設定値が設定されない場合、 jakarta.enterprise.inject.spi.DeploymentException を投げるのではなく、デフォルト値が使用されます。 defaultValue 値は String として表現され、設定値の処理に使用されるのと同じ変換機構が使用されます。プリミティブ、ボックス化されたプリミティブ、その他のクラスには、すでにいくつかの組み込みコンバーターが存在します。例:

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

Optional* タイプと defaultValue 属性の組み合わせが使用される場合、定義された defaultValue が引き続き使用され、プロパティーに値が指定されていない場合、 Optional* が存在し、変換されたデフォルト値が入力されることに注意してください。ただし、プロパティーが明示的に空の場合、デフォルト値は使用されず、 Optional は空になります。この例を考えてみましょう。

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

一方、以下の例では、

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

以下は、Quarkus が提供するコンバーターの例です。

同じ名前のプロパティーを設定できるようにするには、各プロパティーは、 %{profile-name}.config.name の構文で、プロファイル名とドット . の前にパーセント記号 % を付ける必要があります。

Quarkus HTTP ポートは 9090 になります。 dev プロファイルがアクティブな場合、8181 になります。

.env ファイルのプロファイルは構文 _{PROFILE}_CONFIG_KEY=value に従います。

プロファイルが特定の属性の値を定義していない場合、デフォルト (プロファイルなし) の値が使用されます。

dev プロファイルを有効にすると、プロパティー bar の値は hallo になりますが、プロパティー baz の値は bonjour になります。 prod プロファイルが有効になっている場合、 bar の値は hello (` prod` プロファイルには特定の値がないため) であり、 baz の値は bonjour です。

デフォルトでは、Quarkus は 3 つのプロファイルを提供し、特定の条件で自動的にアクティブになります。

追加のプロファイルを作成し、 quarkus.profile 設定プロパティーを使用してそれらをアクティブ化することもできます。新しいプロファイル名を持つ単一の設定プロパティーが唯一の要件です。

quarkus.profile を staging に設定すると、 staging プロファイルがアクティブになります。

この場合、特定のプロファイルのプロパティは、 application-{profile}.properties という名前のファイルに格納されます。先ほどの例は次のように表現できます。

親プロファイルは、現在のプロファイルに 1 レベルの階層を追加します。設定 quarkus.config.profile.parent は、単一のプロファイル名を受け入れます。

親プロファイルがアクティブなときに、現在アクティブなプロファイルにプロパティーが見つからない場合、設定ルックアップは親プロファイルにフォールバックします。以下の例を考えてみます。

この場合、

複数のプロファイルを同時にアクティブにすることができます。 quarkus.profile 設定では、カンマで区切られたプロファイル名のリストを受け付けます: quarkus.profile=common,dev 。 common と dev はどちらも別のプロファイルです。

複数のプロファイルが有効な場合、プロファイル設定に関するルールは同じです。2つのプロファイルが同じ設定を定義している場合、最後にリストされたプロファイルが優先されます。と考えてください:

この場合、

また、プロファイル名をカンマで区切って、複数のプロファイルプロパティを定義することも可能です。同じプロパティ名が複数のプロファイルプロパティに存在する場合、最も具体的なプロファイルを持つプロパティ名が優先されます:

この場合、

デフォルトの Quarkus 実行時プロファイルは、アプリケーションのビルドに使用されるプロファイルに設定されます。

プロパティー式は環境変数でも機能します。

これは HOST 環境変数を展開し、 HOST が設定されていない場合は、プロパティー remote.host の値をデフォルト値として使用します。

Quarkus の設定の中には、ビルド時にのみ有効になるものがあり、ランタイムに変更することはできません。これらの設定はランタイムでも利用可能ですが、読み取り専用であり、Quarkus の動作には影響しません。これらの設定を変更してプロパティーの変更を反映させるには、アプリケーション自体を再ビルドする必要があります。

しかし、いくつかのエクステンションは 実行時にオーバーライド可能な プロパティーを定義しています。定型的な例としては、データベースの URL、ユーザー名とパスワードがあります。これはターゲット環境によって定まるものであり、実行時にセットされ、アプリケーションの動作に影響を与えるものです。

quarkus.config-tracking.enabled を true に設定すると、設定インターセプターが有効になり、ビルドプロセス中に読み込まれたすべての設定オプションを、その値とともに記録します。結果のレポートはデフォルトで ${project.basedir}/.quarkus/quarkus-prod-config-dump に保存されます。ターゲット・ファイルは以下のオプションで設定できます：

quarkus-prod-config-dump ファイル名の prod 部分は Quarkus ビルドモードを参照します。これは、ダンプが実稼働環境用のビルドのために取得されたことを示します。

${project.basedir}/.quarkus ディレクトリーがデフォルトの場所として選択された理由は、ビルド時におけるビルド間の設定変更を追跡しやすくするためです。出力キャッシュツール (Apache Maven Build Cache や Develocity Build Cache など) は、これを指標として使用することで、アプリケーションバイナリーを再構築する必要があるかどうかを判断できます。

quarkus.config-tracking.enabled は効果的なビルド時設定レポートの生成を有効にしますが、プロジェクトの次のビルドが開始される前に、そのレポートに保存されている値が変更されたかどうかを確認する方法もあります。

Maven プロジェクトでは、 quarkus-maven-plugin 設定に次のゴールを追加できます。

track-config-changes ゴールは ${project.basedir}/.quarkus/quarkus-prod-config-dump (ファイル名とディレクトリーは設定可能) を検索し、ファイルがすでに存在する場合は、設定ダンプに保存されている値が変更されているかどうかを確認します。 変更されたオプションを記録し、 ${project.basedir}/target/quarkus-prod-config.check (ターゲットファイル名と場所は設定可能) の ${project.basedir}/.quarkus/quarkus-prod-config-dump にある各オプションの現在の値を保存します。ビルド時の設定が前回のビルドから変更されていない場合は、 ${project.basedir}/.quarkus/quarkus-prod-config-dump と ${project.basedir}/.quarkus/quarkus-prod-config-dump はまったく同じになります。