Spring 类型安全的配置属性

使用 @Value("${property}") 注解来注入配置属性有时会很麻烦,特别是当你要处理多个属性或你的数据是分层的。 Spring Boot提供了一种处理属性的替代方法,让强类型的Bean管理和验证你的应用程序的配置。

另请参见@Value 和类型安全配置属性之间的区别。

一、 JavaBean 属性绑定

如下面的例子所示,可以绑定一个声明了标准JavaBean属性的bean。

Java

Kotlin

@ConfigurationProperties("my.service")
public class MyProperties {

    private boolean enabled;

    private InetAddress remoteAddress;

    private final Security security = new Security();

    // getters / setters...

    public static class Security {

        private String username;

        private String password;

        private List roles = new ArrayList<>(Collections.singleton("USER"));

        // getters / setters...

    }

}

前面的POJO定义了以下属性。

  • my.service.enabled,默认值为`false`。
  • my.service.remote-address,其类型可由`String`强制提供。
  • my.service.security.username,有一个嵌套的 security 对象,其名称由该属性的名称决定。 特别是,那里完全没有使用类型,可以是 SecurityProperties。
  • my.service.security.password.
  • my.service.security.role,有一个 String 的集合,默认为 USER。

映射到Spring Boot中可用的 @ConfigurationProperties 类的属性,通过properties文件、YAML文件、环境变量和其他机制进行配置,这些属性是公共API,但类本身的 getters/setters 并不意味着可以直接使用(一句话,Spring也是通过getter/setter这些public方法进行设置值的,你别用)。

这样的设计依赖于一个默认的无参构造函数,getter和setter通常是必须的,因为绑定是通过标准的Java Beans property descriptor(Java内省)实现的,就像在Spring MVC中一样。 在以下情况下,可以省略setter。

  • Map, 只要它们被初始化,就需要一个getter,但不一定需要一个setter,因为它们可以被绑定器突变。
  • Collection和array 可以通过索引(通常用YAML)或使用单个逗号分隔的值(属性)来访问。 在后一种情况下,一个setter是必须的。 我们建议总是为这类类型添加一个setter。 如果你初始化一个集合,确保它不是不可变的(如前面的例子)。
  • 如果嵌套的POJO属性被初始化(就像前面例子中的 Security 字段),就不需要setter。 如果你想让绑定器通过使用它的默认构造函数来即时创建实例,你需要一个setter。

有些人使用Project Lombok来自动添加getter和setter。 请确保Lombok不会为这样的类型生成任何特定的构造函数,因为它被容器自动用来实例化对象。

最后,只考虑标准的Java Bean属性,不支持对静态属性的绑定。

二、 构造函数绑定

上一节的例子可以用不可变的方式重写,如下例所示。

Java

@ConfigurationProperties("my.service")
public class MyProperties {

    // fields...

    public MyProperties(boolean enabled, InetAddress remoteAddress, Security security) {
        this.enabled = enabled;
        this.remoteAddress = remoteAddress;
        this.security = security;
    }

    // getters...

    public static class Security {

        // fields...

        public Security(String username, String password, @DefaultValue("USER") List roles) {
            this.username = username;
            this.password = password;
            this.roles = roles;
        }

        // getters...

    }

}

在这种设置中,唯一的“带参数构造函数”的存在意味着应该使用该构造函数进行绑定。 这意味着绑定器会找到一个带有你希望绑定的参数的构造函数。 如果你的类有多个构造函数,可以使用 @ConstructorBinding 注解来指定使用哪个构造函数进行构造函数绑定。 如果要为一个只有一个“带参数构造函数”的类选择不绑定构造函数,该构造函数必须用 @Autowired 来注解。 构造函数绑定可以与 Record 一起使用。 除非你的记录有多个构造函数,否则没有必要使用 @ConstructorBinding。

构造函数绑定类的嵌套成员(如上面例子中的 Security)也将通过其构造函数被绑定。

默认值可以在构造函数参数和Record组件上使用 @DefaultValue 来指定。 转换服务将被应用于将注解的 String 值强制转换为缺失属性的目标类型。

参考前面的例子,如果没有属性绑定到 Security , MyProperties 实例将包含一个 security 类型的 null 值。 为了使它包含一个非 null 的 Security 实例,即使没有属性与之绑定(当使用Kotlin时,这将要求 Security 的 username 和 password 参数被声明为 nullable,因为它们没有默认值),使用一个空的 @DefaultValue 注解。

Java

Kotlin

public MyProperties(boolean enabled, InetAddress remoteAddress, @DefaultValue Security security) {
    this.enabled = enabled;
    this.remoteAddress = remoteAddress;
    this.security = security;
}

要使用构造函数绑定,该类必须使用 @EnableConfigurationProperties 或配置属性扫描来启用。 你不能对通过常规Spring机制创建的Bean使用构造函数绑定(例如 @Component Bean,通过使用 @Bean 方法创建的Bean或通过使用 @Import 加载的Bean)。

要在原生镜像中使用构造函数绑定,必须用 -parameters 参数编译该类。如果你使用 Spring Boot 的 Gradle 插件或使用 Maven 和 spring-boot-starter-parent,这将自动配置。

不建议将 java.util.Optional 与 @ConfigurationProperties 一起使用,因为它主要是作为一个返回类型使用。 因此,它并不适合配置属性注入。 为了与其他类型的属性保持一致,如果你确实声明了一个 Optional 属性,但它没有值,null 而不是一个空的 Optional 将被绑定。

三、 启用 @ConfigurationProperties 类

Spring Boot提供了绑定 @ConfigurationProperties 类型并将其注册为Bean的基础设施。 你可以在逐个类的基础上启用配置属性,或者启用配置属性扫描,其工作方式与组件扫描类似。

有时,用 @ConfigurationProperties 注解的类可能不适合扫描,例如,如果你正在开发你自己的自动配置或者你想有条件地启用它们。 在这些情况下,使用 @EnableConfigurationProperties 注解指定要处理的类型列表, 它可以注解在任何 @Configuration 类上,如下面的例子所示。

Java

@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(SomeProperties.class)
public class MyConfiguration {

}

Java

@ConfigurationProperties("some.properties")
public class SomeProperties {

}

要使用配置属性扫描,请向你的application添加 @ConfigurationPropertiesScan 注解。 通常,它被添加到用 @SpringBootApplication 注解的main类中,但它也可以被添加到任何 @Configuration 类上。 默认情况下,扫描会从注解所在的包开始,你如果想自定义扫描其他包,可以参考如下。

Java

@SpringBootApplication
@ConfigurationPropertiesScan({ "com.example.app", "com.example.another" })
public class MyApplication {

}

当 @ConfigurationProperties Bean使用配置属性扫描或通过 @EnableConfigurationProperties 注册时,该Bean有一个常规名称:-,其中 是 @ConfigurationProperties 注解中指定的环境键前缀, 是Bean的完全限定名称。 如果注解没有提供任何前缀,则只使用Bean的完全限定名称。

假设它在 com.example.app 包中,上面的 SomeProperties 例子的 bean 名称是 some.properties-com.example.app.SomeProperties。

我们建议 @ConfigurationProperties 只处理 environment,特别是不从上下文注入其他Bean。 对于边角案例(特殊情况),可以使用 setter 注入或框架提供的任何 *Aware 接口(如 EnvironmentAware ,如果你需要访问 Environment)。 如果你仍然想使用构造器注入其他Bean,配置属性Bean必须用 @Component 来注解,并使用基于JavaBean的属性绑定。

四、 使用 @ConfigurationProperties 类

这种配置方式与 SpringApplication 外部YAML配置配合得特别好,如以下例子所示。

my:
  service:
    remote-address: 192.168.1.1
    security:
      username: "admin"
      roles:
      - "USER"
      - "ADMIN"

要使用 @ConfigurationProperties Bean,你可以用与其他Bean相同的方式注入它们,如下例所示。

Java

@Service
public class MyService {

    private final MyProperties properties;

    public MyService(MyProperties properties) {
        this.properties = properties;
    }

    public void openConnection() {
        Server server = new Server(this.properties.getRemoteAddress());
        server.start();
        // ...
    }

    // ...

}

使用 @ConfigurationProperties 还可以让你生成元数据文件,这些文件可以被IDE用来配置属性的“自动补全”功能。 详情见附录。

五、第三方配置

除了使用 @ConfigurationProperties 来注解一个类之外,你还可以在公共的 @Bean 方法上使用它。 当你想把属性绑定到你控制之外的第三方组件时,这样做特别有用。

要从 Environment 属性中配置一个Bean,请在其Bean注册中添加 @ConfigurationProperties ,如下例所示。

Java

@Configuration(proxyBeanMethods = false)
public class ThirdPartyConfiguration {

    @Bean
    @ConfigurationProperties(prefix = "another")
    public AnotherComponent anotherComponent() {
        return new AnotherComponent();
    }

}

任何用 another 前缀定义的JavaBean属性都会被映射到 AnotherComponent Bean上,其方式类似于前面的 SomeProperties 例子。

六、 宽松的绑定

Spring Boot在将 Environment 属性绑定到 @ConfigurationProperties bean时使用了一些宽松的规则,因此 Environment 属性名称和bean属性名称之间不需要完全匹配。 这很有用,常见的例子包括破折号分隔的属性名称(例如, context-path 绑定到 contextPath ),和大写的属性名称(例如,PORT 绑定到 port )。

演示一个例子,考虑以下 @ConfigurationProperties 类。

Java

@ConfigurationProperties(prefix = "my.main-project.person")
public class MyPersonProperties {

    private String firstName;

    public String getFirstName() {
        return this.firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

}

对以上的代码来说,以下的属性名称都可以使用。

Table 3. relaxed binding

Property

Note

my.main-project.person.first-name

Kebab 风格(短横线隔开),建议在 .properties 和 YAML 文件中使用。

my.main-project.person.firstName

标准的驼峰语法。

my.main-project.person.first_name

下划线,这是一种用于 .properties 和 YAML 文件的替代格式。

MY_MAINPROJECT_PERSON_FIRSTNAME

大写格式,在使用系统环境变量时建议使用大写格式。

注解的 prefix 值 必须 是kebab风格(小写并以 - 分隔,如 my.main-project.person )。

Table 4. 每种属性源的宽松绑定规则

属性源

简单的

列表

Properties 文件

驼峰, kebab , 下划线

使用 [ ] 或逗号分隔值的标准列表语法

YAML 文件

驼峰, kebab , 下划线

标准YAML列表语法或逗号分隔的值

环境变量

大写,下划线为分隔符(见 从环境变量绑定).

Numeric values surrounded by underscores (see 从环境变量绑定)

系统属性(System properties)

驼峰, kebab , 下划线

使用 [ ] 或逗号分隔值的标准列表语法

我们建议,在可能的情况下,属性应以小写的kebab格式存储,例如 my.person.first-name=Rod 。 

绑定Map

当绑定到 Map 属性时,你可能需要使用一个特殊的括号符号,以便保留原始的 key 值。 如果key没有被 [ ] 包裹,任何非字母数字、- 或 . 的字符将被删除。

例如,考虑将以下属性绑定到一个 Map

Properties

Yaml

my.map.[/key1]=value1
my.map.[/key2]=value2
my.map./key3=value3

对于YAML文件,括号需要用引号包裹,以使key被正确解析。

上面的属性将绑定到一个 Map ,/key1,/key2 和 key3 作为map的key。 斜线已经从 key3 中删除,因为它没有被方括号包裹。

当绑定到标量值时,带有 . 的键不需要用 [] 包裹。 标量值包括枚举和所有 java.lang 包中的类型,除了 Object 。 将 a.b=c 绑定到 Map 将保留键中的 . ,并返回一个带有 {"a.b"="c"} Entry的Map。 对于任何其他类型,如果你的 key 包含 . ,你需要使用括号符号。 例如,将 a.b=c 绑定到 Map 将返回一个带有 {"a"={"b"="c"} entry的Map,而 [a.b]=c 将返回一个带有 {"a.b"="c"} entry 的Map。

从环境变量绑定

例如,Linux shell变量只能包含字母(a 到 z 或 A 到 Z )、数字( 0 到 9 )或下划线字符( _ )。 按照惯例,Unix shell变量的名称也将采用大写字母。

Spring Boot宽松的绑定规则被设计为尽可能地与这些命名限制兼容。

要将规范形式的属性名称转换为环境变量名称,你可以遵循这些规则。

  • 用下划线(_)替换点(.)。
  • 删除任何破折号(-)。
  • 转换为大写字母。

例如,配置属性 spring.main.log-startup-info 将是一个名为 SPRING_MAIN_LOGSTARTUPINFO 的环境变量。

环境变量也可以在绑定到对象列表(List)时使用。 要绑定到一个 List,在变量名称中,元素编号(索引)应该用下划线包裹。

例如,配置属性 my.service[0].other 将使用一个名为 MY_SERVICE_0_OTHER 的环境变量。

七、 合并复杂的类型

当List被配置在多个地方时,覆盖的作用是替换整个list。

例如,假设一个 MyPojo 对象的 name 和 description 属性默认为 null。 下面的例子从 MyProperties 中暴露了一个 MyPojo 对象的列表。

Java

@ConfigurationProperties("my")
public class MyProperties {

    private final List list = new ArrayList<>();

    public List getList() {
        return this.list;
    }

}

考虑以下配置。

Properties

Yaml

my.list[0].name=my name
my.list[0].description=my description
#---
spring.config.activate.on-profile=dev
my.list[0].name=my another name

如果 dev 配置文件未被激活,MyProperties.list 包含一个 MyPojo 条目,如之前定义的那样。 然而,如果 dev 配置文件被激活,list 仍然只包含一个条目(name 为 my another name,description为 null)。 这种配置不会在列表中添加第二个 MyPojo 实例,也不会合并项目。

当一个 List 在多个配置文件中被指定时,将使用具有最高优先级的那个(并且只有那个)。 考虑下面的例子。

Properties

Yaml

my.list[0].name=my name
my.list[0].description=my description
my.list[1].name=another name
my.list[1].description=another description
#---
spring.config.activate.on-profile=dev
my.list[0].name=my another name

在前面的例子中,如果 dev 配置文件是激活的,MyProperties.list 包含 一个 MyPojo 条目(name 是 my another name,description是 null)。 对于YAML,逗号分隔的列表和YAML列表都可以用来完全覆盖列表的内容。

对于 Map 属性,你可以用从多个来源获取的属性值进行绑定。 然而,对于多个来源中的同一属性,使用具有最高优先级的那个。 下面的例子从 MyProperties 暴露了一个 Map

Java

Kotlin

@ConfigurationProperties("my")
public class MyProperties {

    private final Map map = new LinkedHashMap<>();

    public Map getMap() {
        return this.map;
    }

}

考虑以下配置。

Properties

Yaml

my.map.key1.name=my name 1
my.map.key1.description=my description 1
#---
spring.config.activate.on-profile=dev
my.map.key1.name=dev name 1
my.map.key2.name=dev name 2
my.map.key2.description=dev description 2

如果 dev 配置文件没有激活,MyProperties.map 包含一个key为 key1 的条目(name为 my name 1 ,description为 my description 1 )。 然而,如果 dev 配置文件被激活,map 包含两个条目,key为 key1 (name为 dev name 1,description为 my description 1 )和 key2(name为 dev name 2,description为 dev description 2)。

前面的合并规则适用于所有属性源的属性,而不仅仅是文件。

八、属性(Properties)转换

当Spring Boot与 @ConfigurationProperties Bean绑定时,它试图将外部application properties强制改为正确的类型。 如果你需要自定义类型转换,你可以提供一个 ConversionService bean(Bean的名称为 conversionService )或自定义属性编辑器(通过 CustomEditorConfigurer bean)或自定义 Converters Bean(使用 @ConfigurationPropertiesBinding 注解)。

由于这个Bean是在应用程序生命周期的早期被请求的,请确保限制你的 ConversionService 所使用的依赖关系。 通常情况下,你所需要的任何依赖关系在创建时可能没有完全初始化。 如果你的自定义 ConversionService 不需要配置keys coercion,你可能想重命名它,并且只依赖用 @ConfigurationPropertiesBinding 限定的自定义转换器。

转换为 Duration

Spring Boot对表达持续时间有专门的支持。 如果你公开了一个 java.time.Duration 属性,application properties中的以下格式就可用。

  • 普通的 long (使用毫秒作为默认单位,除非指定了 @DurationUnit )。
  • 标准的ISO-8601格式 由 java.time.Duration 使用。
  • 一个更易读的格式,其中值和单位是耦合的(10s 表示10秒)。

请考虑以下例子。

Java

@ConfigurationProperties("my")
public class MyProperties {

    @DurationUnit(ChronoUnit.SECONDS)
    private Duration sessionTimeout = Duration.ofSeconds(30);

    private Duration readTimeout = Duration.ofMillis(1000);

    // getters / setters...

}

要指定一个30秒的会话超时, 30 、 PT30S 和 30s 都是等价的。 读取超时为500ms,可以用以下任何一种形式指定。 500, PT0.5S 和 500ms.

你也可以使用如下支持的时间单位。

  • ns 纳秒
  • us 微秒
  • ms 毫秒
  • s 秒
  • m 分
  • h 小时
  • d 天

默认单位是毫秒,可以使用 @DurationUnit 来重写,如上面的例子所示。

如果你喜欢使用构造函数绑定,同样的属性可以被暴露出来,如下面的例子所示。

Java

@ConfigurationProperties("my")
public class MyProperties {

    // fields...

    public MyProperties(@DurationUnit(ChronoUnit.SECONDS) @DefaultValue("30s") Duration sessionTimeout,
            @DefaultValue("1000ms") Duration readTimeout) {
        this.sessionTimeout = sessionTimeout;
        this.readTimeout = readTimeout;
    }

    // getters...

}

 如果你要升级一个 Long 的属性,如果它不是毫秒,请确保定义单位(使用 @DurationUnit )。 这样做提供了一个透明的升级路径,同时支持更丰富的格式

转换为期间(Period)

除了duration,Spring Boot还可以使用 java.time.Period 类型。 以下格式可以在application properties中使用。

  • 一个常规的 int 表示法(使用天作为默认单位,除非指定了 @PeriodUnit )。
  • 标准的ISO-8601格式 由 java.time.Period 使用。
  • 一个更简单的格式,其中值和单位对是耦合的( 1y3d 表示1年3天)。

支持下列简单的单位格式。

  • y 年
  • m 月
  • w 周
  • d 日

java.time.Period 类型实际上从未存储过周数,它是一个快捷方式,意味着 “7天”。

转换为数据大小(Data Sizes)

Spring Framework有一个 DataSize 值类型,以字节为单位表达大小。 如果你公开了一个 DataSize 属性,application properties中的以下格式就可用。

  • 一个常规的 long 表示(使用字节作为默认单位,除非指定了 @DataSizeUnit)。
  • 一个更易读的格式,其中值和单位是耦合的(10MB 意味着10兆字节)。

考虑以下例子。

Java

Kotlin

@ConfigurationProperties("my")
public class MyProperties {

    @DataSizeUnit(DataUnit.MEGABYTES)
    private DataSize bufferSize = DataSize.ofMegabytes(2);

    private DataSize sizeThreshold = DataSize.ofBytes(512);

    // getters/setters...

}

要指定一个10兆字节(Mb)的缓冲区大小, 10 和 10MB 是等价的。 256字节的大小阈值可以指定为 256 或 256B。

你也可以使用如下这些支持的单位。

  • B 字节
  • KB KB
  • MB MB
  • GB GB
  • TB TB

默认单位是字节,可以使用 @DataSizeUnit 来重写,如上面的例子所示。

如果你喜欢使用构造函数绑定,同样的属性可以被暴露出来,如下面的例子所示。

Java

@ConfigurationProperties("my")
public class MyProperties {

    // fields...

    public MyProperties(@DataSizeUnit(DataUnit.MEGABYTES) @DefaultValue("2MB") DataSize bufferSize,
            @DefaultValue("512B") DataSize sizeThreshold) {
        this.bufferSize = bufferSize;
        this.sizeThreshold = sizeThreshold;
    }

    // getters...

}

如果你正在升级一个 Long 属性,确保定义单位(使用 @DataSizeUnit),如果它不是字节。 这样做提供了一个透明的升级路径,同时支持更丰富的格式。 

九、@ConfigurationProperties 校验

只要使用Spring的 @Validated 注解,Spring Boot就会尝试验证 @ConfigurationProperties 类。 你可以直接在你的配置类上使用JSR-303的 jakarta.validation 约束注解。 要做到这一点,请确保你的classpath上有一个兼容的JSR-303实现,然后将约束注解添加到你的字段中,如下面的例子所示。

Java

@ConfigurationProperties("my.service")
@Validated
public class MyProperties {

    @NotNull
    private InetAddress remoteAddress;

    // getters/setters...

}

你也可以通过在 configuration properties 的 @Bean 方法上注解 @Validated 来触发验证。 

为了确保总是为嵌套的属性触发验证,即使没有找到属性,相关的字段必须用 @Valid 来注释。 下面的例子建立在前面的 MyProperties 的基础上。

Java

@ConfigurationProperties("my.service")
@Validated
public class MyProperties {

    @NotNull
    private InetAddress remoteAddress;

    @Valid
    private final Security security = new Security();

    // getters/setters...

    public static class Security {

        @NotEmpty
        private String username;

        // getters/setters...

    }

}

你也可以通过创建一个名为 configurationPropertiesValidator 的bean定义来添加一个自定义的Spring Validator。 @Bean 方法应该被声明为 static。 配置属性验证器是在应用程序生命周期的早期创建的,将 @Bean 方法声明为静态,可以让Bean的创建不需要实例化 @Configuration 类。 这样做可以避免过早实例化可能引起的任何问题。

spring-boot-actuator 模块包括一个暴露所有 @ConfigurationProperties Bean 的端点。 你可以通过浏览器访问 /actuator/configprops 或使用相应的JMX端点。 详情见"生产就绪"部分。

十、@ConfigurationProperties vs. @Value

@Value 注解是一个核心的容器功能,它不提供与类型安全的配置属性相同的功能。 下表总结了 @ConfigurationProperties 和 @Value 所支持的功能。

功能

@ConfigurationProperties

@Value

宽松绑定

Yes

有限制 (见 下文注释)

支持 Meta-data

Yes

No

SpEL 表达式

No

Yes

如果你确实想使用 @Value,我们建议你使用属性名称的规范形式(仅使用小写字母的kebab-case)来引用属性名称。 这将允许Spring Boot使用与 宽松绑定 @ConfigurationProperties 时相同的逻辑。

例如,@Value("${demo.item-price}") 将从 application.properties 文件中获取 demo.item-price 和 demo.itemPrice 形式,以及从系统环境中获取 DEMO_ITEMPRICE。 如果你用 @Value("${demo.itemPrice}") 代替,demo.item-price 和 DEMO_ITEMPRICE 将不会被考虑。

如果你为你自己的组件定义了一组配置键,我们建议你将它们分组在一个用 @ConfigurationProperties 注解的POJO中。 这样做将为你提供结构化的、类型安全的对象,你可以将其注入到你自己的bean中。

来自应用application property 文件的 SpEL 表达式在解析这些文件和填充environment时不会被处理。 然而,可以在 @Value 中写一个 SpEL 表达式。 如果来自应用程序属性文件的属性值是一个 SpEL 表达式,它将在被 @Value 消费时被解析。

你可能感兴趣的:(#,Spring,专栏,spring,安全,sql)