YAML configuration

你可以使用 YAML 文件 application.yaml 为你要配置的 Quarkus 应用程序替换标准 Java 属性文件 application.properties。 YAML 广泛用于定义资源描述符，尤其是在 Kubernetes 中。

Enable YAML configuration

要启用 YAML 配置，请添加 quarkus-config-yaml 扩展名：

CLI
quarkus extension add {add-extension-extensions}
Maven
./mvnw quarkus:add-extension -Dextensions='{add-extension-extensions}'
Gradle
./gradlew addExtension --extensions='{add-extension-extensions}'

也可以向你的项目添加以下依赖项：

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-config-yaml</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-config-yaml")

添加扩展名或依赖项后，为了避免混乱，请移除 src/main/resources/application.properties 文件并创建一个 src/main/resources/application.yaml 文件。

如果同时存在两个文件，Quarkus 将优先使用 YAML 文件中的属性。

Quarkus 识别 .yml 和 .yaml 文件扩展名。

Example YAML configurations

以下片段提供了 YAML 配置示例：

# YAML supports comments
quarkus:
  datasource:
    db-kind: postgresql
    jdbc:
      url: jdbc:postgresql://localhost:5432/some-database

# REST Client configuration property
quarkus:
  rest-client:
    org.acme.rest.client.ExtensionsService:
      url: https://stage.code.quarkus.io/api
# For configuration property names that use quotes, do not split the string inside the quotes
quarkus:
  log:
    category:
      "io.quarkus.category":
        level: INFO
quarkus:
  datasource:
    jdbc:
      url: jdbc:postgresql://localhost:5432/quarkus_test

  hibernate-orm:
    database:
      generation: drop-and-create

  oidc:
    enabled: true
    auth-server-url: http://localhost:8180/auth/realms/quarkus
    client-id: app


app:
  frontend:
    oidc-realm: quarkus
    oidc-app: app
    oidc-server: http://localhost:8180/auth

# With profiles
"%test":
   quarkus:
     oidc:
       enabled: false
     security:
        users:
            file:
              enabled: true
              realm-name: quarkus
              plain-text: true

Profiles

如你所见，你可以在 YAML 中使用 profiles。

在 YAML 中，以 % 开头的键不被允许。但是，配置文件键必须以该符号开头。要解决此问题，请将配置文件键用双引号括起来，如示例 "%test" 所示。

"%test" 键下的所有配置仅在启用 test 配置文件时激活。例如，前一个片段表明，当活动 test 配置文件时，OpenID Connect (OIDC) (quarkus.oidc.enabled: false) 被禁用。没有 test 配置文件，OIDC 默认情况下处于启用状态。

你还可以定义自定义配置文件，例如以下示例中的 %staging：

quarkus:
  http:
    port: 8081

"%staging":
    quarkus:
        http:
          port: 8082

如果你启用 staging 配置文件，HTTP 端口将被设置为 8082，而不是 8081。

YAML 配置还支持配置文件相关的文件。在这种情况下，特定配置文件的属性可以保存在名为 application-{profile}.yaml 的文件中。前一个示例可以表示为：

quarkus:
  http:
    port: 8081
application-staging.yaml
quarkus:
  http:
    port: 8082

Expressions

YAML 格式也支持 property expressions，使用与 Java 属性相同的格式：

mach: 3
x:
  factor: 2.23694

display:
  mach: ${mach}
  unit:
    name: "mph"
    factor: ${x.factor}

您可以使用 . (点) 分隔符来引用嵌套属性，如下所示：${x.factor}。

External application.yaml file

application.yaml 文件也可以放在 config/application.yaml 中以专门化运行时配置。文件必须存在于工作目录根目录中，相对于 Quarkus 应用程序运行程序：

.
├── config
│    └── application.yaml
├── my-app-runner

此文件中的值会覆盖 application.yaml 文件中（如果存在）的任何值。

Configuration property conflicts

MicroProfile Config 规范将配置文件定义为一个任意 . 分隔的字符串。然而，YAML 等结构化格式只支持可能的配置名称空间的一部分。例如，考虑两个配置属性 quarkus.http.cors 和 quarkus.http.cors.methods。一个属性是另一个的开头，因此可能无法立即显而易见如何在 YAML 配置中指定两个键。

通过使用 ~ 作为 null 键来解决此问题，它表示的前缀是另一个 YAML 属性：

quarkus:
  http:
    cors:
      ~: true
      methods: GET,PUT,POST

YAML null 键不包括在配置文件名称的组装中，允许在任何级别使用它们来消除配置属性的歧义。

虽然 Quarkus 主要使用 .properties 文件扩展名进行配置，但用于在 Quarkus 中解析 YAML 的 snakeyaml 库也可以解析 JSON 结构。这意味着您可以使用 YAML 文件，其中包含 JSON 内容。

可以在 application.yaml 文件中读取 YAML 和 JSON 结构。

当然，以下是有关如何使用 Quarkus 的复杂配置文件结构的分步指南：

  • Define Your Configuration Interface.

@ConfigMapping(prefix = "server")
public interface ServiceConfig {

  List<Environment> environments();

  interface Environment {
    String name();
    String services();
  }
}

  • 创建适当的 JSON 结构并将其存储在 YAML 文件中。

{
  "server": {
    "environments": [
      {
        "name": "dev",
        "services": "bookstore"
      },
      {
        "name": "batch",
        "services": "warehouse"
      }
    ]
  }
}