YAML configuration

你可以使用 YAML 文件 application.yaml 为你要配置的 {project-name} 应用程序替换标准 Java 属性文件 application.properties。

You can use a YAML file,application.yaml, to configure your {project-name} application instead of the standard Java properties file, application.properties.

YAML 广泛用于定义资源描述符，尤其是在 Kubernetes 中。

YAML is widely used for defining resource descriptors, especially in Kubernetes.

Enable YAML configuration

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

To enable YAML configuration, add the quarkus-config-yaml extension:

Unresolved directive in config-yaml.adoc - include::{includes}/devtools/extension-add.adoc[]

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

Alternatively, add the following dependency to your project:

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 文件。

After adding the extension or dependency, to avoid confusion, remove the src/main/resources/application.properties file and create a src/main/resources/application.yaml file.

如果同时存在两个文件，{project-name} 将优先使用 YAML 文件中的属性。

If both files are present, {project-name} gives precedence to properties in the YAML file.

{project-name} 识别 .yml 和 .yaml 文件扩展名。

{project-name} recognizes both .yml and .yaml file extensions.

Example YAML configurations

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

The following snippets give examples of YAML configurations:

# 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。

As you can see in the previous snippet, you can use profiles in YAML.

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

In YAML, keys that begin with % are not allowed. However, profile keys must start with this symbol. To resolve this, enclose the profile keys in double quotes, as demonstrated by the example, "%test".

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

All configurations under the "%test" key activate only when the test profile is enabled. For instance, the previous snippet shows that OpenID Connect (OIDC) (quarkus.oidc.enabled: false) is disabled when the test profile is active. Without the test profile, OIDC is enabled by default.

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

You can also define custom profiles, such as %staging in the following example:

quarkus:
  http:
    port: 8081

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

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

If you enable the staging profile, the HTTP port is set to 8082 instead of 8081.

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

The YAML configuration also supports profile-aware files. In this case, properties for a specific profile can reside in an application-{profile}.yaml named file. The previous example can be expressed as:

quarkus:
  http:
    port: 8081

application-staging.yaml

quarkus:
  http:
    port: 8082

Expressions

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

The YAML format also supports property expressions, by using the same format as Java properties:

mach: 3
x:
  factor: 2.23694

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

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

You can reference nested properties by using the . (dot) separator, as in ${x.factor}.

External application.yaml file

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

The application.yaml file can also be placed in config/application.yaml to specialize the runtime configuration. The file must be present in the root of the working directory relative to the {project-name} application runner:

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

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

The values from this file override any values from the regular application.yaml file if it exists.

Configuration property conflicts

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

The MicroProfile Config specification defines configuration properties as an arbitrary .-delimited string. However, structured formats such as YAML only support a subset of the possible configuration namespace. For example, consider the two configuration properties quarkus.http.cors and quarkus.http.cors.methods. One property is the prefix of another, so it might not be immediately evident how to specify both keys in your YAML configuration.

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

This is solved by using ~ as a null key to represent any YAML property that is a prefix of another one:

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

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

YAML null keys are not included in the assembly of the configuration property name, allowing them to be used at any level for disambiguating configuration properties.

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

Although Quarkus primarily uses .properties file extension for configuration, the snakeyaml library, which is used for parsing YAML in Quarkus, can also parse JSON structures. This means you can use YAML files with JSON content inside.

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

YAML and JSON structures can be read in an application.yaml file.

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

Certainly, here’s a step-by-step guide on how to use complex configuration structures with Quarkus:

Define Your Configuration Interface.

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

  List<Environment> environments();

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

Create the appropriate JSON structure and store it in a YAML file.

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