Configuring your application
| The content of this guide has been revised and split into additional topics. Please check the Additional Information section. |
コードの中にハードコードされた値を使うことは できません (たとえ誰もがどこかの時点でそうしていたとしてもです ;-)。このガイドでは、Quarkusアプリケーションを設定する方法を学びます。
前提条件
このガイドを完了するには、以下が必要です。
-
約15分
-
IDE
-
JDK 17+がインストールされ、
JAVA_HOMEが適切に設定されていること -
Apache Maven 3.9.16
-
使用したい場合は、 Quarkus CLI
-
ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること
ソリューション
次の章で紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。
git clone -b 3.40 https://github.com/quarkusio/quarkus-quickstarts.git で Git リポジトリーをクローンします。または、https://github.com/quarkusio/quarkus-quickstarts/archive/3.40.zip[アーカイブ] をダウンロードします。
ソリューションは config-quickstart ディレクトリ にあります。
Maven プロジェクトの作成
まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。
Windowsユーザーの場合:
-
cmdを使用する場合、(バックスラッシュ
\を使用せず、すべてを同じ行に書かないでください)。 -
Powershellを使用する場合は、
-Dパラメータを二重引用符で囲んでください。例:"-DprojectArtifactId=config-quickstart"
以下が生成されます:
-
maven構造
-
ランディングページは次のURLでアクセス可能です:
http://localhost:8080 -
nativeとjvmの両方のモードに対応したDockerfileファイルの例 -
アプリケーション設定ファイル
設定の作成
Quarkusアプリケーションは SmallRye Config APIを使用して、設定に関連するすべてのメカニズムを提供します。
デフォルトでは、Quarkusは 複数のソース から設定プロパティを読み込みます。
このガイドでは、 src/main/resources/application.properties にあるアプリケーション設定ファイルを使用します。
以下の内容でファイルを編集します:
# Your configuration properties
greeting.message=hello
greeting.name=quarkus
RESTリソースの作成
org.acme.config.GreetingResource REST リソースを以下の内容で作成します:
package org.acme.config;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
@Path("/greeting")
public class GreetingResource {
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
return "Hello RESTEasy";
}
}
設定の挿入
Quarkus は、 MicroProfile Config アノテーションを使用して、アプリケーションに設定プロパティーを注入します。
@ConfigProperty(name = "greeting.message") (1)
String message;
| 1 | @Inject @ConfigProperty または単に @ConfigProperty を使用できます。 @ConfigProperty が付与されたメンバーには、 @Inject アノテーションは必要ありません。 |
| If the application attempts to inject a configuration property that is not set, an error is thrown. |
org.acme.config.GreetingResource を編集し、以下の設定プロパティーを導入します:
@ConfigProperty(name = "greeting.message") (1)
String message;
@ConfigProperty(name = "greeting.suffix", defaultValue="!") (2)
String suffix;
@ConfigProperty(name = "greeting.name")
Optional<String> name; (3)
| 1 | このプロパティに値を指定しない場合、アプリケーションの起動は jakarta.enterprise.inject.spi.DeploymentException: No config value of type [class java.lang.String] exists for: greeting.message で失敗します。 |
| 2 | 設定で greeting.suffix の値が提供されない場合は、デフォルト値がインジェクトされます。 |
| 3 | このプロパティーはオプションです。設定で greeting.name の値が提供されない場合は、空の Optional がインジェクトされます。 |
ここで、 hello メソッドを修正して、注入されたプロパティーを使用します:
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
return message + " " + name.orElse("world") + suffix;
}
Use @io.smallrye.config.ConfigMapping annotation to group multiple configurations in a single interface. Please,
check the Config Mappings documentation.
|
環境プロパティファイルへのシークレットの保存
シークレット(パスワード、個人用アクセストークン、APIキーなど)は、セキュリティ上の理由から、バージョン管理には置いてはいけません。
一つの方法は、ローカル環境のプロパティ ( .env ) ファイルに保存することです:
-
プロジェクト・ルート・ディレクトリの
.envファイルにシークレットを保存します。The .env filefoo.api-key=ThisIsSecret -
.envファイルを.gitignoreに追加します。
mvn quarkus:dev は、 application.properties ファイルのプロパティと同様に、 .env ファイルのプロパティを自動的にピックアップします。
テストの更新
また、エンドポイントに加えられた変更を反映させるために、機能テストを更新する必要があります。 src/test/java/org/acme/config/GreetingResourceTest.java ファイルを以下の内容で作成します:
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
}
}
アプリケーションをパッケージ化して実行する
次のコマンドでアプリケーションを実行します。
quarkus dev
./mvnw quarkus:dev
./gradlew --console=plain quarkusDev
ブラウザで http://localhost:8080/greeting を開きます。
設定ファイルの変更はすぐに反映されます。 greeting.suffix の追加、他のプロパティーの削除、値の変更などが可能です。
いつものように、アプリケーションは以下の方法でパッケージ化されます。
quarkus build
./mvnw install
./gradlew build
そして次のように実行します java -jar target/quarkus-app/quarkus-run.jar 。
ネイティブ実行可能ファイルを生成することもできます:
quarkus build --native
./mvnw install -Dnative
./gradlew build -Dquarkus.native.enabled=true
設定にプログラムでアクセス
The org.eclipse.microprofile.config.ConfigProvider.getConfig() API allows access to the Config API programmatically.
This API is mostly useful in situations where CDI injection is not available.
String databaseName = ConfigProvider.getConfig().getValue("database.name", String.class);
Optional<String> maybeDatabaseName = ConfigProvider.getConfig().getOptionalValue("database.name", String.class);
Quarkus の設定
Quarkus 自体も、アプリケーションと同じメカニズムで設定されます。 Quarkus は、自身の設定のために quarkus. 名前空間を予約しています。例えば、 HTTP サーバーのポートを設定するには、 application.properties で quarkus.http.port を設定できます。すべての Quarkus 設定プロパティーは ドキュメント化されており検索可能 です。
|
上述のように、 |
ビルド時設定
Quarkusの設定の中には、ビルド時にのみ有効になるものがあり、ランタイムに変更することはできません。これらの設定はランタイムでも利用可能ですが、読み取り専用であり、Quarkusの動作には影響しません。これらの設定を変更するには、そのようなプロパティの変更を反映させる場合、アプリケーション自体を再ビルドする必要があります。
| The properties fixed at build time are marked with a lock icon () in the list of all configuration options. |
ただし、一部のエクステンションでは、 実行時に上書き可能な プロパティーを定義しています。簡単な例は、データベースの URL、ユーザー名、パスワードです。これらはターゲット環境ごとに固有のものであるため、実行時に設定してアプリケーションの動作に影響を与えることができます。
追加情報
Quarkus は SmallRye Config に依存しており、その機能を継承しています。
-
追加
ConfigSource -
追加
Converter -
インデックスされたプロパティ
-
親プロファイル
-
設定値解決のためのインターセプタ―
-
設定プロパティーの移動
-
設定プロパティーのフォールバック
-
ロギング
-
シークレットを隠す
詳しくは、SmallRye Configのドキュメント をご確認ください。