使用 YAML 文件配置红帽构建的 Quarkus 应用程序


Red Hat build of Quarkus 3.15

Red Hat Customer Content Services

摘要

本指南论述了如何使用 YAML 文件配置红帽构建的 Quarkus 应用程序。

向红帽构建的 Quarkus 文档提供反馈

要报告错误或改进文档,请登录您的红帽 JIRA 帐户并提交问题。如果您没有红帽 JIRA 帐户,系统会提示您创建一个帐户。

流程

  1. 单击以下链接 来创建 ticket
  2. Summary 中输入有关此问题的简单描述。
  3. 提供有关 描述 中问题或增强功能的详细描述。包括一个 URL,以在文档中发生问题。
  4. Submit 创建问题并将其路由到适当的文档团队。

作为应用程序开发人员,您可以使用红帽构建的 Quarkus 来创建在 OpenShift Container Platform 和无服务器环境中运行的 Java 编写的基于微服务的应用程序。编译到原生可执行文件的应用程序占用较小的内存占用和快速启动时间。

通过更新 application.yaml 文件来配置 Quarkus 应用程序来应用结构化配置。

注意

另外,您可以通过在 application.properties 文件中设置属性来配置 Quarkus 应用程序。如需更多信息,请参阅设置配置属性

该流程包括使用 Quarkus config-quickstart 练习创建的配置示例。

注意

对于应用程序配置练习的完整示例,请下载 Quarkus Quickstarts 存档或克隆 Quarkus Quickstarts Git 存储库,并进入 config-quickstart 目录。

先决条件

1.1. 配置选项

您可以在单个配置文件中管理应用程序的设置。另外,您可以定义配置文件来对不同环境相关的设置进行分组,如开发、测试或生产。这样,您可以在配置集间轻松切换并应用特定于环境的属性,而无需更改主配置文件。

默认情况下,Quarkus 从 src/main/resources 目录中的 application.properties 文件中读取属性。如果希望在 application.yaml 文件中配置和管理应用程序属性,请将 quarkus-config-yaml 依赖项添加到项目的 pom.xml 文件中。如需更多信息,请参阅 添加 YAML 配置支持

红帽构建的 Quarkus 还支持 MicroProfile 配置,可用于从各种来源加载应用的配置。通过使用 Eclipse MicroProfile 项目中的 MicroProfile 配置规范,您可以将配置属性注入到应用中,并使用您的代码中定义的方法访问它们。

Quarkus 可以从不同的来源读取应用程序属性,包括:

  • 文件系统
  • 数据库
  • Kubernetes 或 OpenShift Container Platform ConfigMapSecret 对象
  • Java 应用程序都可以加载的任何源

1.2. 添加 YAML 配置支持

红帽构建的 Quarkus 通过 Eclipse MicroProfile Config 的 SmallRye Config 实现支持 YAML 配置文件。您可以添加 Quarkus Config YAML 扩展,并通过属性文件使用 YAML 配置文件进行配置。Quarkus 支持使用 application.ymlapplication.yaml 作为 YAML 文件的名称。

YAML 配置文件优先于 application.properties 文件。要避免错误,您可以删除 application.properties 文件,并只使用一种类型的配置文件。

流程

  1. 使用以下方法之一在项目中添加 YAML 扩展:

    • 打开 pom.xml 文件,并将 quarkus-config-yaml 扩展添加为依赖项:

      pom.xml 文件示例

      <dependency>
          <groupId>io.quarkus</groupId>
          <artifactId>quarkus-config-yaml</artifactId>
      </dependency>
      Copy to Clipboard Toggle word wrap

    • 要从命令行添加 quarkus-config-yaml 扩展,请从项目目录输入以下命令:

      添加 quarkus-config-yaml 扩展

      ./mvnw quarkus:add-extension -Dextensions="quarkus-config-yaml"
      Copy to Clipboard Toggle word wrap

1.2.1. 使用带有 YAML 的嵌套对象配置

您可以使用 application.yaml 配置文件为 Red Hat build of Quarkus 应用程序定义现有配置属性。

先决条件

  • 您有一个 Quarkus Maven 项目。
  • 您有一个 PostgreSQL 数据源。
  • 在项目的 pom.xml 文件中有以下扩展作为依赖项:

    • quarkus-resteasy-client
    • quarkus-jdbc-postgresql
    • quarkus-config-yaml

流程

  1. 打开 src/main/resources/application.yaml 配置文件。
  2. application.yaml 文件中添加嵌套类配置属性,如下例所示:

    application.yaml 文件示例

    # Properties that configure the JDBC data source driver of your PostgreSQL data source
    quarkus:
      datasource:
        db-kind: postgresql
        jdbc:
          url: jdbc:postgresql://localhost:5432/quarkus_test
        username: quarkus_test
        password: quarkus_test
    
    # Property that configures the URL of the endpoint to which the REST client sends requests
    quarkus:
      rest-client:
        org.acme.rest.client.ExtensionsService:
          url: https://stage.code.quarkus.io/api
    
    # Property that configures the log message level for your application
    # For configuration property names that use quotes, do not split the string inside the quotes
    quarkus:
      log:
        category:
          "io.quarkus.category":
            level: INFO
    Copy to Clipboard Toggle word wrap

    警告

    对于生产环境,不要在配置文件中设置用户名和密码,如上例中所示。这仅用于演示目的。而是在环境变量中设置它们。如需更多信息,请参阅"使用 属性文件配置 Quarkus 应用程序的红帽构建配置属性"指南中的设置配置属性 部分。

    application.properties 文件类似,您可以使用注释来以 YAML 格式描述您的配置属性。

    注意

    始终使用空格来缩进 YAML 配置文件中的属性。YAML 不支持将标签页用于缩进。

1.2.2. 使用 YAML 设置自定义配置配置集

使用 Quarkus,您可以设置特定于应用程序的不同配置配置文件的配置属性和值。您可以使用特定配置集启动应用程序,以访问特定的配置。此流程演示了如何以 YAML 格式为特定配置集提供配置。

先决条件

  • 您有一个 Quarkus Maven 项目,配置为使用带有 JDBC 数据源驱动程序的 PostgreSQL 数据源。
  • 在项目的 pom.xml 文件中具有 quarkus-jdbc-postgresqlquarkus-config-yaml 扩展作为依赖项。

流程

  1. 打开项目的配置文件 src/main/resources/application.yaml
  2. 要设置与配置集相关的配置,请在使用 "%<profile_name>" 语法定义键值对前添加 配置集名称。确保将配置集名称放在引号内。

    提示

    在 YAML 中,您必须将以特殊字符开头的所有字符串放在引号内。

    在以下示例中,当您以开发模式启动 Quarkus 应用程序时,PostgreSQL 数据库被配置为位于 jdbc:postgresql://localhost:5432/quarkus_test URL 中:

    src/main/resources/application.yaml

    "%dev":
      quarkus:
        datasource:
          db-kind: postgresql
            jdbc:
              url: jdbc:postgresql://localhost:5432/quarkus_test
            username: quarkus_test
            password: quarkus_test
    Copy to Clipboard Toggle word wrap

    警告

    对于生产环境,不要在配置文件中设置用户名和密码,如上例中所示。这仅用于演示目的。而是在环境变量中设置它们。如需更多信息,请参阅"使用 属性文件配置 Quarkus 应用程序的红帽构建配置属性"指南中的设置配置属性 部分。

1.3. 属性表达式

您可以将属性引用和文本字符串组合成属性表达式,并将这些表达式用作 Quarkus 配置中的值。

与变量一样,属性表达式会动态地替换配置属性值,避免硬编码的值。

您可以在一个配置源中扩展表达式,其值在另一个定义。

java.util.Properties 从配置来源读取属性值时,应用会解析属性表达式:如果读取,并在运行时进行编译(如果在该时间点上被覆盖)。

如果应用无法解析表达式中的属性值,并且属性没有默认值,则应用会抛出 NoSuchElementException 错误。

1.3.1. 示例: YAML 文件中的属性表达式

以下示例演示了如何将属性表达式用于灵活的 Quarkus 应用程序配置。

application.yaml 文件示例

mach: 3
x:
  factor: 2.23694

display:
  mach: ${mach}
  unit:
    name: "mph"
    factor: ${x.factor}
Copy to Clipboard Toggle word wrap

注意

要引用嵌套属性,请使用 . (dot)分隔符,如 {x.factor} 中所示。

要在运行时配置应用程序属性,请将 application.yaml 文件添加到 config 目录中。

config/application.yamlsrc/main/resources/application.yaml 共享属性时,来自 config/application.yaml 的值会覆盖 src/main/resources/application.yaml 中的值。

确保 config/application.yaml 文件位于与 Quarkus 应用程序运行程序相关的工作目录中的根目录,如下例所示:

├── config
│    └── application.yaml
├── my-app-runner
Copy to Clipboard Toggle word wrap

1.5. 管理配置属性冲突

YAML 等结构化格式只支持可能的配置命名空间的子集。以下流程演示了如何解决两个配置属性 quarkus.http.cors 和 quarkus.http.cors.methods 之间冲突,其中一个属性是另一个配置的前缀。

先决条件

  • 您有一个 Quarkus 项目,它被配置为读取 YAML 配置文件。

流程

  1. 打开 YAML 配置文件。
  2. 要将 YAML 属性定义为另一个属性的前缀,请在属性范围中添加一个波形符(~),如下例所示:

    将 YAML 属性定义为前缀示例

    quarkus:
      http:
        cors:
          ~: true
          methods: GET,PUT,POST
    Copy to Clipboard Toggle word wrap

  3. 要在开发模式下编译 Quarkus 应用程序,请从项目目录输入以下命令:

    编译应用程序

    ./mvnw quarkus:dev
    Copy to Clipboard Toggle word wrap

    注意

    您可以使用 YAML 键在任何级别上冲突的配置键,因为它们没有包含在配置属性名称的 assembly 中。

法律通告

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

Theme

© 2026 Red Hat
返回顶部