一文学会Spring Boot配置属性

Spring Boot允许将配置外部化，以便在不同的环境中使用相同的程序代码。可以使用各种外部配置源，包括Java属性文件、YAML文件、环境变量、命令行参数。配置属性值可以通过@Value注解直接注入到bean中，或者通过@ConfigurationProperties注解绑定到结构化对象。

Spring Boot中的配置具有顺序性，该顺序允许程序员合理的覆盖属性值，顺序高的配置值可以覆盖顺序低的配置值，优先级从低到高如下：

1. 默认属性 - 可通过 SpringApplication.setDefaultProperties 设置
2. @Configuration 类上配置的 @PropertySource 注解 - 需要注意在刷新应用上下文context之前，不会将此类属性添加到 Environment 中。对于特殊的场景配置会导致读不到属性值，如 logging.* and spring.main.*
3. Config Data - 例如 application.properties 文件
4. 配置随机属性值
5. 操作系统环境变量
6. JVM 环境变量 - 如可以通过System.getProperties()获取的属性值
7. 从 java:comp/env 获取的 JNDI 属性值
8. ServletConext 初始化参数
9. ServletConfig 初始化参数
10. SPRING_APPLICATION_JSON 中的属性值
11. 命令行启动参数
12. 测试属性值 - 使用 @SpringBootTest 、测试注解中的属性值
13. @TestPropertySource 注解
14. devtools 启用时，Devtools 工具在 $HOME/.config/spring-boot 目录设置的全局属性

配置文件的优先级顺序如下：

• jar包内部的 application.properties 配置文件
• profile 属性指定jar包内部的配置文件 - 如application-{profile}.properties
• jar包外部的 application.properties 配置文件
• profile 属性指定jar包外部的配置文件 - 如application-{profile}.properties

建议在项目中使用相同格式的配置文件，统一为 .properties 或 .yml 格式。假设在相同的目录中同时存在两种类型的配置文件，.properties优先

@Value

@Component
public class MyBean {@Value("${name}")private String name;}

以上代码使用 @Value注解读取配置文件的name值。可以应用不同的场景：

• jar包内部 application.properties 中配置的name属性

• 运行新环境时，jar外部 application.properties 文件中name属性值可以覆盖jar包内部的属性值

• 测试时，可以通过命令行覆盖属性值

  java -jar app.jar --name="Spring"
  

获取命令行属性值

默认情况下，Spring Boot 可以转化命令中 以 --开头的参数，如 --server.port=9000，并把它们添加到Spring Environment环境中，命令行的参数始终偶先配置文件中的参数。

如果不想将命令行中的属性配置添加到 Environment中，可以通过代码禁用该行为：

SpringApplication.setAddCommandLineProperties(false)

JSON 应用属性

环境变量跟系统属性可能会存在一些属性名称上的冲突，为了解决此类问题。Spring Boot允许将属性代码快编码为单个的JSON结构。启动应用程序时，spring.application.json (SPRING_APPLICATION_JSON) 属性值将被解析并添加到 Environment环境中。

例如，SPRING_APPLICATION_JSON

// 方式一
java -jar target/springboot-study-0.0.1-SNAPSHOT.jar --spring.application.json='{\"name\":\"test\"}'// 方式二
java -jar target/springboot-study-0.0.1-SNAPSHOT.jar -Dspring.application.json='{\"name\":\"test\"}'

外部属性文件

系统启动时，Spring Boot 自动从指定的目录加载 application.properties、application.yaml 配置文件。指定目录(优先级顺序从低到高)如下：

1. 从 classpath 加载
   • classpath 根目录
   • classpath 下 /config 目录
2. 从当前目录 加载
   • 当前目录加载
   • 当前目录下的 config 子目录加载
   • config 下的子目录加载

如果不喜欢默认的配置文件名 application，可以通过 spring.config.name 在命令行中指定其他配置文件名称，如下指定 myproject.properties 或 myproject.yaml 文件：

$ java -jar myproject.jar --spring.config.name=myproject

也可以显示指定系统加载的文件，多个目录之间使用逗号进行分隔

$ java -jar myproject.jar --spring.config.location=\optional:classpath:/default.properties,\optional:classpath:/override.properties

大多数情况下，每个spring.config选项关联单个文件或者目录。多个目录之间按照定义顺序进行处理，后面的位置可以覆盖前面位置的值。spring.config.location配置的目录将会替换默认的读取路径。例如 spring.config.location 配置为 “optional:classpath:/custom-config/,optional:file:./custom-config/”，Spring Boot 读取的完整路径为：

• optional:classpath:custom-config/
• optional:file:./custom-config/

如果只是新增路径，然不是替换默认路径。可以使用 spring.config.additional-location 配置。从其他位置加载的属性配置将覆盖默认的属性配置。例如 spring.config.additional-location 配置为 optional:classpath:/custom-config/,optional:file:./custom-config/, Spring Boot 将会读取的路径为：

• optional:classpath:/;optional:classpath:/config/
• optional:file:./;optional:file:./config/;optional:file:./config/*/
• optional:classpath:custom-config/`
• optional:file:./custom-config/

Spring Boot允许你有选择性的覆盖另一个配置中的值。开发人员可以在应用程序中为应用程序提供默认值。然后在运行时指定一个特定的路径位置然后覆盖这些默认值。

Optional Locations

默认情况下，当指定的配置文件路径不存在时，Spring Boot 将会终止启动应用程序，并抛出异常 ConfigDataLocationNotFoundException。

如果你想指定路径，但并不确定该路径是否一直存在，你可以加上 optional: 前缀。spring.config.location 、spring.config.additional-location都可以使用 这个前缀，也可以使用 spring.config.import 声明。例如， spring.config.import 值为 optional:file:./myconfig.properties 允许应用程序启动，及时 myconfig.properties文件不存在。

如果想忽略ConfigDataLocationNotFoundException异常，并继续启动应用，可以使用 spring.config.on-not-found，值设置为 ingore。系统使用SpringApplication.setDefaultProperties(…) 或 system/environment 中的值

Wildcard Locations

如果配置路径中包含 * 号，则它将被视为通配符位置。加载配置文件时会将子目录也考虑进去。例如 需要配置Redis、Mysql配置文件，考虑将这两部分配置文件分开，方便管理。这将导致两个文件

• /config/redis/application.properties
• /config/mysql/application.properties

这种情况需要使用通配符进行处理，让Spring Boot识别并加载这两个目录下的文件，如 config/*/。默认情况下，Spring Boot 在默认的搜索位置搜索 config/*/ 目录，jar包外部的 /config 文件夹也会被识别加载。

通配符位置仅适用于外部目录，不能在classpath: 下 使用通配符

Profile Specific Files

Spring Boot 允许使用 application-{profile} 加载不同环境的配置文件。例如，应用程序在 prod 生产环境中启动，则配置文件命名为 application-prod.yml。跟标准的配置文件加载流程类似，特定环境下profile配置文件会覆盖默认的配置文件。

如果多个 profile 文件被指定，默认应用后面的profile文件 (last-wins strategy)，如 同时在 prod、live profile配置文件中指定spring.profiles.active属性，application-live.properties 配置文件中的值 覆盖 application-prod.properties.

last-wins strategy应用于目录组级别，即相同的目录组，后面文件的配置属性覆盖前面文件的配置属性。还是使用上面的案例，同时指定 prod、live 配置文件，如下：
/cfgapplication-live.properties
/extapplication-live.propertiesapplication-prod.properties
使用spring.config.location属性，配置值为： classpath:/cfg/,classpath:/ext/，则文件处理顺序如下：
1. /cfg/application-live.properties
2. /ext/application-prod.properties
3. /ext/application-live.properties将 classpath:/cfg/;classpath:/ext/ 使用分号进行分隔时，则/cfg,/ext目录被当成同一个目录级别，则文件处理顺序如下：
1. /ext/application-prod.properties
2. /cfg/application-live.properties
3. /ext/application-live.properties

系统使用默认的profile配置文件，默认值为 [default]，即没有显示指定profile配置文件时，则使用 application-default 配置文件。

Importing Additional Data

应用程序可以使用spring.config.import属性从其他目录导入配置文件，导入的文件被当成原配置文件的一部分进行处理，如下：

spring:application:name: "myapp"config:import: "optional:file:./dev.properties"

上述配置将导入当前目录下的dev.properties（如果文件存在）。dev.properties属性文件的值将优先处理，在dev.properties中可以重新定义 spring.application.name的值。

在properties/yaml 单个文件中导入的顺序并不重要，如下两个配置它们的结果是一样的。

spring:config:import: "my.properties"
my:property: "value"

my:property: "value"
spring:config:import: "my.properties"

在上述的两个示例中，mysql.properties中的值将优先于文件中定义的属性值。使用 spring.config.import 导入多个文件时，目录文件按顺序处理，后面导入的文件优先级高。

Importing Extensionless Files

一些云平台需要导入外部文件系统的配置文件，应对这种场景，需要告诉Spring Boot如何加载他们。

假如需要在application.properties 导入 /etc/config/myconfig文件，使用示例如下

spring:config:import: "file:/etc/config/myconfig[.yaml]"

Using Configuration Trees

etc/config/myapp/usernamepassword

假设存在如上目录配置文件，需要同时读取他们的配置属性。当然可以使用 spring.config.import 一个个的导入，但是可以使用以下更直观的方式导入：

spring:config:import: "optional:configtree:/etc/config/"

可以在Environment 环境变量中使用 myapp.username 、myapp.password 配置属性。

如果同一个父目录，存在多个子配置目录，可以使用通配符，减少代码代码量，如下：

etc/config/dbconfig/db/usernamepasswordmqconfig/mq/usernamepassword

spring:config:import: "optional:configtree:/etc/config/*/"

Property Placeholders

application.properties 、applicaiton.yml中的属性值在使用时会经过 Environment处理，因此配置可以关联之前已经定义的值（从系统属性、环境变量中关联）。${name}占位符可以使用在任何位置。属性占位符还可以指定默认值，如 ${name:default}.

app:name: "MyApp"description: "${app.name} is a Spring Boot application written by ${username:Unknown}"

username 可能其他地方没有设置，配置默认值；app.name为设置为 MyApp，因此description的最终结果为：MyApp is a Spring Boot application written by Unknown.

Working With Multi-Document Files

Spring Boot 允许将单个文件拆分程多个文件，每个文件单独添加，文档按从上到下的顺序处理，后面的文件可以覆盖前面文件中定义的属性。YAML支持多文档语法，— 字符串表示一个文档的结尾，下一个文档的开始。

以下配置代表两个逻辑文件

spring:application:name: "MyApp"
---
spring:application:name: "MyCloudApp"config:activate:on-cloud-platform: "kubernetes"

对于properties属性文件 使用 #— 、!— 字符串分隔文件

spring.application.name=MyApp
#---
spring.application.name=MyCloudApp
spring.config.activate.on-cloud-platform=kubernetes

Activation Properties

在一些场景中，当条件满足时，需要激活相关的属性配置。可以使用 spring.config.activate.*. 有条件的技术配置属性。

myprop:"always-set"
---
spring:config:activate:on-cloud-platform: "kubernetes"on-profile: "prod | staging"
myotherprop: "sometimes-set"

Working With YAML

YAML是一个分层的、格式良好的数据配置文件，跟JSON数据一样，也是Key-Value数据格式存储。Spring Boot 内部使用SnakeYAML 第三方 jar包 支持 YAML格式文件的解析。

如果使用Starter包，SnakeYAML jar包已经被包含在 spring-boot-starter.

Mapping YAML to Properties

YAML 文档根据其分层结构转换为 Key-Value键值对存储在Spring Environment 环境中，例如：

environments:dev:url: "https://dev.example.com"name: "Developer Setup"prod:url: "https://another.example.com"name: "My Cool App"

Spring Environment 内部存储的数据结构如下：

environments.dev.url=https://dev.example.com
environments.dev.name=Developer Setup
environments.prod.url=https://another.example.com
environments.prod.name=My Cool App

同时，YAML支持组数配置，使用 [index] 解析器表示数组下标，如：

my:servers:- "dev.example.com"- "another.example.com"

上述example将被转换为：

my.servers[0]=dev.example.com
my.servers[1]=another.example.com

Directly Loading YAML

Spring Framework 提供了两个类来加载YAML配置文件

• YamlPropertiesFactoryBean - 将YAML作为properties属性加载
• YamlMapFactoryBean - 将YAML作为Map加载

配置随机属性

RandomValuePropertySource 类用于注入随机配置属性(例如，配置秘钥、测试用例)。可以生成Integer、Long、uuids、strings，配置如下：

my:secret: "${random.value}"number: "${random.int}"bignumber: "${random.long}"uuid: "${random.uuid}"number-less-than-ten: "${random.int(10)}"number-in-range: "${random.int[1024,65536]}"

Type-safe Configuration Properties

使用@Value(“${property}”)注解注入属性文件时，有些时候可能存在问题。尤其是使用多个属性、或者数据分层时，Spring Boot 提供了另一种处理属性的方法，它允许强类型bean管理、验证应用程序的配置。

JavaBean 属性绑定

绑定Bean中定义的属性值(Get、Set方法)，使用如下:

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

Bean 与 配置文件之间的对应关系为：

• my.service.enabled 对应 enabled属性，默认值为 false
• my.service.remote-address 对应remoteAddress属性，配置为字符串
• my.service.security.username 对应内部类Security中的name属性
• my.service.security.password 对应内部类Security中的password属性
• my.service.security.roles 对应内部类roles属性，配置为String 数组

构造函数绑定

Spring Boot 支持以构造函数方式注入配置属性值，代码如下：

import java.net.InetAddress;
import java.util.List;import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.ConstructorBinding;
import org.springframework.boot.context.properties.bind.DefaultValue;@ConstructorBinding
@ConfigurationProperties("my.service")
public class MyProperties {private final boolean enabled;private final InetAddress remoteAddress;private final Security security;public MyProperties(boolean enabled, InetAddress remoteAddress, Security security) {this.enabled = enabled;this.remoteAddress = remoteAddress;this.security = security;}public boolean isEnabled() {return this.enabled;}public InetAddress getRemoteAddress() {return this.remoteAddress;}public Security getSecurity() {return this.security;}public static class Security {private final String username;private final String password;private final List roles;public Security(String username, String password, @DefaultValue("USER") List roles) {this.username = username;this.password = password;this.roles = roles;}public String getUsername() {return this.username;}public String getPassword() {return this.password;}public List getRoles() {return this.roles;}}
}

@ConstructorBinding注解用于指定使用构造函数绑定配置属性值，内部类的构造函数也可以使用该注解绑定属性值。

通过构造函数绑定属性值时，可以使用@DefaultValue注解设置属性默认值。

引用之前的带啊，如果文件中没有配置 Security值，MyProperties 实例中 security字段设置为null。为了避免null值，可以通过 @DefaultValue 指定默认值，如下：

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

使用构造函数绑定，Spring Boot应用程序必须开启 @EnableConfigurationProperties 属性、或者配置属性扫描。不能使用构造函数绑定来创建 @Component 声明的bean

Enabling @ConfigurationProperties-annotated Types

Spring Boot 提供 @ConfigurationProperties 声明一个class文件，并将它注册为bean。可以单个启动配置属性，也可以通过扫描启动多个配置属性。

使用@ConfigurationProperties注释的类可能不适合扫描，例如开发自定义的配置，并希望有条件的启用他们。此类情况请使用@EnableConfigurationProperties注解要处理的class类型。需要跟 @configuration配合使用。

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(SomeProperties.class)
public class MyConfiguration {}

进行配置文件扫描时，需要在应用程序增加 @ConfigurationPropertiesScan 注解，一般加在启动类上。默认情况下，从注解中声明的package进行扫描，如果需要指定特殊的package，代码如下：

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;@SpringBootApplication
@ConfigurationPropertiesScan({ "com.example.app", "com.example.another" })
public class MyApplication {}

Relaxed Binding

Spring Boot 使用宽松的规则来匹配配置文件中对的key值，跟class内定义的字段值。

import org.springframework.boot.context.properties.ConfigurationProperties;@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;}}