@ConfigurationProperties 注解使用姿式，这一篇就够了

时间 2019-12-20

标签 configurationproperties 注解使用一篇够了繁體版

原文原文链接

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

使用 @ConfigurationProperties 配置模块

假设咱们正在搭建一个发送邮件的模块。在本地测试，咱们不想该模块真的发送邮件，因此咱们须要一个参数来「开关」 disable 这个功能。另外，咱们但愿为这些邮件配置一个默认的主题，这样，当咱们查看邮件收件箱，经过邮件主题能够快速判断出这是测试邮件java

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

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

@ConfigurationProperties 的基本用法很是简单:咱们为每一个要捕获的外部属性提供一个带有字段的类。请注意如下几点:面试

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

Spring 宽松绑定规则 (relaxed binding)

Spring使用一些宽松的绑定属性规则。所以，如下变体都将绑定到 hostName 属性上:spring

若是咱们将 MailModuleProperties 类型的 bean 注入到另外一个 bean 中，这个 bean 如今能够以类型安全的方式访问那些外部配置参数的值。shell

可是，咱们仍然须要让 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.enabled
    Value: foo
    Origin: class path resource [application.properties]:1:20
    Reason: 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-property
    Value: foo
    Origin: class path resource [application.properties]:3:29
    Reason: 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.enabled
    Value: null
    Reason: must not be null

    Property: myapp.mail.defaultSubject
    Value: null
    Reason: must not be empty

固然这些默认的验证注解不能知足你的验证要求，咱们也能够自定义注解

若是你的验证逻辑很特殊，咱们能够实现一个方法，并用 @PostConstruct 标记，若是验证失败，方法抛出异常便可, 关于 @PostConstruct，能够查看 Spring Bean 的生命周期，我从哪里来？