Spring Framework 提供两个可用于加载 YAML 文档的便利类。YamlPropertiesFactoryBean 加载 YAML 作为 Properties，YamlMapFactoryBean 加载 YAML 作为 Map。

例如，参考下面的 YAML 文档：

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

前面的示例将被转换成以下属性：

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

YAML 列表表示为 [index] 间接引用的属性键。例如，参考下面的 YAML：

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

前面的示例将被转换成以下属性：

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

要像 Spring Boot 的 Binder utilities 那样绑定属性（这是 @ConfigurationProperties 所做的），你需要在目标 bean 中有一个 java.util.List (或 Set) 类型的属性，并需要提供一个 setter 或用一个可变的值初始化它。例如，下面的示例绑定前面所示的属性：

@ConfigurationProperties(prefix="my")
public class Config {

	private List<String> servers = new ArrayList<String>();

	public List<String> getServers() {
		return this.servers;
	}
}

YamlPropertySourceLoader 类可用于将 YAML 作为 Spring Environment 的 PropertySource。这样做可以让你使用带有占位符语法的 @Value 注解来访问 YAML 属性。

你可以使用 spring.profiles 键在单个文件中指定多个配置组的 YAML 文件，以指示文档何时应用，如下面的示例所示：

server:
	address: 192.168.1.100
---
spring:
	profiles: development
server:
	address: 127.0.0.1
---
spring:
	profiles: production & eu-central
server:
	address: 192.168.1.120

在前面的示例中，如果 development 配置组是激活的，则 server.address 属性是 127.0.0.1。类似的，如果 production 和 eu-central 配置组是激活的，server.address 属性是 192.168.1.120。development 和 production 和 eu-central 配置组是未启用的，则属性值是 192.168.1.100。

	Note
	spring.profiles 可以包含一个简单的配置组名称（例如 production）或配置组表达式。一个配置组表达式允许更复杂的配置逻辑来表达，例如 production & (eu-central | eu-west)。更多详细信息请参阅参考指南

如果在应用程序上下文启动时没有显式激活，则激活默认配置组，因此，在下面的 YAML 中，我们为 spring.security.user.password 设置了一个值，并仅在 "default" 中可用：

server:
  port: 8000
---
spring:
  profiles: default
  security:
    user:
      password: weak

然而，在下面的示例中，密码总是被设置，因为它不附加到任何配置文件中，并且在必要时，必须在所有其它配置文件中显式重置：

server:
  port: 8000
spring:
  security:
    user:
      password: weak

使用 spring.profiles 元素指定的 Spring 配置组可以通过使用 ! 字符随时取消。如果单个文档指定了否定和非否定的配置组，则至少匹配一个非否定的配置组，并且可以匹配非否定的配置组。

YAML 文件不能使用 @PropertySource 注解加载。因此，在需要以这种方式加载值的情况下，你需要使用属性文件。

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

若要从 Environment 属性配置 bean，请在其 bean 的注册中添加 @ConfigurationProperties，如下面的示例所示：

@ConfigurationProperties(prefix = "another")
@Bean
public AnotherComponent anotherComponent() {
	...
}

所有有 another 前缀的属性定义，以类似于前面的 AcmeProperties 示例的方式映射到 AnotherComponent bean。

Spring Boot 使用一些松散的规则来将 Environment 属性绑定到 @ConfigurationProperties bean，因此不需要在 Environment 属性名称和 bean 属性名称之间进行精确匹配。有用的常见示例包括破折号分离的环境属性（例如，context-path 绑定到 contextPath）和大写化的环境属性（例如，PORT 绑定到 port）。

例如，考虑下面的 @ConfigurationProperties 类：

@ConfigurationProperties(prefix="acme.my-project.person")
public class OwnerProperties {

	private String firstName;

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

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

}

在前面的示例中，可以使用以下属性名称：

	Note
	注解的前缀值必须是串格式（小写并使用 - 分隔，例如 acme.my-project.person）。

	Tip
	我们建议，在可能的情况下，属性以小写的串格式存储，例如 my.property-name=acme。

当绑定到 Map 属性时，如果 key 包含除小写字母数字字符或 - 以外的任何字符，则需要使用括号表示法，以便保留原始值。如果 key 未被 [] 包围，则任何非字母数字或 - 的字符都被删除。例如，考虑将下列属性绑定到 Map：

acme:
  map:
    "[/key1]": value1
    "[/key2]": value2
    /key3: value3

上面的属性使用 /key1、/key2 和 key3 为 map 中的键来绑定到 Map。

当列表在多个位置配置时，通过替换整个列表来重写。

例如，假设 MyPojo 对象的 name 和 description 属性默认为 null。下面的示例展示了来自 AcmeProperties 的 MyPojo 对象的列表：

@ConfigurationProperties("acme")
public class AcmeProperties {

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

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

}

考虑以下配置：

acme:
  list:
    - name: my name
      description: my description
---
spring:
  profiles: dev
acme:
  list:
    - name: my another name

如果 dev 配置组不是激活的，AcmeProperties.list 包含一个 MyPojo 记录，如上面定义的。如果 dev 配置组是启用的，列表仍然只包含一个记录（name为 my another name，description 为 null）。此配置不会添加第二个 MyPojo 实例到列表中，它并不会合并项。

当在多个配置文件中指定一个列表时，使用具有最高优先级的列表（并且只有一个）。考虑下面的例子：

acme:
  list:
    - name: my name
      description: my description
    - name: another name
      description: another description
---
spring:
  profiles: dev
acme:
  list:
    - name: my another name

在前面的示例中，如果 dev 配置组是激活的，AcmeProperties.list 包含一个 MyPojo 记录（name为 my another name，description 为 null）。对于YAML，逗号分隔列表和 YAML 列表都可以用于完全覆盖列表的内容。

对于 Map 属性，可以绑定从多个源绘制的属性值。然而，对于多个源中的相同属性，使用具有最高优先级的属性。下面的示例展示了一个从 AcmeProperties 得到 Map<String, MyPojo>：

@ConfigurationProperties("acme")
public class AcmeProperties {

	private final Map<String, MyPojo> map = new HashMap<>();

	public Map<String, MyPojo> getMap() {
		return this.map;
	}

}

考虑下面的配置：

acme:
  map:
    key1:
      name: my name 1
      description: my description 1
---
spring:
  profiles: dev
acme:
  map:
    key1:
      name: dev name 1
    key2:
      name: dev name 2
      description: dev description 2

如果 dev 配置组不是激活的，AcmeProperties.map 包含一个 key1 关键字的记录（name 是 my name 1， description 是 my description 1）。如果 dev 配置组是启用的，那么，map 包含 key1 关键字（name 是 dev name 1， description 是 my description 1）和 key2 关键字（name 是 dev name 2， description 是 dev description 2）的两个记录

	Note
	前面的合并规则适用于所有属性源的属性，而不只是 YAML 文件。

Spring Boot 在绑定到 @ConfigurationProperties bean 时试图将外部应用程序属性强制转换为恰当的类型。如果你需要自定义类型转换，可以提供一个 ConversionService bean（一个命名为 conversionService 的 bean）或自定义属性编辑器（通过一个 CustomEditorConfigurer bean）或自定义 Converters（定义为 @ConfigurationPropertiesBinding 的 bean）。

	Note
	由于这个 bean 在应用程序生命周期中被请求得很早，请务必限制 ConversionService 使用的依赖关系。通常，你需要的一些依赖项在创建时可能未完全初始化。如果不需要配置键强制，则只需要重命名自定义 ConversionService，并且只依赖于符合 @ConfigurationPropertiesBinding 的自定义转换器。

转换持续时间

Spring Boot 有表示持续时间的专门支持。如果暴露 java.time.Duration 属性，应用程序属性中的以下格式可用：

• 规则的 long 表示（除非指定了 @DurationUnit，否则使用毫秒作为默认单位）
• java.util.Duration 使用的标准 ISO-8601 格式。
• 一个更可读的格式，其中的值和单位被耦合（例如，10s 意味着 10秒）。

参考以下的示例：

@ConfigurationProperties("app.system")
public class AppSystemProperties {

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

	private Duration readTimeout = Duration.ofMillis(1000);

	public Duration getSessionTimeout() {
		return this.sessionTimeout;
	}

	public void setSessionTimeout(Duration sessionTimeout) {
		this.sessionTimeout = sessionTimeout;
	}

	public Duration getReadTimeout() {
		return this.readTimeout;
	}

	public void setReadTimeout(Duration readTimeout) {
		this.readTimeout = readTimeout;
	}

}

为了指定会话超时为 30秒，30、PT30S 和 30s 都是等效的。一个读取时间为500ms，可以指定在以下任何形式：500、PT0.5S 和 500ms。

你也可以使用任何支持的单位。它们是：

• ns 当作 nanoseconds（纳秒）
• us 当作 microseconds（微秒）
• ms 当作 milliseconds（毫秒）
• s 当作 seconds（秒）
• m 当作 minutes（分钟）
• h 当作 hours（小时）
• d 当作 days（天）

默认的单位是毫秒，可以用上面的示例中所示的 @DurationUnit 来重写。

	Tip
	如果你是从只使用 Long 来表示持续时间的版本升级，那么如果在转换到 Duration 的时候不确定是毫秒，请确保定义单位（使用 @DurationUnit）。这样做提供了透明的升级路径，同时支持更丰富的格式。

Spring Framework 具有一个 DataSize 值类型，以用来表示字节的大小 。如果暴露 DataSize 属性，应用程序属性中的以下格式可用：

参考下面的例子：

@ConfigurationProperties("app.io")
public class AppIoProperties {

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

	private DataSize sizeThreshold = DataSize.ofBytes(512);

	public DataSize getBufferSize() {
		return this.bufferSize;
	}

	public void setBufferSize(DataSize bufferSize) {
		this.bufferSize = bufferSize;
	}

	public DataSize getSizeThreshold() {
		return this.sizeThreshold;
	}

	public void setSizeThreshold(DataSize sizeThreshold) {
		this.sizeThreshold = sizeThreshold;
	}

}

若要指定10兆字节的缓冲区大小，10 和 10MB 是等效的。256字节的大小阈值可以指定为 256 或 256B。

你也可以使用任何支持的单位。它们是：

默认的单位是字节，可以用上面的示例中所示的 @DataSizeUnit 来重写。

	Tip
	如果你是从只使用 Long 来表示大小的版本升级，那么如果在转换到 DataSize 的时候不确定是字节，请确保定义单位（使用 @DataSizeUnit）。这样做提供了透明的升级路径，同时支持更丰富的格式。

Spring Boot 会尝试校验使用 Spring 的 @Validated 注解来注解的 @ConfigurationProperties 类。你可以直接在配置类上使用 JSR-303 javax.validation 约束注解。为此，请确保兼容的 JSR-303 实现在类路径上，然后将约束注解添加到字段中，如下面的示例所示：

@ConfigurationProperties(prefix="acme")
@Validated
public class AcmeProperties {

	@NotNull
	private InetAddress remoteAddress;

	// ... getters and setters

}

	Tip
	你还可以通过注解 @Bean 方法来触发校验，该方法使用 @Validated 创建配置属性。

虽然嵌套属性在绑定时也会被校验，但是将相关字段注解为 @Valid 也是很好的做法。这确保即使没有嵌套属性也会触发校验。下面的示例基于前面的 AcmeProperties 实例构建：

@ConfigurationProperties(prefix="acme")
@Validated
public class AcmeProperties {

	@NotNull
	private InetAddress remoteAddress;

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

	// ... getters and setters

	public static class Security {

		@NotEmpty
		public String username;

		// ... getters and setters

	}

}

你还可以通过创建一个名为 configurationPropertiesValidator 的 bean 定义来添加自定义 Spring Validator。@Bean 方法应该声明为 static。配置属性校验器在应用程序的生命周期中很早被创建，并将 @Bean 方法声明为静态，可以在不必实例化 @Configuration 的情况下创建 bean。这样做避免了早期实例化可能引起的任何问题。这有一个属性校验示例演示如何设置。

	Tip
	spring-boot-actuator 模块包含一个暴露所有 @ConfigurationProperties bean 的端点。将 Web 浏览器指向 /actuator/configprops 或使用等效的 JMX 端点。详情见 "s生产就绪特性" 部分。

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

如果你为自己的组件定义了一组配置键，建议将它们在带有 @ConfigurationProperties 注解的 POJO 中分组。你还应该意识到，因为 @Value 不支持松散绑定，所以如果需要使用环境变量提供值，它则不是一个好的候选。

最后，虽然可以在 @Value 中写入 SpEL 表达式，但这些表达式不会从应用程序属性文件中处理。