返回指南
编辑此页面

配置您的应用程序

本指南的内容已修订并拆分为更多主题。请查看“其他信息”部分。

代码中的硬编码值是“禁忌”（尽管我们都曾在某个时候这样做过 ;-))。在本指南中，我们将学习如何配置 Quarkus 应用程序。

先决条件

要完成本指南，您需要

  • 大约 15 分钟

  • 一个 IDE

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

  • Apache Maven 3.9.9

  • 如果您想使用它，可以选择 Quarkus CLI

  • 如果您想构建本机可执行文件（或者如果您使用本机容器构建，则为 Docker），可以选择安装 Mandrel 或 GraalVM 并进行适当的配置

解决方案

我们建议您按照以下章节中的说明，逐步创建应用程序。但是，您可以直接转到完整的示例。

克隆 Git 仓库：git clone https://github.com/quarkusio/quarkus-quickstarts.git，或下载一个存档。

解决方案位于config-quickstart目录中。

创建 Maven 项目

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

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

要创建 Gradle 项目，请添加 --gradle 或 --gradle-kotlin-dsl 选项。

有关如何安装和使用 Quarkus CLI 的更多信息，请参阅 Quarkus CLI 指南。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.24.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=config-quickstart \
    -Dextensions='rest' \
    -DnoCode
cd config-quickstart

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

对于 Windows 用户

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

  • 如果使用 Powershell，请将 -D 参数用双引号括起来，例如 "-DprojectArtifactId=config-quickstart"

它生成

  • Maven 结构

  • 一个可以在 https://:8080 上访问的欢迎页面

  • 用于 native 和 jvm 模式的示例 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。对于用 @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 文档。

将秘密存储在环境变量属性文件中

出于安全原因，秘密（如密码、个人访问令牌或 API 密钥）不得进入版本控制。一种方法是将它们存储在本地环境变量属性（.env）文件中。

  1. 将秘密存储在项目根目录的 .env 文件中。

    .env 文件
    foo.api-key=ThisIsSecret

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

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

更新测试

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

在浏览器中打开 https://: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

以编程方式访问配置

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 服务器端口，您可以在 application.properties 中设置 quarkus.http.port。所有 Quarkus 配置属性都有文档记录且可搜索。

如上所述，以 quarkus. 开头的属性实际上是保留给 Quarkus 及其扩展使用的。因此，quarkus. 前缀**绝不**应为应用程序特定属性使用。

构建时配置

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

在所有配置选项列表中，在构建时固定的属性会用锁图标（）标记。

但是，某些扩展确实定义了运行时可覆盖的属性。一个简单的例子是数据库 URL、用户名和密码，这些信息仅在你目标环境中可知，因此可以设置它们并影响应用程序在运行时中的行为。

其他信息

Quarkus 依赖于 SmallRye Config 并继承其功能。

  • 其他 ConfigSource

  • 其他 Converter

  • 索引属性

  • 父配置文件

  • 用于配置值解析的拦截器

  • 重定位配置属性

  • 备用配置属性

  • 日志

  • 隐藏秘密

有关更多信息，请参阅 SmallRye Config 文档。

相关内容

关于相同主题

Quarkus 是开源的。本项目的所有依赖项均根据 Apache 软件许可证 2.0 或兼容许可证提供。 CC by 3.0

本网站使用 Jekyll 构建，托管在 GitHub Pages 上，并且完全开源。如果您想让它变得更好，请 fork 该网站并向我们展示您的成果。

导航
关注我们
获取帮助
语言
Quarkus 由社区项目组成
版权所有 © Quarkus。保留所有权利。有关我们的商标详情，请访问我们的 商标政策 和 商标列表。第三方商标属于其各自持有人，此处提及并不暗示任何认可或关联。