quarkus实战之七：使用配置

头像
程序员欣宸
     广东
    阅读 11 分钟

    欢迎访问我的GitHub

    这里分类和汇总了欣宸的全部原创(含配套源码)：https://github.com/zq2599/blog_demos

    本篇概览

    • 本文是《quarkus实战》系列的第七篇，前文讲述了如何在将配置信息传入quarkus应用，今天要练习的是如何使用这些配置信息
    • 整篇文章由以下内容构成：
    • 创建工程，作为演示使用配置项操作的代码
    • 演示最基本的使用配置项操作
    • 展示配置项不存时会导致什么问题
    • 演示如何设置默认值，这样配置项不存在也不会出错
    • 默认值是字符串，而实际的变量可以是多种类型，它们之间的关系
    • Optional类型的配置注入
    • 不用注解注入，也可以写代码获取配置
    • 针对相同前缀的配置项，使用配置接口简化代码
    • 使用配置接口嵌套，简化多级的相同前缀配置项
    • 用map接受配置信息（减少配置项相关代码量）
    • quarkus及其扩展组件的内置配置项

    • 接下来从创建demo工程开始吧

      演示代码

    • 创建一个demo工程，参考下面的命令，这样的工程会自带一个web服务类HobbyResource.java

      mvn "io.quarkus:quarkus-maven-plugin:create" \
-DprojectGroupId="com.bolingcavalry" \
-DprojectArtifactId="hello-quarkus" \
-DprojectVersion="1.0-SNAPSHOT" \
-DclassName="HobbyResource" \
-Dpath="actions"

      最基本的配置

    • 先来看看最常用最基本的配置文件使用方式

    • 打开文件<font color="blue">src/main/resources/application.properties</font>，增加下面这行配置

      greeting.message = hello from application.properties

    • 打开HobbyResource.java，增加如下成员变量，使用了注解ConfigProperty

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

    • 以上就是最简单的使用配置项的方式，程序运行后，application.properties中greeting.message的值就会被quarkus框架注入到message成员变量中

      配置项不存在导致的异常

    • 如果ConfigProperty注解的配置项在配置文件中不存在，应用启动会报错，来看看是什么错误

    • 将HobbyResource.java的代码改成下面这样，成员变量notExistsConfig的配置项是<font color="blue">not.exists.config</font>，这个配置项在配置文件中并不存在

      @Path("/actions")
public class HobbyResource {

  // 配置文件中不存在名为not.exists.config的配置项
  @ConfigProperty(name = "not.exists.config")
  String notExistsConfig;

  @GET
  @Produces(MediaType.TEXT_PLAIN)
  public String hello() {
      return "Hello RESTEasy, " + LocalDateTime.now() + ", [" + notExistsConfig + "]";
  }
}

    • 启动应用时报错如下图所示，红框中提示加载配置项失败
      image-20220306112030133

      带默认值的配置

    • 对于上面演示的配置项不存在导致启动失败问题，可以给ConfigProperty注解设置默认值，这样一旦找不到配置项，就使用默认值注入，可以避免启动失败了

    • HobbyResource.java的源码如下，成员变量notExistsConfig的注解了增加属性<font color="red">defaultValue</font>

      @Path("/actions")
public class HobbyResource {

  // 配置文件中不存在名为not.exists.config的配置项
  @ConfigProperty(name = "not.exists.config", defaultValue = "112233")
  String notExistsConfig;

  @GET
  @Produces(MediaType.TEXT_PLAIN)
  public String hello() {
      return "Hello RESTEasy, " + LocalDateTime.now() + ", [" + notExistsConfig + "]";
  }
}

    • 再次启动应用，这次不报错了，浏览器访问结果如下图，defaultValue已经生效
      在这里插入图片描述

      defaultValue属性的自动转换

    • 对于ConfigProperty注解的defaultValue属性还有一点要注意，来看ConfigProperty的源码，如下图，红框显示defaultValue的类型是String
      在这里插入图片描述
    • 上图中，defaultValue的注释有说明：如果ConfigProperty注解修饰的变量并非String型，那么defaultValue的字符串就会被自动quarkus字符转换

    • 例如修饰的变量是int型，那么defaultValue的String类型的值会被转为int型再赋给变量，如下所示，notExistsConfig是int型，defaultValue的字符串可以被转为int：

      // 配置文件中不存在名为not.exists.config的配置项
@ConfigProperty(name = "not.exists.config", defaultValue = "123")
int notExistsConfig;
    • 如果把上面代码中的defaultValue的值从<font color="blue">123</font>改为<font color="red">xxx</font>，此时应用启动就会失败，因为“xxx”转为int的过程中抛出了异常，如下图：
      在这里插入图片描述
    • 除了上面试过的int，还有很多种类型都支持从defaultValue的字符串值被自动转换，它们是：
    • 基础类型：如boolean, byte, short
    • 装箱类型：如java.lang.Boolean, java.lang.Byte, java.lang.Short
    • Optional类型：java.util.Optional, java.util.OptionalInt, java.util.OptionalLong, and java.util.OptionalDouble
    • java枚举
    • java.time.Duration
    • JDK网络对象：如java.net.SocketAddress, java.net.InetAddress

    • 例如，下面是字符串自动转InetAddress的例子，可以正常运行：

      @ConfigProperty(name = "server.address", defaultValue = "192.168.1.1")
InetAddress serverAddress;
    • 如果ConfigProperty修饰的变量是boolean型，或者Boolean型，则defaultValue值的自动转换逻辑有些特别： "true", "1", "YES", "Y" "ON"这些都会被转为true(而且不区分大小写，"on"也被转为true)，其他值会被转为false

    • 还有一处要注意的：defaultValue的值如果是空字符串，就相当于没有设置defaultValue，此时如果在配置文件中没有该配置项，启动应用会报错

      支持Optional

    • 支持Optional这个特性很赞，首先Optional类型的成员变量可直接用于函数式编程，其次配置项不存在时又能避免启动失败
    • 接下来试试用ConfigProperty注解修饰Optional类型的成员变量

    • HobbyResource.java的源码如下，<font color="blue">optionalMessage</font>是Optional类型的成员变量，配置项<font color="red">optional.message</font>就算不存在，应用也能正常启动，并且optionalMessage直接用于函数式编程中（optionalMessage.ifPresent）

      @Path("/actions")
public class HobbyResource {

  // 配置文件中存在名为greeting.message的配置项
  @ConfigProperty(name = "greeting.message")
  String message;

  // 配置文件中，不论是否存在名为optional.message的配置项，应用都不会抛出异常
  @ConfigProperty(name = "optional.message")
  Optional<String> optionalMessage;

  @GET
  @Produces(MediaType.TEXT_PLAIN)
  public String hello() {
      List<String> list = new ArrayList<>();
      list.add(message);

      // 只有配置项optional.message存在的时候，才会执行list.add方法
      optionalMessage.ifPresent(list::add);

      return "Hello RESTEasy, " + LocalDateTime.now() + ", " + list;
  }
}
    • 先看配置项optional.message存在的情况，如下图红框所示，optional.message在配置文件中是个正常的配置项
      在这里插入图片描述
    • 启动应用，浏览器访问web接口，如下图，<font color="blue">optional info</font>是配置项optional.message的值
      在这里插入图片描述

    • 现在将<font color="blue">optional info</font>从文件<font color="red">application.properties</font>中删除，重启应用，再次访问浏览器，如下图，应用依然正常响应，list中只有成员变量message的内容：
      在这里插入图片描述

      编码获取配置项

    • 除了用ConfigProperty注解来获取配置项的值，还可以用写代码的方式获取

    • 下面的代码展示了通过API获取配置项的操作，请注意代码中的注释

      @Path("/actions")
public class HobbyResource {

  @GET
  @Produces(MediaType.TEXT_PLAIN)
  public String hello() {
      List<String> list = new ArrayList<>();

      // 可以用静态方法取得Config实例
      Config config = ConfigProvider.getConfig();

      // getValue可取得指定配置项的指定类型值
      String greet = config.getValue("greeting.message", String.class);

      list.add(greet);

      // getOptionalValue可以将配置项的值包状为Optional对象，如果配置项不存在，也不会报错
      Optional<String> optional = config.getOptionalValue("not.exists.config", String.class);

      // 函数式编程：只用optional中有对象时，才会执行list.add方法
      optional.ifPresent(list::add);

      return "Hello RESTEasy, " + LocalDateTime.now() + ", " + list;
  }
}
    • 当配置项not.exists.config不存在时，页面响应如下，只有greeting.message配置项的值：
      在这里插入图片描述
    • 配置项not.exists.config=123456时，页面响应如下，两个配置项的值都能成功获取：
      在这里插入图片描述

    • 另外，官方建议不要使用<font color="blue">System.getProperty(String) </font>和<font color="blue"> System.getEnv(String)</font>去获取配置项了，它们并非quarkus的API，因此quarkus配置相关的功能与它们并无关系（例如感知配置变化、自动转换类型等）

      配置接口

    • 假设配置项如下，都是相同的前缀<font color="blue">student</font>
    student.name=Tom
student.age=11
student.description=He is a good boy
    • 针对上述配置项，可以用注解<font color="red">ConfigMapping</font>将这些它们集中在一个接口类中获取，接口类StudentConfiguration.java如下
    package com.bolingcavalry;

import io.smallrye.config.ConfigMapping;
import io.smallrye.config.WithDefault;
import io.smallrye.config.WithName;

@ConfigMapping(prefix = "student")
public interface StudentConfiguration {
    /**
     * 名字与配置项一致
     * @return
     */
    String name();

    /**
     * 名字与配置项一致，自动转为int型
     * @return
     */
    int age();

    /**
     * 名字与配置项不一致时，用WithName注解指定配置项
     * @return
     */
    @WithName("description")
    String desc();

    /**
     * 用WithDefault注解设置默认值，如果配置项"student.favorite"不存在，则默认值生效
     * @return
     */
    @WithDefault("default from code")
    String favorite();
}
    • 从上述代码可见，一个接口即可完成所有配置项的注入，在使用这些配置项的时候，只要注入StudentConfiguration实例即可
    • 首先要用ConfigMapping指明配置项的前缀，该接口中的方法都对应具有此前缀的配置项
    • 一般情况下，方法名就等于配置项的名称，也可以用<font color="blue">WithName</font>指定配置项名称
    • 用<font color="blue">WithDefault</font>指定默认值，如果找不到配置项就用此默认值
    • 来看看如何使用这个配置接口，web服务代码如下，只要依赖注入StudentConfiguration即可，不在需要为每个配置项都用成员变量和ConfigProperty注解了
    package com.bolingcavalry;

import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import java.time.LocalDateTime;

@Path("/actions")
public class HobbyResource {

    @Inject
    StudentConfiguration student;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {

        return "Hello RESTEasy, "
                + LocalDateTime.now()
                + " [" + student.name() + "], "
                + " [" + student.age() + "], "
                + " [" + student.desc() + "], "
                + " [" + student.favorite() + "]";
    }
}
    • 运行代码，用浏览器访问web接口试试，如下图，所有配置项都能正确获取

    image-20220310082423348

    配置项是多个单词时，如何对应配置接口的方法？

    • 回顾刚才的配置，name、age、description这些都是单个单词，现在如果有个配置项是多个单词，例如<font color="blue">学号</font>的英文是<font color="red">student number</font>，应该如何转为StudentConfiguration接口的方法呢？
    • 首先要看您的匹配项的命名风格，对多个单词是如何分隔的，一般有这三种：
    • 减号分隔：student-number
    • 下划线分隔：student_number
    • 驼峰命名：studentNumber
    • ConfigMapping注解提供了namingStrategy的属性，其值有三种，分别对应上述三种命名风格，您根据自身情况选用即可
    1. KEBAB_CASE（默认值）：减号分隔的配置项转为驼峰命令的方法，配置项student-number对应的方法是studentNumber
    2. SNAKE_CASE：下划线分隔的配置项转为驼峰命令的方法，配置项student_number对应的方法是studentNumber
    3. VERBATIM：完全对应，不做任何转换，配置项student_number对应的方法是student_number
    • 使用namingStrategy属性的示例代码如下
    @ConfigMapping(prefix = "student", namingStrategy = ConfigMapping.NamingStrategy.SNAKE_CASE)
public interface StudentConfiguration {
    /**
     * 名字与配置项一致
     * @return
     */
    String name();
    ...

    配置接口嵌套

    • 再来看下面的配置，有两个配置项的前缀都是<font color="blue">student.address</font>，给人的感觉像是student对象里面有个成员变量是address类型的，而address有两个字段：province和city
    student.name=Tom
student.age=11
student.description=He is a good boy

student.address.province=guangdong
student.address.city=shenzhen
    • 针对上述配置，quarkus支持用接口嵌套来导入，具体做法分为两步，首先新增一个接口Address.java，源码如下
    package com.bolingcavalry;

public interface Address {
    String province();
    String city();
}
    • 第二步，在配置接口StudentConfiguration.java中，增加下图红框中的一行代码（接口中返回接口，形成接口嵌套）

    image-20220310083629464

    • 最后，修改HobbyResource.java代码，增加下图红框中的两行，验证能否正常取得address前缀的配置项目

    image-20220310083947856

    • 重启应用，如下图，配置项可以正常获取

    image-20220310084223359

    配置项转为map

    • 前面的接口嵌套，虽然将多层级的配置以对象的形式清晰的表达出来，但也引出一个问题：配置越多，接口定义或者接口方法就越多，代码随之增加
    • 如果配置项的层级简单，还有种简单的方式将其映射到配置接口中：转为map
    • 依然以下面的配置项为例
    student.address.province=guangdong
student.address.city=shenzhen
    • 对应的代码改动如下图，只要把address方法的返回值从<font color="blue">Address</font>改为<font color="red">Map<String, String></font>即可，这样修改后，address层级下面再增加配置项，也不用修改配置项有关的代码了：

    image-20220311080316711

    • 使用配置的业务代码也要改，如下图，改为从map中获取

    image-20220311080529522

    • 部署运行验证，可以正常取值

    image-20220311081214976

    内置配置项

    • quarkus有很多内置的配置项，例如web服务的端口<font color="blue">quarkus.http.port</font>就是其中一个，如果您熟悉SpringBoot的话，对这些内置配置项应该很好理解，数据库、消息、缓存，都有对应配置项
    • 篇幅所限就不在此讲解quarkus内置的配置项了，您可以参考这份官方提供的配置项列表，里面有详细说明：https://quarkus.io/guides/all-config
    • 上述文档中，有很多配置项带有加锁的图标，如下图红框所示，有这个图标的配置项，其值在应用构建的时候已经固定了，在应用运行期间始终保持只读状态
      在这里插入图片描述
    • 这种带有加锁图标的配置项的值，在应用运行期间真的不能改变了吗？其实还是有办法的，官方文档指明，如果业务的情况特殊，一定要变，就走热部署的途径，您可以参考《quarkus实战之四：远程热部署》
    • 官方对开发者的建议：在开发quarkus应用的时候，<font color="red">不要使用quarkus作为配置项的前缀</font>，因为目前quarkus框架及其插件们的配置项的前缀都是<font color="blue">quarkus</font>，应用开发应该避免和框架使用相同的配置项前缀，以免冲突
    • 至此，咱们已经学习了如何在quarkus应用中使用配置项，接下来还会一起实践更多的quarkus基础知识，锁定《quarkus实战》专辑，欣宸不会辜负您的期待

    欢迎关注思否：程序员欣宸

    学习路上，你不孤单，欣宸原创一路相伴...
    后端java云原生
    程序员欣宸
    147 声望24 粉丝

    热爱Java和Docker

    « 上一篇
    quarkus实战之六：配置
    下一篇 »
    quarkus实战之八：profile

    引用和评论

    推荐阅读
    头像
    quarkus依赖注入之十二：禁用类级别拦截器

    程序员欣宸阅读 428

    头像
    Jerry和您聊聊Chrome开发者工具

    注销赞 9阅读 4.4k评论 3

    头像
    在Java程序中监听mysql的binlog

    huan1993赞 9阅读 1.7k

    头像
    构建自定义Feign客户端demo

    zZ_jie赞 5阅读 865

    头像
    Bitmap 和 布隆过滤器傻傻分不清？你这不应该啊

    程序员小富赞 7阅读 1.2k

    头像
    Just for fun——迅速写完快速排序

    ufdf赞 3阅读 2.5k

    头像
    Spring 实现 3 种异步流式接口，干掉接口超时烦恼

    程序员小富赞 4阅读 1.5k

    0 条评论
    得票最新