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

アプリケーションの設定

本ガイドの内容を改訂し、さらにトピックを分割しました。追加情報をご覧ください。

Hardcoded values in your code are a no-go (even if we all did it at some point ;-)). In this guide, we will learn how to configure a Quarkus application.

前提条件

このガイドを完成させるには、以下が必要です:

  • 約15分

  • IDE

  • JDK 11+ がインストールされ、 JAVA_HOME が適切に設定されていること

  • Apache Maven 3.8.1+

  • 使用したい場合、 Quarkus CLI

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

ソリューション

次のセクションで紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。

Git レポジトリをクローンするか git clone https://github.com/quarkusio/quarkus-quickstarts.gitアーカイブ をダウンロードします。

ソリューションは config-quickstart ディレクトリ にあります。

Maven プロジェクトの作成

まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。

CLI
quarkus create app org.acme:config-quickstart \
    --extension=resteasy-reactive \
    --no-code
cd config-quickstart

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストール方法については、Quarkus CLIガイドをご参照ください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:2.11.1.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=config-quickstart \
    -Dextensions="resteasy-reactive" \
    -DnoCode
cd config-quickstart

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

以下が生成されます:

  • Maven の構造

  • ランディングページは次の URL でアクセス可能です: http://localhost:8080

  • nativejvm の両方のモードに対応した Dockerfile ファイルの例

  • アプリケーション設定ファイル

設定の作成

Quarkusアプリケーションは SmallRye Config APIを使用して、設定に関連するすべてのメカニズムを提供します。

デフォルトでは、Quarkus は 複数のソース から設定プロパティーを読み取ります。このガイドでは、 src/main/resources/application.properties にあるアプリケーション設定ファイルを使用します。以下の内容でファイルを編集します。

application.properties
# Your configuration properties
greeting.message = hello
greeting.name = quarkus

RESTリソースの作成

org.acme.config.GreetingResource REST リソースを以下の内容で作成します:

package org.acme.config;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.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 だけを使用することもできます。 @Inject アノテーションは、 @ConfigProperty でアノテーションされたメンバーには必要ありません。
アプリケーションが設定されていない設定プロパティーを注入しようとすると、エラーがスローされます。

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 このプロパティーに値を指定しないと、アプリケーションの起動は javax.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.

テストの更新

また、エンドポイントに加えられた変更を反映させるために、機能テストを更新する必要があります。 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
    }

}

アプリケーションをパッケージ化して実行する

アプリケーションを実行します:

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

ブラウザで http://localhost:8080/greeting を開きます。

設定ファイルの変更はすぐに反映されます。 greeting.suffix の追加、他のプロパティーの削除、値の変更などが可能です。

いつものように、アプリケーションは以下の方法でパッケージ化されます。

CLI
quarkus build
Maven
./mvnw clean package
Gradle
./gradlew build

そして次のコマンドで実行できます。 java -jar target/quarkus-app/quarkus-run.jar.

次のようにネイティブ実行可能ファイルを生成することもできます。

CLI
quarkus build --native
Maven
./mvnw package -Dnative
Gradle
./gradlew build -Dquarkus.package.type=native

設定にプログラムでアクセス

org.eclipse.microprofile.config.ConfigProvider.getConfig() APIを使用すると、Config APIにプログラムでアクセスすることができます。このAPIは、CDIインジェクションが利用できない状況で主に役立ちます。

String databaseName = ConfigProvider.getConfig().getValue("database.name", String.class);
Optional<String> maybeDatabaseName = ConfigProvider.getConfig().getOptionalValue("database.name", String.class);

Quarkus の設定

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

上述したように、 quarkus. で始まるプロパティーは、Quarkus 自体を設定するために実質的に予約されているため、アプリケーション固有のプロパティーのプレフィックスとして quarkus. を使用してはいけ ません

ビルド時設定

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

ビルド時に固定されたプロパティーは、 すべての設定オプションのリスト でロックアイコン () でマークされます。

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

追加情報

Quarkusアプリケーションは SmallRye Config に依存し、その機能を継承します:

  • 追加 ConfigSource

  • 追加 Converter

  • インデックスされたプロパティ

  • 親プロファイル

  • 設定値解決のためのインターセプタ―

  • 設定プロパティーの移動

  • 設定プロパティーのフォールバック

  • ロギング

  • シークレットを隠す

For more information, please check the SmallRye Config documentation.