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

Quarkusアプリケーションの再オーグメンテーション

オーグメンテーションとは?

Quarkusのアプリケーション設定には、2種類の設定オプションがあります。

  • ビルドタイムオプション:アプリケーションのビルド時に処理されます。

  • ランタイムオプション:アプリケーションがビルドされた後、起動する前に調整することができます。

オーグメンテーションとは、アプリケーションのビルドプロセスの段階で、アプリケーションのバイトコードがアプリケーションのビルド時の設定に応じて最適化されることです。EARファイルがJakarta EEサーバーにデプロイされるときに行われていた初期化ステップ(静的設定のパース、プロキシ・インスタンスの作成など)が、オーグメンテーション時に行われるようになりました。オーグメンテーション後に追加されたCDI Beanは(プロキシクラスがないため)動作しませんし、オーグメンテーション後に変更されたビルド時のプロパティ(例: quarkus.datasource.db-kind )は無視されます。ビルド時のプロパティは、 すべての設定オプションのリストでロックアイコン () が付いています。プロファイルやその他の方法でプロパティを上書きしても関係ありません。オーグメンテーション時に有効だったビルド時のプロパティは、ビルドに焼き付けられます。

再オーグメンテーションとは、オーグメンテーション出力を異なるビルド時の設定で再作成するプロセスです。

どのような場合に再オーグメンテーションが有効ですか?

再オーグメンテーションは、アプリケーションのユーザーがビルド時のプロパティの一部を変更できるようにしたい場合に便利です。例えば、データベースドライバの変更や、機能のオン/オフ(例: opentracingconsul-config)などです。ユーザー環境に依存するビルド時のプロパティが2つか3つしかない場合は、アプリケーションの代替ビルドの提供を検討してもよいでしょう。しかし、プロパティが多い場合には、代わりに変更可能なjarを出荷し、ユーザーが自分の環境に合わせてアプリケーションを再オーグメンテーションすることを好むかもしれません。なお、パッケージタイプ mutable-jar では、ネイティブイメージを使用することはできません。その結果と、他にどんな選択肢があるかを考えてみてください。

サーバーの起動に数分かかり、準備が整うまでコーヒーを楽しむことができた古き良き時代を懐かしむのでなければ、実行時に再オーグメンテーションを行うのは得策ではありません。

Quarkusのアプリケーションを再オーグメンテーションする方法

オーグメンテーションステップを実行するためには、使用されるQuarkusエクステンションのデプロイメントJARが必要です。これらのJARは、 mutable-jar のディストリビューションにのみ含まれています。つまり、 quarkus.package.type=mutable-jar でアプリケーションを構築する必要があります。 mutable-jar ディストリビューションは、 fast-jar ディストリビューションと同じですが、追加のフォルダ quarkus-app/lib/deployment には、デプロイメントJARとその依存関係(およびクラスローダの設定)が含まれています。

デフォルトでは、ビルド時プロパティが実行時に変更された場合、警告が表示されます。 quarkus.configuration.build-time-mismatch-at-runtime=fail プロパティを設定して、不一致があった場合にアプリケーションが起動しないようにすることもできます。しかし、この記事を書いている時点では、実行時に quarkus.datasource.db-kind を変更しても、失敗することも警告が出ることもなく、静かに無視されました。

1. mutable-jar として、アプリケーションを構築します。

mvn clean install -Dquarkus.package.type=mutable-jar

2. ビルド時の設定を変えて、アプリケーションを再ビルドする

異なるビルド時のプロパティでQuarkusアプリケーションを再オーグメンテーションするには、目的の設定に加えて、 quarkus.launch.rebuild システムプロパティを true に設定してアプリケーションを起動します。

次の例では、 quarkus.datasource.db-kindmysql に変更しています。これを実行するには、 mysql-extension がビルドに含まれている必要があります。オーグメンテーションは、コンパイル時に存在していたエクステンションのみを使用することができます。

java -jar -Dquarkus.launch.rebuild=true -Dquarkus.datasource.db-kind=mysql target/quarkus-app/quarkus-run.jar
システムプロパティ、環境変数、プロファイル、外部の設定ファイルのどれを使っても構いません。現在の設定がオーグメンテーションに使用されます( quarkus-app/quarkus の内容は、新しいオーグメンテーション出力に置き換えられます)。上記のコマンドラインでは、アプリケーションは起動しません。アプリケーションが再オーグメンテーションされた後、Quarkusは直ちに終了します。

3. オプション: deployments フォルダの削除

ZIP配布やDockerイメージのスペースを節約するために、 quarkus-app/lib/deployment ディレクトリを削除しても構いません(不要なレイヤーを避けるために、多段階のDockerビルドを使用することを忘れないでください)。 deployment ディレクトリを削除すると、当然ながらアプリケーションの再オーグメンテーションはできなくなります。