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

アプリケーションの設定

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

コードの中にハードコードされた値を使うことは できません (たとえ誰もがどこかの時点でそうしていたとしてもです ;-)。このガイドでは、Quarkusアプリケーションを設定する方法を学びます。

前提条件

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

  • 約15分

  • IDE

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

  • Apache Maven 3.9.6

  • 使用したい場合は、 Quarkus CLI

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

ソリューション

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

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

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

Maven プロジェクトの作成

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

コマンドラインインタフェース
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:3.8.3:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=config-quickstart \
    -Dextensions='resteasy-reactive' \
    -DnoCode
cd config-quickstart

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

Windowsユーザーの場合:

  • cmdを使用する場合、(バックスラッシュ \ を使用せず、すべてを同じ行に書かないでください)。

  • Powershellを使用する場合は、 -D パラメータを二重引用符で囲んでください。例: "-DprojectArtifactId=config-quickstart"

以下が生成されます:

  • 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 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 だけを使用することもできます。 @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 このプロパティに値を指定しない場合、アプリケーションの起動は 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;
}
@io.smallrye.config.ConfigMapping アノテーションを使用して、複数の設定を1つのインターフェイスにまとめます。 Config Mappings のドキュメントを参照してください。

環境プロパティファイルへのシークレットの保存

シークレット(パスワード、個人用アクセストークン、APIキーなど)は、セキュリティ上の理由から、バージョン管理には置いてはいけません。 一つの方法は、ローカル環境のプロパティ ( .env ) ファイルに保存することです:

  1. プロジェクト・ルート・ディレクトリの .env ファイルにシークレットを保存します。

    .envファイル
    foo.api-key=ThisIsSecret
  2. .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
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

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

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

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

コマンドラインインタフェース
quarkus build
Maven
./mvnw install
Gradle
./gradlew build

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

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

コマンドラインインタフェース
quarkus build --native
Maven
./mvnw install -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

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

  • 親プロファイル

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

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

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

  • ロギング

  • シークレットを隠す

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

関連コンテンツ