Quarkus技术系列「云原生架构实战」配置参考指南相关的功能机制配置介绍分析

Posted 2022-12-23 洛神灬殇

回顾Quarkus介绍

Quarkus的概念定义

Quarkus是一个为Java虚拟机（JVM）和原生编译而设计的全堆栈 Kubernetes 原生 Java 框架，用于专门针对容器优化 Java，并使其成为无服务器、云和 Kubernetes 环境的高效平台。

Quarkus与框架整合

Quarkus可与常用 Java 标准、框架和库协同工作，例如：Eclipse MicroProfile、Spring、Apache Kafka、RESTEasy (JAX-RS)、Hibernate ORM (JPA)、Spring、Infinispan、Camel 等。

Quarkus的依赖注入

Quarkus的依赖注入解决方案基于 CDI（上下文和依赖注入），且包含一个扩展框架来扩展功能并将其配置、引导并集成到您的应用中。添加扩展就像添加依赖项一样容易；或者，您可以使用 Quarkus 工具。

Quarkus多语言化

• GraalVM（一种通用虚拟机，用于运行以多种语言（包括 Java 和 javascript）编写的应用）提供正确信息，以便对应用进行原生编译。

• 惊人的快速启动时间，极低的RSS内存（不仅是堆大小！）在容器编排平台（如Kubernetes）中提供了近乎即时的向上扩展和高密度的内存利用率

专为开发人员而设计

Quarkus的设计从一开始就立足于简单易用，其功能几乎不需要配置即可正常使用。

开发人员可以为其应用选择所需的Java框架，而这些应用可以在JVM模式下运行，也可以在原生模式下进行编译和运行。

可为开发人员带来最佳的欢乐：

统一配置

• 零配置，瞬间重载实时重载

• 简化了80％常用用法的代码，灵活了20％的用法

• 无需麻烦的本机可执行文件生成

容器优先

• 无论是将应用托管在公共云上还是内部托管的 Kubernetes 集群中，快速启动和低内存消耗等特性对于降低总体主机成本来说都至关重要。

• Quarkus的开发遵从了容器优先的原则，这意味着它已通过以下方式针对降低内存使用和加快启动时间进行了优化

  • 鼎力支持Graal/SubstrateVM

  • 构建时元数据处理

  • 减少反射的使用

  • 本机映像预启动

Quarkus构建的应用其内存消耗只有传统Java的1/10，而且启动时间更快（快了 300 倍），这些都大大降低了云资源的成本。

云原生

在Kubernetes等环境中采用 12 要素原则。

统一命令式与反应式

在设计上，Quarkus能够在开发应用时无缝地结合熟悉的命令式代码和非阻塞、响应式样式。

这对于习惯使用命令式模型而不想切换风格的 Java 开发人员以及使用云原生/响应式方法的开发人员都非常有用。

基于标准

Quarkus通过利用您喜欢和使用的五十多种最佳库的不断增长的列表，提供了一个内聚的，易于使用的，全栈的框架。所有都连接在标准主干上

Quarkus 开发模型可以适应您正在开发的任何应用

对于在新的无服务器架构、微服务、容器、Kubernetes、功能即服务（FaaS）和云环境中运行 Java 而言，Quarkus 堪称是一个有效的解决方案，因为在创建它时就充分考虑了所有这些因素。

使用DI注入

• Quarkus中的依赖注入基于ArC，ArC是为Quarkus架构量身定制的基于CDI的依赖注入解决方案。如果您不熟悉CDI，建议您阅读CDI简介指南。

• Quarkus仅实现CDI功能的一个子集，并具有非标准功能和特定的APIS，您可以在Contexts and Dependency Injection指南中了解有关它的更多信息。

• ArC作为的依赖项，quarkus-resteasy因此您已经很方便了。

配置参考指南

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

配置源

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

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

系统属性

运行jar：

java -Dquarkus.datasource.password=youshallnotpass -jar target/quarkus-app/quarkus-run.jar

native执行文件：

./target/myapp-runner -Dquarkus.datasource.password=youshallnotpass

环境变量

运行jar：

export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ; 
java -jar target/quarkus-app/quarkus-run.jar

native可执行文件：

export QUARKUS_DATASOURCE_PASSWORD=youshallnotpass ;
./target/myapp-runner

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

示例.env文件

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

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

没有定义的配置文件的环境变量.env文件将覆盖其所有相关的配置文件中application.properties，例如，%test.application.value被覆盖APPLICATION_VALUE的.env文件。

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

• 将application.properties文件放置在名为config的目录中，该目录位于应用程序运行的目录中，该文件中定义的所有运行时属性都将覆盖默认配置。

• 此外，添加到该文件中的任何不属于原始application.properties文件的 运行时属性也将被考虑在内。对于运行程序jar和本机可执行文件，其工作方式相同。

• 该config/application.properties功能在开发模式下也可用。

• 要使用它，config/application.properties需要放置在构建工具的输出目录中。但是请记住，从构建工具进行的任何清理操作（例如mvn clean或）gradle clean也会删除该config目录。

应用程序配置文件

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

application.properties文件

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

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

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

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

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

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

注入配置属性

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

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

可以使用@Inject @ConfigProperty或@ConfigProperty。对于使用@Inject注释的成员，注释不是必需的@ConfigProperty。此行为不同于MicroProfile Config。

如果应用程序尝试注入未设置的配置属性，则会引发错误，从而使您可以快速了解配置何时完成。

@ConfigProperty例子

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

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

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

如果您不提供此属性的值，则应用程序启动将失败

javax.enterprise.inject.spi.DeploymentException: No config value of type [class java.lang.String] exists for: greeting.message。

如果配置未提供的值，则会注入默认值greeting.suffix。

此属性是可选的-Optional如果配置未提供的值，则会注入一个空值greeting.name。

以编程方式访问配置

可以通过编程方式访问配置。实现动态查找或从既不是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);

使用@ConfigProperties

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

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

@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字段和具有默认值的字段。

有关@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，则允许该接口扩展其他接口，并且使用整个接口层次结构中的方法来绑定属性。

使用具有不同前缀的相同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;

使用对象列表

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

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

这种配置的局限性在于用作列表的通用类型的类型必须是类而不是接口

配置配置文件

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