利用 Spring Boot 中的 @ConfigurationProperties,优雅绑定配置参数

使用 @Value("${property}") 注释注入配置属性有时会很麻烦,尤其是当你使用多个属性或你的数据是分层的时候。

Spring Boot 引入了一个可替换的方案 —— @ConfigurationProperties 来注入属性。

JavaBean 属性绑定

@Data
@ConfigurationProperties("my.service")
public class MyProperties { // 我们可以简单地用一个值初始化一个字段来定义一个默认值
private boolean enabled = true; private InetAddress remoteAddress; private final Security security = new Security(); @Data
public static class Security { private String username; private String password;
// 如果这个属性配置的话,默认是“USER”
private List<String> roles = new ArrayList<>(Collections.singleton("USER")); }
}

在配置文件中进行如下配置:

my:
service:
enabled: true
remoteAddress: 127.0.0.1
security:
username: csx
password: passwoed
roles:
- role1
- role2

最后生成的 Bean 的属性如下:

{
"enabled": true,
"remoteAddress": "127.0.0.1",
"security": {
"username": "csx",
"password": "passwoed",
"roles": [
"role1",
"role2"
]
}
}

以上的绑定当时需要提供默认的构造函数,以及get/setter方法。

并且不支持 JavaBean 中的静态成员变量的数据绑定

另外,@ConfigurationProperties 还有两个其他属性。

@ConfigurationProperties( value = "my.service",
ignoreInvalidFields = false,
ignoreUnknownFields = false)

ignoreInvalidFields:是否忽略非法值,比如将一个字符串 “foo” 赋值给 bool 值,不忽略的话会报启动异常。

ignoreUnknownFields:对于多余的配置是否会报异常。

构造函数绑定

有些情况下,我们需要绑定的 JavaBean 是不可变的(防止配置注入 Bean 以后,开发者在程序中错误地将配置改掉了)。这种情况下我们可以使用构造函数形式的绑定,只提供 getter 方法。

@Getter
@ConstructorBinding
@ConfigurationProperties("my.service")
public class MyProperties { private boolean enabled;
private InetAddress remoteAddress;
private final Security security; public MyProperties(boolean enabled, InetAddress remoteAddress, Security security) {
this.enabled = enabled;
this.remoteAddress = remoteAddress;
this.security = security;
} @Getter
public static class Security { private String username;
private String password;
private List<String> roles; public Security(String username, String password, @DefaultValue("USER") List<String> roles) {
this.username = username;
this.password = password;
this.roles = roles;
}
}
}

@DefaultValue 可以指定默认值。

使用构造函数绑定的方式,只能 @EnableConfigurationProperties 或者 @ConfigurationPropertiesScan 的方式激活 Bean。而不能使用 @Component、@Bean 或者 @Import 的方式进行数据绑定。

如果你的类有多个构造函数,可以直接指定使用哪个。

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

激活方式

方式一:添加 @Component 注解

上面的方式需要保证 MyProperties 能被 Spring 扫到。

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

方式二:通过 @Bean 方法

@Configuration
public class ServiceConfig { @Bean
public MyProperties myProperties(){
return new MyProperties();
}
}

方式三:@EnableConfigurationProperties(推荐)

@Configuration
@EnableConfigurationProperties(MyProperties.class)
public class ServiceConfig { }

方式四:@ConfigurationPropertiesScan

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

怎么使用

我们通过配置在 Spring 容器中生成了配置 Bean,那么需要怎么使用他们呢?

@Service
public class MyService {
// 依赖注入
@Autowired
private MyProperties properties; public void service(){
System.out.println(properties.getRemoteAddress());
} } @Service
public class MyService { private MyProperties properties;
// 通过构造函数注入,一般推荐这种方式
public MyService(MyProperties properties) {
this.properties = properties;
} public void service(){
System.out.println(properties.getRemoteAddress());
} }

给第三方类绑定值

假如某些类不是你自己开发的,你也想使用 @ConfigurationProperties 的方式给他绑定值,那么可以进行下面的方式进行配置。

@Configuration(proxyBeanMethods = false)
public class ThirdPartyConfiguration { @Bean
@ConfigurationProperties(prefix = "another")
public AnotherComponent anotherComponent() {
return new AnotherComponent();
} }

宽松绑定原则(Relaxed Binding)

所谓的宽松绑定原则是指:并不是 JavaBean 中的属性必须要和配置文件中的一致才能绑定数据,context-path 也能绑定到 contextPath 属性上。下面举个列子:

@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;
} }

下面的几种方式,都能将配置文件或者环境变量中的值绑定到 firstName 上。

形式 使用场景
my.main-project.person.first-name 推荐使用在 .properties and .yml files.
my.main-project.person.firstName Standard camel case syntax.
my.main-project.person.first_name 推荐使用在 .properties and .yml files.
MY_MAINPROJECT_PERSON_FIRSTNAME 推荐使用在系统环境变量读取配置时使用

和 @Value 对比

@Value 是 Spring Framework 中的注解,而 @ConfigurationProperties 是在 Spring Boot 中引入的。

利用 Spring Boot 中的 @ConfigurationProperties,优雅绑定配置参数

参考

上一篇:Spring Boot中使用MyBatis注解配置详解(1)


下一篇:Spring Boot 中使用 @Transactional 注解配置事务管理