@ConfigurationProperties 注解使用姿势

2023-11-04 05:30

本文主要是介绍@ConfigurationProperties 注解使用姿势,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

在编写项目代码时,我们要求更灵活的配置,更好的模块化整合。在 Spring Boot 项目中,为满足以上要求,我们将大量的参数配置在 application.properties 或 application.yml 文件中,通过 @ConfigurationProperties 注解,我们可以方便的获取这些参数值

使用 @ConfigurationProperties 配置模块

假设我们正在搭建一个发送邮件的模块。在本地测试,我们不想该模块真的发送邮件,所以我们需要一个参数来「开关」 disable 这个功能。另外,我们希望为这些邮件配置一个默认的主题,这样,当我们查看邮件收件箱,通过邮件主题可以快速判断出这是测试邮件

在 application.properties 文件中创建这些参数:

我们可以使用 @Value 注解或着使用 Spring Environment bean 访问这些属性,是这种注入配置方式有时显得很笨重。我们将使用更安全的方式(@ConfigurationProperties )来获取这些属性

@ConfigurationProperties 的基本用法非常简单:我们为每个要捕获的外部属性提供一个带有字段的类。请注意以下几点:

  • 前缀定义了哪些外部属性将绑定到类的字段上
  • 根据 Spring Boot 宽松的绑定规则,类的属性名称必须与外部属性的名称匹配
  • 我们可以简单地用一个值初始化一个字段来定义一个默认值
  • 类本身可以是包私有的
  • 类的字段必须有公共 setter 方法

Spring 宽松绑定规则 (relaxed binding)

Spring使用一些宽松的绑定属性规则。因此,以下变体都将绑定到 hostName 属性上:

如果我们将 MailModuleProperties 类型的 bean 注入到另一个 bean 中,这个 bean 现在可以以类型安全的方式访问那些外部配置参数的值。

但是,我们仍然需要让 Spring 知道我们的 @ConfigurationProperties 类存在,以便将其加载到应用程序上下文中( 面试还不知道 BeanFactory 和 ApplicationContext 的区别?)

激活 @ConfigurationProperties

对于 Spring Boot,创建一个 MailModuleProperties 类型的 bean,我们可以通过下面几种方式将其添加到应用上下文中

首先,我们可以通过添加 @Component 注解让 Component Scan 扫描到

很显然,只有当类所在的包被 Spring @ComponentScan 注解扫描到才会生效,默认情况下,该注解会扫描在主应用类下的所有包结构

我们也可以通过 Spring 的 Java Configuration 特性实现同样的效果:

只要 MailModuleConfiguration 类被 Spring Boot 应用扫描到,我们就可以在应用上下文中访问 MailModuleProperties bean

我们还可以使用 @EnableConfigurationProperties 注解让我们的类被 Spring Boot 所知道,在该注解中其实是用了@Import(EnableConfigurationPropertiesImportSelector.class) 实现,大家可以看一下

激活一个 @ConfigurationProperties 类的最佳方式是什么?

所有上述方法都同样有效。然而,我建议模块化你的应用程序,并让每个模块提供自己的@ConfigurationProperties 类,只提供它需要的属性,就像我们在上面的代码中对邮件模块所做的那样。这使得在不影响其他模块的情况下重构一个模块中的属性变得容易。

因此,我不建议在应用程序类本身上使用 @EnableConfigurationProperties,如许多其他教程中所示,是在特定于模块的 @Configuration 类上使用@EnableConfigurationProperties,该类也可以利用包私有的可见性对应用程序的其余部分隐藏属性。

无法转换的属性

如果我们在 application.properties 属性上定义的属性不能被正确的解析会发生什么?假如我们为原本应该为布尔值的属性提供的值为 'foo':

默认情况下,Spring Boot 将会启动失败,并抛出异常:

Failed to bind properties under 'myapp.mail.enabled' to java.lang.Boolean:Property: myapp.mail.enabledValue: fooOrigin: class path resource [application.properties]:1:20Reason: failed to convert java.lang.String to java.lang.Boolean

当我们为属性配置错误的值时,而又不希望 Spring Boot 应用启动失败,我们可以设置 ignoreInvalidFields 属性为 true (默认为 false)

这样,Spring Boot 将会设置 enabled 字段为我们在 Java 代码里设定好的默认值。如果我们没有设置默认值,enabled 将为 null,因为这里定义的是 boolean 的包装类 Boolean

未知的属性

和上面的情况有些相反,如果我们在 application.properties 文件提供了 MailModuleProperties 类不知道的属性会发生什么?

默认情况下,Spring Boot 会忽略那些不能绑定到 @ConfigurationProperties 类字段的属性

然而,当配置文件中有一个属性实际上没有绑定到 @ConfigurationProperties 类时,我们可能希望启动失败。也许我们以前使用过这个配置属性,但是它已经被删除了,这种情况我们希望被触发告知手动从 application.properties 删除这个属性

为了实现上述情况,我们仅需要将 ignoreUnknownFields 属性设置为 false (默认是 true)

现在,应用启动时,控制台会反馈我们异常信息

Binding to target [Bindable@cf65451 type = com.example.configurationproperties.properties.MailModuleProperties, value = 'provided', annotations = array<Annotation>[@org.springframework.boot.context.properties.ConfigurationProperties(value=myapp.mail, prefix=myapp.mail, ignoreInvalidFields=false, ignoreUnknownFields=false)]] failed:Property: myapp.mail.unknown-propertyValue: fooOrigin: class path resource [application.properties]:3:29Reason: The elements [myapp.mail.unknown-property] were left unbound.

弃用警告⚠️(Deprecation Warning)
ignoreUnknownFields 在未来 Spring Boot 的版本中会被标记为 deprecated,因为我们可能有两个带有 @ConfigurationProperties 的类,同时绑定到了同一个命名空间 (namespace) 上,其中一个类可能知道某个属性,另一个类却不知道某个属性,这样就会导致启动失败

启动时校验 @ConfigurationProperties

如果我们希望配置参数在传入到应用中时有效的,我们可以通过在字段上添加 bean validation 注解,同时在类上添加 @Validated 注解

如果我们忘记在 application.properties 文件设置 enabled 属性,并且设置 defaultSubject 为空

应用启动时,我们将会得到 BindValidationException

Binding to target org.springframework.boot.context.properties.bind.BindException: Failed to bind properties under 'myapp.mail' to com.example.configurationproperties.properties.MailModuleProperties failed:Property: myapp.mail.enabledValue: nullReason: must not be nullProperty: myapp.mail.defaultSubjectValue: nullReason: must not be empty

 

当然这些默认的验证注解不能满足你的验证要求,我们也可以自定义注解

如果你的验证逻辑很特殊,我们可以实现一个方法,并用 @PostConstruct 标记,如果验证失败,方法抛出异常即可, 关于 @PostConstruct,可以查看 Spring Bean 的生命周期,我从哪里来?

 

复杂属性类型

多数情况,我们传递给应用的参数是基本的字符串或数字。但是,有时我们需要传递诸如 List 的数据类型

List 和 Set

假如,我们为邮件模块提供了一个 SMTP 服务的列表,我们可以添加该属性到 MailModuleProperties 类中

我们有两种方式让 Spring Boot 自动填充该 list 属性

application.properties

在 application.properties 文件中以数组形式书写

application.yml

YAML 本身支持 list 类型,所以可以在 application.yml 文件中添加:

set 集合也是这种方式的配置方式,不再重复书写。另外YAML 是更好的阅读方式,层次分明,所以在实际应用中更推荐大家使用该种方式做数据配置

Duration

Spring Boot 内置支持从配置参数中解析 durations (持续时间),官网文档 给出了明确的说明

我们既可以配置毫秒数数值,也可配置带有单位的文本:

官网上已明确说明,配置 duration 不写单位,默认按照毫秒来指定,我们也可已通过 @DurationUnit 来指定单位:

常用单位如下:

  • ns for nanoseconds (纳秒)
  • us for microseconds (微秒)
  • ms for milliseconds (毫秒)
  • s for seconds (秒)
  • m for minutes (分)
  • h for hours (时)
  • d for days (天)

DataSize

与 Duration 的用法一毛一样,默认单位是 byte (字节),可以通过 @DataSizeUnit 单位指定:

添加配置

但是,我测试的时候打印出来结果都是以 B (bytes) 来显示

常见单位如下:

  • B for bytes
  • KB for kilobytes
  • MB for megabytes
  • GB for gigabytes
  • TB for terabytes

自定义类型

有些情况,我们想解析配置参数到我们自定义的对象类型上,假设,我们我们设置最大包裹重量:

在 MailModuleProperties 中添加 Weight 属性

我们可以模仿 DataSize 和 Duration 创造自己的 converter (转换器)

将其注册到 Spring Boot 上下文中

@ConfigurationPropertiesBinding 注解是让 Spring Boot 知道使用该转换器做数据绑定

使用 Spring Boot Configuration Processor 完成自动补全

我们向项目中添加依赖:

Maven

Gradle

重新 build 项目之后,configuration processor 会为我们创建一个 JSON 文件:

这样,当我们在 application.properties 和 application.yml 中写配置的时候会有自动提醒:

标记配置属性为 Deprecated

configuration processor 允许我们标记某一个属性为 deprecated

我们可以通过添加 @DeprecatedConfigurationProperty 注解到字段的 getter 方法上,来标示该字段为 deprecated,重新 build 项目,看看 JSON 文件发生了什么?

当我们再编写配置文件时,已经给出了明确 deprecated 提示:

总结

Spring Boot 的 @ConfigurationProperties 注解在绑定类型安全的 Java Bean 时是非常强大的,我们可以配合其注解属性和 @DeprecatedConfigurationProperty 注解获取到更友好的编程方式,同时这样让我们的配置更加模块化。

附加说明

以为 @ConfigurationProperties 注解满足我们的全部需要了吗?其实不然,Spring 官网明确给出了该注解和 @Value 注解的对比:

如果使用 SpEL 表达式,我们只能选择 @Value 注解

另外我之前在阅读 RabbitMQ 源码时,发现 RabbitProperties 类充分的利用了 @ConfigurationProperties 注解特性:

  • deprecated

  • Duration

  • Enum

  • 嵌套属性

感觉自己后知后觉,最近在思考,为什么小时候要阅读和背诵古诗词,文言文等经典,因为这样写文章就可以轻松熟练的引用经典。技术也一样,各种框架的源码就是学生时代的古诗词和文言文,我们要多多查看阅读,甚至背诵编程思想,这样就可以写出越来越优雅的代码

关于 @ConfigurationProperties 注解的使用,这里推荐 RabbitMQ Github 源码,只需看这一个类就可以,知道怎样充分利用这个注解.

Demo 代码获取,回复公众号「demo」,打开链接查看对应的子文件夹即可

灵魂追问

  1. 在实际项目中, 你能够充分利用这些特性让你的配置更灵活和模块化吗?
  2. 阅读框架源码时,他们都是怎样配置的呢?
  3. @Value 注解怎样给出默认值?

这篇关于@ConfigurationProperties 注解使用姿势的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/343571

相关文章

中文分词jieba库的使用与实景应用(一)

知识星球:https://articles.zsxq.com/id_fxvgc803qmr2.html 目录 一.定义: 精确模式(默认模式): 全模式: 搜索引擎模式: paddle 模式(基于深度学习的分词模式): 二 自定义词典 三.文本解析   调整词出现的频率 四. 关键词提取 A. 基于TF-IDF算法的关键词提取 B. 基于TextRank算法的关键词提取

使用SecondaryNameNode恢复NameNode的数据

1)需求: NameNode进程挂了并且存储的数据也丢失了,如何恢复NameNode 此种方式恢复的数据可能存在小部分数据的丢失。 2)故障模拟 (1)kill -9 NameNode进程 [lytfly@hadoop102 current]$ kill -9 19886 (2)删除NameNode存储的数据(/opt/module/hadoop-3.1.4/data/tmp/dfs/na

Hadoop数据压缩使用介绍

一、压缩原则 (1)运算密集型的Job,少用压缩 (2)IO密集型的Job,多用压缩 二、压缩算法比较 三、压缩位置选择 四、压缩参数配置 1)为了支持多种压缩/解压缩算法,Hadoop引入了编码/解码器 2)要在Hadoop中启用压缩,可以配置如下参数

Makefile简明使用教程

文章目录 规则makefile文件的基本语法:加在命令前的特殊符号:.PHONY伪目标: Makefilev1 直观写法v2 加上中间过程v3 伪目标v4 变量 make 选项-f-n-C Make 是一种流行的构建工具,常用于将源代码转换成可执行文件或者其他形式的输出文件(如库文件、文档等)。Make 可以自动化地执行编译、链接等一系列操作。 规则 makefile文件

使用opencv优化图片(画面变清晰)

文章目录 需求影响照片清晰度的因素 实现降噪测试代码 锐化空间锐化Unsharp Masking频率域锐化对比测试 对比度增强常用算法对比测试 需求 对图像进行优化,使其看起来更清晰,同时保持尺寸不变,通常涉及到图像处理技术如锐化、降噪、对比度增强等 影响照片清晰度的因素 影响照片清晰度的因素有很多,主要可以从以下几个方面来分析 1. 拍摄设备 相机传感器:相机传

pdfmake生成pdf的使用

实际项目中有时会有根据填写的表单数据或者其他格式的数据,将数据自动填充到pdf文件中根据固定模板生成pdf文件的需求 文章目录 利用pdfmake生成pdf文件1.下载安装pdfmake第三方包2.封装生成pdf文件的共用配置3.生成pdf文件的文件模板内容4.调用方法生成pdf 利用pdfmake生成pdf文件 1.下载安装pdfmake第三方包 npm i pdfma

零基础学习Redis(10) -- zset类型命令使用

zset是有序集合,内部除了存储元素外,还会存储一个score,存储在zset中的元素会按照score的大小升序排列,不同元素的score可以重复,score相同的元素会按照元素的字典序排列。 1. zset常用命令 1.1 zadd  zadd key [NX | XX] [GT | LT]   [CH] [INCR] score member [score member ...]

git使用的说明总结

Git使用说明 下载安装(下载地址) macOS: Git - Downloading macOS Windows: Git - Downloading Windows Linux/Unix: Git (git-scm.com) 创建新仓库 本地创建新仓库:创建新文件夹,进入文件夹目录,执行指令 git init ,用以创建新的git 克隆仓库 执行指令用以创建一个本地仓库的

【北交大信息所AI-Max2】使用方法

BJTU信息所集群AI_MAX2使用方法 使用的前提是预约到相应的算力卡,拥有登录权限的账号密码,一般为导师组共用一个。 有浏览器、ssh工具就可以。 1.新建集群Terminal 浏览器登陆10.126.62.75 (如果是1集群把75改成66) 交互式开发 执行器选Terminal 密码随便设一个(需记住) 工作空间:私有数据、全部文件 加速器选GeForce_RTX_2080_Ti

【Linux 从基础到进阶】Ansible自动化运维工具使用

Ansible自动化运维工具使用 Ansible 是一款开源的自动化运维工具,采用无代理架构(agentless),基于 SSH 连接进行管理,具有简单易用、灵活强大、可扩展性高等特点。它广泛用于服务器管理、应用部署、配置管理等任务。本文将介绍 Ansible 的安装、基本使用方法及一些实际运维场景中的应用,旨在帮助运维人员快速上手并熟练运用 Ansible。 1. Ansible的核心概念