Configuring Your Application

本指南的内容已修订并拆分为其他主题。请查看 Additional Information 部分。

你代码中的硬编码值是一个 no-go（即使我们都曾经在某个时间点这样做过 ;-))。在本指南中，我们将学习如何配置 Quarkus 应用程序。

Prerequisites

如要完成本指南，您需要：

  • Roughly 15 minutes

  • An IDE

  • 安装了 JDK 17+，已正确配置 JAVA_HOME

  • Apache Maven ${proposed-maven-version}

  • 如果你想使用 Quarkus CLI, 则可以选择使用

  • 如果你想构建一个本机可执行文件（或如果你使用本机容器构建，则使用 Docker），则可以选择安装 Mandrel 或 GraalVM 以及 configured appropriately

Solution

我们建议您遵循接下来的部分中的说明，按部就班地创建应用程序。然而，您可以直接跳到完成的示例。

克隆 Git 存储库： git clone $${quickstarts-base-url}.git，或下载 $${quickstarts-base-url}/archive/main.zip[存档]。

可以在 config-quickstart directory 中找到解决方案。

Create the Maven project

首先，我们需要一个新项目。使用以下命令创建一个新项目：

CLI
quarkus create app {create-app-group-id}:{create-app-artifact-id} \
    --no-code
cd {create-app-artifact-id}

要创建一个 Gradle 项目，添加 --gradle 或 --gradle-kotlin-dsl 选项。 有关如何安装和使用 Quarkus CLI 的详细信息，请参见 Quarkus CLI 指南。

Maven
mvn {quarkus-platform-groupid}:quarkus-maven-plugin:{quarkus-version}:create \
    -DprojectGroupId={create-app-group-id} \
    -DprojectArtifactId={create-app-artifact-id} \
    -DnoCode
cd {create-app-artifact-id}

要创建一个 Gradle 项目，添加 -DbuildTool=gradle 或 -DbuildTool=gradle-kotlin-dsl 选项。

适用于 Windows 用户：

  • 如果使用 cmd，（不要使用反斜杠 \ ，并将所有内容放在同一行上）

  • 如果使用 Powershell，将 -D 参数用双引号引起来，例如 "-DprojectArtifactId={create-app-artifact-id}"

它生成：

  • the Maven structure

  • 一个可通过 http://localhost:8080 访问的登陆页面

  • 针对 native 和 jvm 模式的 Dockerfile 示例文件

  • the application configuration file

Create the configuration

Quarkus 应用程序使用 SmallRye Config API 提供与配置相关的全部机制。

默认情况下，Quarkus 会从 several sources 读取配置属性。为指引起见，我们将使用位于 src/main/resources/application.properties 的应用程序配置文件。

使用以下内容编辑此文件：

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

Create a REST resource

使用以下内容创建 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";
    }
}

Inject the configuration

Quarkus 使用 MicroProfile Config 注释，向应用程序中注入配置属性。

@ConfigProperty(name = "greeting.message") 1
String message;
1 你可以使用 @Inject @ConfigProperty 或只是 @ConfigProperty。对于使用 @ConfigProperty 注释的成员，不必使用 @Inject 注释。

如果应用程序试图注入一个未设置的配置属性，将抛出错误。

编辑 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 注释，在单个界面中对多个配置进行分组。请查看 Config Mappings 文档。

Store secrets in an environment properties file

出于安全考虑，不得在版本控制中保留机密（例如密码、个人访问令牌或 API 密钥）。一种方法是将它们存储在本地环境属性（.env）文件中：

  1. 在项目根目录中，将机密存储在 .env 文件中。[source, properties] .The .env file

foo.api-key=ThisIsSecret

  1. 将 .env 文件添加到 .gitignore。

mvn quarkus:dev 会自动提取 .env 文件中的属性，类似于 application.properties 文件中的属性。

Update the test

我们还需要更新功能测试以反映对端点所做的更改。使用以下内容创建 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
    }

}

Package and run the application

使用以下内容运行应用程序：

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

用浏览器打开 [role="bare"][role="bare"]http://localhost:8080/greeting.

更改配置文件会立即反映出来。您可以添加 greeting.suffix、删除其他属性、更改值等。

和往常一样，可以使用以下命令打包应用程序：

CLI
quarkus build
Maven
./mvnw install
Gradle
./gradlew build

并使用 java -jar target/quarkus-app/quarkus-run.jar 执行。

你还可以按如下方式生成本机可执行文件：

CLI
quarkus build --native
Maven
./mvnw install -Dnative
Gradle
./gradlew build -Dquarkus.native.enabled=true

Programmatically access the configuration

org.eclipse.microprofile.config.ConfigProvider.getConfig() API 允许以编程方式访问配置 API。此 API 主要在 CDI 注入不可用的情况下有用。

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

Configuring Quarkus

Quarkus 本身使用与应用程序相同的机制进行配置。Quarkus 保留 quarkus. 命名空间用于自身配置。例如，要配置 HTTP 服务器端口，您可以在 application.properties 中设置 quarkus.http.port。所有 Quarkus 配置属性都是 documented and searchable。

如上所述，以 quarkus. 为前缀的属性实际上是保留用于配置 Quarkus 本身及其扩展的。因此，quarkus. 前缀应该 never 用于应用程序特定属性。

Build Time configuration

一些 Quarkus 配置仅在构建时生效，这意味着无法在运行时更改它们。这些配置在运行时仍然可用，但只读且对 Quarkus 行为没有影响。对这些配置的任何更改都要求重新构建应用程序本身才能反映此类属性的更改。

构建时固定的属性会在 list of all configuration options 中用锁图标 () 标记。

但是，一些扩展确实定义了属性 overridable at runtime。一个简单的例子是数据库 URL、用户名和密码，这些通常只在您的目标环境中知道，因此可以在运行时设置它们并影响应用程序的行为。

Additional Information

Quarkus 依赖于 SmallRye Config 并继承其特性：

  • Additional `ConfigSource`s

  • Additional `Converter`s

  • Indexed properties

  • Parent profile

  • 配置值解析拦截器

  • Relocate configuration properties

  • Fallback configuration properties

  • Logging

  • Hide secrets

欲了解更多信息，请查看 SmallRye Config documentation。