Quarkus应用程序和Quarkus本身（核心和扩展）都通过相同的机制进行配置，该机制利用SmallRye Config API和 MicroProfile Config规范的实现。此外，Quarkus本身提供了一些附加功能。

1.配置源

默认情况下，Quarkus从多个来源（优先级递减）中读取配置属性：

1. 系统属性
2. 环境变量
3. 名为文件的文件.env放置在当前工作目录中
4. application.properties文件放在$PWD/config/目录中
5. 应用程序配置文件，即src/main/resources/application.properties

1.1.系统属性

• 运行jar： java -Dquarkus.datasource.password=youshallnotpass -jar target/quarkus-app/quarkus-run.jar
• native执行文件： ./target/myapp-runner -Dquarkus.datasource.password=youshallnotpass

1.2.环境变量

• 运行jar： export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; java -jar target/quarkus-app/quarkus-run.jar
• native可执行文件： export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; ./target/myapp-runner

1.3.文件名为.env放置在当前工作目录中

示例.env文件

QUARKUS_DATASOURCE_PASSWORD=youshallnotpass 
QUARKUS_DATASOURCE_PASSWORD使用与环境变量相同的规则来转换名称。

对于开发人员模式，此文件可以放在项目的根目录中，但建议不要将其检入版本控制。

1.4.application.properties文件放置在$PWD/config/

将application.properties文件放置在名为config的目录中，该目录位于应用程序运行的目录中，该文件中定义的所有运行时属性都将覆盖默认配置。此外，添加到该文件中的任何不属于原始application.properties文件的 运行时属性也将被考虑在内。对于运行程序jar和本机可执行文件，其工作方式相同。

1.5.应用程序配置文件

这是位于中的主要应用程序配置文件src/main/resources/application.properties。

示例application.properties文件

greeting.message=hello 
quarkus.http.port=9090 

• 这是用户定义的配置属性。
• 这是用户定义的配置属性。
• Quarkus支持在文件中使用属性表达式application.properties。

2.将配置文件嵌入到依赖项中

可以通过向META-INF/microprofile-config.properties配置文件中添加一个配置文件来将配置文件嵌入其中（这是MicroProfile Config的标准功能）。

当将此依赖项添加到应用程序时，其配置属性将被合并。

可以覆盖优先于它的属性来自它的属性application.properties。

3.注入配置属性

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

@ConfigProperty(name = "greeting.message") 
String message;

更多@ConfigProperty例子

@ConfigProperty(name = "greeting.message") 
String message;

@ConfigProperty(name = "greeting.suffix", defaultValue="!") 
String suffix;

@ConfigProperty(name = "greeting.name")
Optional<String> name; 

4.以编程方式访问配置

可以通过编程方式访问配置。实现动态查找或从既不是CDI bean也不是JAX-RS资源的类中检索配置的值可能很方便。

可以使用以下方式以编程方式访问配置org.eclipse.microprofile.config.ConfigProvider.getConfig()：

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

5.使用@ConfigProperties

作为以上一示例中所示的方式注入多个相关配置值的替代方法，用户还可以使用@io.quarkus.arc.config.ConfigProperties注释将这些属性组合在一起。

对于上面的Greeting属性，GreetingConfiguration可以这样创建一个类：

package org.acme.config;

import io.quarkus.arc.config.ConfigProperties;
import java.util.Optional;

@ConfigProperties(prefix = "greeting") 
public class GreetingConfiguration {

    private String message;
    private String suffix = "!"; 
    private Optional<String> name;

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public String getSuffix() {
        return suffix;
    }

    public void setSuffix(String suffix) {
        this.suffix = suffix;
    }

    public Optional<String> getName() {
        return name;
    }

    public void setName(Optional<String> name) {
        this.name = name;
    }
}

然后可以GreetingResource使用@Inject类似的CDI注释将此类注入到，如下所示：

@Inject
GreetingConfiguration greetingConfiguration;

Quarkus提供的另一种替代样式是GreetingConfiguration像这样创建接口：

package org.acme.config;

import io.quarkus.arc.config.ConfigProperties;
import org.eclipse.microprofile.config.inject.ConfigProperty;
import java.util.Optional;

@ConfigProperties(prefix = "greeting")
public interface GreetingConfiguration {

    @ConfigProperty(name = "message") 
    String message();

    @ConfigProperty(defaultValue = "!")
    String getSuffix(); 

    Optional<String> getName(); 
}

在@ConfigProperties类或接口上使用时，如果未提供其字段之一的值，则应用程序启动将失败，并且将javax.enterprise.inject.spi.DeploymentException显示指示缺少值的信息。这不适用于Optional字段和具有默认值的字段。

5.1.有关@ConfigProperties的其他说明

当使用带有类注释的常规类时，@ConfigProperties不一定必须声明getter和setter。具有简单的公共非最终字段也是有效的。

此外，配置类支持嵌套对象配置。假设需要有一个额外的问候语配置层，名称content将包含一些字段。可以这样实现：

@ConfigProperties(prefix = "greeting")
public class GreetingConfiguration {

    public String message;
    public String suffix = "!";
    public Optional<String> name;
    public ContentConfig content; 

    public static class ContentConfig {
        public Integer prizeAmount;
        public List<String> recipients;
    }
}

字段名称（不是类名称）将确定绑定到对象的属性的名称。

设置属性将以正常方式进行，例如，application.properties可能具有：

greeting.message = hello
greeting.name = quarkus
greeting.content.prize-amount=10
greeting.content.recipients=Jane,John

此外，@ConfigProperties可以使用Bean Validation批注来批注使用批注的类，类似于以下示例：

@ConfigProperties(prefix = "greeting")
public class GreetingConfiguration {

    @Size(min = 20)
    public String message;
    public String suffix = "!";

}

为了使验证生效，quarkus-hibernate-validator需要提供扩展名

如果使用给定的配置验证失败，则应用程序将无法启动，并在日志中指示相应的验证错误。

如果接口带有注释@ConfigProperties，则允许该接口扩展其他接口，并且使用整个接口层次结构中的方法来绑定属性。

5.2.使用具有不同前缀的相同ConfigProperty

Quarkus还支持使用注解@ConfigProperties为每个注入点使用带有不同前缀的同一对象io.quarkus.arc.config.@ConfigPrefix。举例来说，前缀和前缀GreetingConfiguration都需要使用以上代码。在这种情况下，代码如下所示：greetingother

GreetingConfiguration.java

@ConfigProperties(prefix = "greeting")
public class GreetingConfiguration {

    @Size(min = 20)
    public String message;
    public String suffix = "!";

}

SomeBean.java

@ApplicationScoped
public class SomeBean {

    @Inject 
    GreetingConfiguration greetingConfiguration;

    @ConfigPrefix("other") 
    GreetingConfiguration otherConfiguration;

}

5.3.使用对象列表

在某些情况下，可能有必要支持利用对象列表的复杂配置结构，如以下示例所示：

ComplexConfiguration.java

@ConfigProperties(prefix = "complex")
public class ComplexConfiguration {
    public String name;
    public String user;
    public String password;
    public List<Nested> inputs;
    public List<Nested> outputs;

    public static class Nested {
        public String user;
        public String password;
    }
}

仅当将YAML配置与quarkus-config-yaml扩展一起使用时，才对此类用例提供支持。相应的示例YAML配置可以是：

application.yaml

complex:
  name: defaultName
  user: defaultUser
  password: defaultPassword
  inputs:
    - user: user
      password: secret
    - user: otheruser
      password: secret2
  outputs:
    - user: someuser
      password: asecret
    - user: someotheruser
      password: anothersecret

6.配置配置文件

Quarkus支持配置配置文件的概念。这些允许您在同一文件中具有多个配置，并通过配置文件名称在它们之间进行选择。

语法为%{profile}.config.key=value。例如，如果我有以下内容：

quarkus.http.port=9090
%dev.quarkus.http.port=8181

除非dev配置文件处于活动状态，否则Quarkus HTTP端口将为9090 ，在这种情况下，它将为8181。

要在.env文件中使用配置文件，可以遵循一种_{PROFILE}_CONFIG_KEY=value模式。.env文件中上述示例的等效内容为：

QUARKUS_HTTP_PORT=9090
_DEV_QUARKUS_HTTP_PORT=8181

默认情况下，Quarkus具有三个配置文件，尽管可以随意使用。默认配置文件为：

• dev-在开发模式下（即quarkus:dev）激活
• 测试-运行测试时激活
• prod-未在开发或测试模式下运行时的默认配置文件

有两种方法可以通过quarkus.profile系统属性或QUARKUS_PROFILE 环境变量来设置定制概要文件。如果两者都设置，则系统属性优先。请注意，不必在任何地方定义这些概要文件的名称，只需创建具有概要文件名称的config属性，然后将当前概要文件设置为该名称即可。例如，如果我想要staging使用其他HTTP端口的配置文件，则可以将以下内容添加到application.properties：

quarkus.http.port=9090
%staging.quarkus.http.port=9999

然后将QUARKUS_PROFILE环境变量设置staging为激活我的配置文件。

6.1.默认运行时配置文件

默认的Quarkus应用程序运行时配置文件设置为用于构建应用程序的配置文件。例如：

./mvnw package -Pnative -Dquarkus.profile=prod-aws
./target/my-app-1.0-runner 

7.使用属性表达式

Quarkus支持在application.properties文件中使用属性表达式。

读取属性后，将解析这些表达式。因此，如果您的配置属性是构建时配置属性，则该属性表达式将在构建时解析。如果您的配置属性在运行时可覆盖，则该属性表达式将在运行时解析。

您可以将属性表达式同时用于Quarkus配置或您自己的配置属性。

属性表达式是通过以下方式定义的：${my-property-expression}。

例如，具有以下属性：

remote.host=quarkus.io

另一个属性定义为：

callable.url=https://${remote.host}/

将导致该callable.url属性的值设置为：

callable.url=https://quarkus.io/

另一个示例是根据所使用的概要文件定义不同的数据库服务器：

%dev.quarkus.datasource.jdbc.url=jdbc:mysql://localhost:3306/mydatabase?useSSL=false
quarkus.datasource.jdbc.url=jdbc:mysql://remotehost:3306/mydatabase?useSSL=false

可以通过以下方式简化：

%dev.application.server=localhost
application.server=remotehost

quarkus.datasource.jdbc.url=jdbc:mysql://${application.server}:3306/mydatabase?useSSL=false

在此示例中，它的确增加了一行，但是的值application.server可以在其他属性中重用，从而减少了输入错误的可能性，并在属性定义中提供了更大的灵活性。

8.组合属性表达式和环境变量

Quarkus还支持属性表达式和环境变量的组合。

假设您在中定义了以下属性application.properties：

remote.host=quarkus.io

您可以通过如下定义属性来组合环境变量和属性表达式：

application.host=${HOST:${remote.host}}

如果未设置，这将扩展HOST环境变量并将属性的值remote.host用作默认值HOST。

出于本节的目的，我们使用了remote.host之前定义的属性。必须注意，该值可以是固定值，例如：

application.host=${HOST:localhost}

localhost如果HOST未设置，它将作为默认值。

9.配置Quarkus

Quarkus本身是通过与您的应用程序相同的机制配置的。Quarkusquarkus.为自己的配置及其所有扩展的配置保留名称空间。例如，要配置HTTP服务器端口，可以quarkus.http.port在 中设置application.properties。所有Quarkus配置属性均已记录且可搜索。

Quarkus在构建时进行大部分配置和引导，并且在构建期间读取并使用了一些配置属性。这些属性在构建时是固定的，无法在运行时进行更改。您始终需要重新打包应用程序，以反映此类属性的更改。

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

但是，某些扩展程序确实定义了可以在运行时覆盖的属性。一个典型的例子是数据库URL，用户名和密码，这些仅在您的目标环境中才知道。这是一个权衡，因为可用的运行时属性越多，Quarkus可以进行的构建时间越少。因此，运行时属性列表是精简的。您可以使用以下机制（以降低的优先级）覆盖这些运行时属性：

1. 系统属性
2. 环境变量
3. 名为环境文件.env放置在当前工作目录中
4. 放置在其中的配置文件 $PWD/config/application.properties

有关更多详细信息，请参见配置源。

10.为应用程序生成配置

也可以生成一个application.properties具有所有已知配置属性的示例，以使您轻松查看可用的Quarkus配置选项。为此，请运行：

./mvnw quarkus:generate-config

这将创建一个src/main/resources/application.properties.example文件，其中包含通过您当前安装的扩展程序公开的所有配置选项。这些选项已被注释掉，并在适用时具有其默认值。例如，此HTTP端口配置条目将显示为：

#
# The HTTP port
#
#quarkus.http.port=8080

除了生成示例配置文件之外，您还可以通过设置-Dfile 参数将它们添加到实际的配置文件中：

./mvnw quarkus:generate-config -Dfile=application.properties

如果配置选项已经存在（有注释），则不会添加，因此在添加其他扩展名以查看添加了哪些其他选项之后可以安全地运行该配置选项。

11.清除属性

可以通过为属性分配一个空字符串来明确清除运行时属性，这些属性是可选的，并具有在构建时设置的值或具有默认值。请注意，这只会影响运行时属性，并且只能与不需要其值的属性一起使用。

可以通过设置相应的application.properties属性，设置相应的系统属性或设置相应的环境变量来清除该属性。

12.自定义配置

12.1.定制配置源

您还可以采用标准MicroProfile Config方式介绍自定义配置源。为此，您必须提供一个实现org.eclipse.microprofile.config.spi.ConfigSource 或的类org.eclipse.microprofile.config.spi.ConfigSourceProvider。为该类创建一个 服务文件，它将在应用程序启动时检测并安装。

12.2.定制配置转换器

您也可以将自定义类型用于配置值。这可以通过org.eclipse.microprofile.config.spi.Converter<T> 在META-INF/services/org.eclipse.microprofile.config.spi.Converter文件中实现并添加其完全限定的类名来完成。

让我们假设您有一个像这样的自定义类型：

package org.acme.config;

public class MicroProfileCustomValue {

    private final int number;

    public MicroProfileCustomValue(int number) {
        this.number = number;
    }

    public int getNumber() {
        return number;
    }
}

相应的转换器如下所示。请注意，您的自定义转换器类必须是public并且必须具有public无参数构造函数。也一定不能abstract。

package org.acme.config;

import org.eclipse.microprofile.config.spi.Converter;

public class MicroProfileCustomValueConverter implements Converter<MicroProfileCustomValue> {

    @Override
    public MicroProfileCustomValue convert(String value) {
        return new MicroProfileCustomValue(Integer.parseInt(value));
    }
}

然后，您需要在服务文件中包含转换器的标准类名META-INF/services/org.eclipse.microprofile.config.spi.Converter。如果您有更多的转换器，也只需在其文件中添加它们的类名。每行一个全限定的类名，例如：

org.acme.config.MicroProfileCustomValueConverter
org.acme.config.SomeOtherConverter
org.acme.config.YetAnotherConverter

请注意，SomeOtherConverter并且YetAnotherConverter仅出于演示目的而添加了。如果在此文件中包含在运行时不可用的类，则转换器加载将失败。

完成此操作后，您可以将自定义类型用作配置值：

@ConfigProperty(name = "configuration.value.name")
MicroProfileCustomValue value;

12.2.1.转换器优先级

在某些情况下，您可能希望使用自定义转换器来转换已经由其他转换器转换的类型。在这种情况下，您可以使用javax.annotation.Priority注释来更改转换器的优先级，并使自定义转换器的优先级高于列表中的其他转换器。

默认情况下，如果@Priority在转换器上找不到No ，则其优先级为100，所有Quarkus核心转换器的优先级为200，因此，根据要替换的转换器，需要设置更高的值。

为了演示这个想法，让我们实现一个自定义转换器，该转换器将优先MicroProfileCustomValueConverter于上一个示例中实现的转换器 。

package org.acme.config;

import javax.annotation.Priority;
import org.eclipse.microprofile.config.spi.Converter;

@Priority(150)
public class MyCustomConverter implements Converter<MicroProfileCustomValue> {

    @Override
    public MicroProfileCustomValue convert(String value) {

        final int secretNumber;
        if (value.startsFrom("OBF:")) {
            secretNumber = Integer.parseInt(SecretDecoder.decode(value));
        } else {
            secretNumber = Integer.parseInt(value);
        }

        return new MicroProfileCustomValue(secretNumber);
    }
}

由于它会转换相同的值类型（即MicroProfileCustomValue），并且优先级为150，因此将使用MicroProfileCustomValueConverter默认优先级为100的a代替它。

13. YAML配置

13.1.添加YAML配置支持

您可能要对属性使用YAML进行配置。由于SmallRye Config带来了对YAML配置的支持，因此Quarkus也支持这一点。

首先，您需要将Config YAML扩展名添加到您的pom.xml：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-config-yaml</artifactId>
</dependency>

或者，您也可以在包含Quarkus项目的目录中运行以下命令：

./mvnw quarkus:add-extension -Dextensions="config-yaml"

现在，Quarkus可以读取YAML配置文件。配置目录和优先级与以前相同。

13.1.1.配置实例

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

# REST Client configuration property
org:
  acme:
    restclient:
      CountriesService/mp-rest/url: https://restcountries.eu/rest

# For configuration property names that use quotes, do not split the string inside the quotes.
quarkus:
  log:
    category:
      "io.quarkus.category":
        level: INFO

13.2.取决于配置文件的配置

与属性一样，通过YAML提供与配置文件相关的配置也是如此。%profile在定义键/值对之前，只需添加包装在引号中的引号即可：

"%dev":
  quarkus:
    datasource:
      db-kind: postgresql
      jdbc:
        url: jdbc:postgresql://localhost:5432/some-database
      username: quarkus
      password: quarkus

13.3.配置密钥冲突

MicroProfile Config规范将配置键定义为一个任意的，.分隔字符串。但是，像YAML这样的结构化格式天真的仅支持可能的配置名称空间的子集。例如，考虑两个配置属性quarkus.http.cors和quarkus.http.cors.methods。一个属性是另一个属性的前缀，因此如何在您的YAML配置中同时指定两个密钥可能并不明显。

这可以通过对任何YAML属性使用null键（通常由表示~）来解决，该键是另一个前缀。这是一个例子：

解决与前缀相关的键名冲突的示例YAML配置

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

通常，nullYAML密钥不包括在配置属性名称的汇编中，从而允许它们在任何级别上用于消除配置密钥的歧义。

14.有关如何配置的更多信息

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

SmallRye Config提供：

• 其他配置源
• 附加转换器
• 索引属性
• 家长资料
• 用于配置值解析的拦截器
• 重新定位配置属性
• 后备配置属性
• 记录中
• 隐藏秘密