https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-Config-Data-Migration-Guide

This document is meant to help you migrate your application.properties and application.yml files for use with Spring Boot 2.4 and above.

Overview

Spring Boot 2.4 has provided an overhaul of the way that application.properties and application.yml files are processed. The updated logic has been designed to simplify and rationalize the way that external configuration is loaded. It has also allowed us to provide new features, such as spring.config.import support.

The updated design intentionally restricts certain property combinations. This means that you may need to change a few things when upgrading from Spring Boot 2.3 or earlier.

Legacy Mode

If you’re not yet ready to migrate your application to use the new config data processing logic, you’ll need to switch back to the legacy mode. To do this, you should set the spring.config.use-legacy-processing property to true.

The property needs to be set in the Spring Environment. The easiest way is usually to to add it to the application.properties or application.yml inside your jar.

For example, you can have a src/main/resources/application.properties as follows:

spring.config.use-legacy-processing=true

# any other properties

Simple Scenarios

For many applications, you won’t need to make any changes to your existing properties files. Specifically, if you only have a single application.properties or application.yml file, you don’t use spring.profiles<.*> properties and you don’t make use of multi-document YAML, then upgrading should just work.

If you do have a more advanced set-up, then you should follow the advice in the rest of this document.

Multi-document YAML Ordering

If you use multi-document YAML files (files with --- separators) then you need to be aware that property sources are now added in the order that documents are declared. With Spring Boot 2.3 and earlier, the order that the individual documents were added was based on profile activation order.

If you have properties that override each other, you need to make sure that the property you want to "win" is lower in the file. This means that you may need to reorder the documents inside your YAML.

Profile Specific External Configuration

If you use configuration outside of your jar, and you make use of profile-specific configuration files, you should check that your properties are loaded as expected. In earlier versions of Spring Boot, an application.properties file outside of your jar would not override a application-.properties file inside your jar.

As of Spring Boot 2.4, external file always override packaged files (profile-specific or not). You can read more about the rationale for this change in Issue 3845 on GitHub. You can also check the update documentation which describes the new ordering.

Profile Specific Documents

If you use the spring.profiles property, for example in multi-document YAML files, you should migrate to spring.config.activate.on-profile. As with the previous property, you can specify a list of profiles that need to be active for the properties to apply. You can also use profile expressions such as (prod & cloud)

For example, if you have the following application.yaml:

spring:
  profiles: "prod"
secret: "production-password"

It would be migrated as follows:

spring:
  config:
    activate:
      on-profile: "prod"
secret: "production-password"

Profile Activation

The spring.profiles.active property should still be used to active specific profiles. For example, from the command line you can run:

$ java -jar myapp.jar --spring.profiles.active=prod

You can also set it in your application.properties or application.yaml, but as of Spring Boot 2.4 you cannot set the property in a profile-specific document. In other words, you can no longer combine it with a document that has a spring.config.activate.on-profile property.

Likewise, you can still use the spring.profiles.include property, but only in non profile-specific documents.

For example, the second document following configuration is invalid:

# this document is valid
spring:
  profiles:
    active: "prod"

---

# this document is invalid
spring:
  config:
    activate:
      on-profile: "prod"
  profiles:
    include: "metrics"

| Note |
The reason we have introduced this restriction is so that on-profile conditions are only evaluated once. Without this limitation, it would be possible for a spring.config.activate.on-profile expression to return a different result depending on when it was evaluated. |

Profile Groups

With Spring Boot 2.3 and earlier, users would often combine spring.profiles with spring.profiles.include to expand active profiles.

For example, they might have the following application.yaml file:

spring.profiles: "debug"
spring.profiles.include: "debugdb,debugcloud"

This allowed them to run java -jar --spring.profiles.active=debug and automatically have the debug, debugdb and debugcloud profiles activated.

If we migrate this example to a Spring Boot 2.4 application.yaml we get:

spring:
  config:
    activate:
      on-profile: "debug"
  profiles:
    include: "debugdb,debugcloud"

As discussed above, it’s no longer possible to use spring.profiles.include in a profile-specific document so this file isn’t valid.

Since this use-case is quite common, we’ve tried to provide another way to support it. In Spring Boot 2.4 you can use the “profile groups” feature.

Profile groups allow you to say:

if you see profile 'x', also activate profiles 'y' & 'z'

Profile groups are defined with the spring.profiles.group. property. For example, the configuration above would be written as follows:

spring:
  profiles:
    group:
      "debug": "debugdb,debugcloud"

| Note |
The spring.profile.group property cannot be used in profile-specific documents. You can’t use it in a document that also has a spring.config.activate.on-profile property. |

Migration Example

Let’s walk through an example migration for a Spring Boot 2.3 application. Say that we have an application ships with an application.yaml inside the jar that looks like this:

spring.application.name: "customers"
---
spring.profiles: "production"
spring.profiles.include: "mysql,rabbitmq"
---
spring:
  profiles: "mysql"
  datasource:
    url: "jdbc:mysql://localhost/test"
    username: "dbuser"
    password: "dbpass"
---
spring:
  profiles: "rabbitmq"
  rabbitmq:
    host: "localhost"
    port: 5672
    username: "admin"
    password: "secret"

In addition, a application-prod.yaml file is included next to the jar when the app is deployed:

spring:
  datasource:
    username: "proddbuser"
    password: "proddbpass"
  rabbitmq:
    username: "prodadmin"
    password: "prodsecret"

To migrate the application, we can start by updating the application.yaml packaged in the jar to use the new property names:

spring.application.name: "customers"
---
spring:
  config:
    activate:
      on-profile: "production"
  profiles:
    include: "mysql,rabbitmq"
---
spring:
  config:
    activate:
      on-profile: "mysql"
  datasource:
    url: "jdbc:mysql://localhost/test"
    username: "dbuser"
    password: "dbpass"
---
spring:
config:
  activate:
    on-profile: "rabbitmq"
  rabbitmq:
    host: "localhost"
    port: 5672
    username: "admin"
    password: "secret"

This almost works, except that we’ve tried to use spring.profiles.include in a profile-specific document. We can migrate that property by using profile groups:

spring:
  application:
    name: "customers"
  profiles:
    group:
      "production": "mysql,rabbitmq"
---
spring:
  config:
    activate:
      on-profile: "mysql"
  datasource:
    url: "jdbc:mysql://localhost/test"
    username: "dbuser"
    password: "dbpass"
---
spring:
  config:
    activate:
      on-profile: "rabbitmq"
  rabbitmq:
    host: "localhost"
    port: 5672
    username: "admin"
    password: "secret"

At this point our migration is complete and things should behave as before. The production instance can set the profile in the usual way (for example with a SPRING_PROFILES_ACTIVE=prod system environment variable) and the previous application-prod.yaml file will be picked up.

If we want to, we can rename application-prod.yaml to application.yaml since with Spring Boot 2.4 all external files override internal ones.

中文翻译

本文档旨在帮助您迁移“application.properties”和“application.yml”文件，以便与Spring Boot 2.4及更高版本一起使用。

概述

SpringBoot2.4彻底改变了application.properties 和application.yml 文件的处理方式。更新的逻辑旨在简化和合理化外部配置的加载方式。它还允许我们提供新功能，例如spring.config.import 支持。
更新的设计有意限制某些属性组合。这意味着从SpringBoot2.3或更早版本升级时，您可能需要更改一些内容。

传统模式

如果您还没有准备好迁移应用程序以使用新的配置数据处理逻辑，则需要切换回旧模式。为此，应将spring.config.use-legacy-processing 属性设置为true 。
需要在Spring环境中设置该属性。最简单的方法通常是将其添加到jar中的application.properties 或application.yml 中。
例如，您可以有一个src/main/resources/application.properties ，如下所示：

spring.config.use-legacy-processing=true

# any other properties

简单场景 Simple Scenarios

对于许多应用程序，您不需要对现有属性文件进行任何更改。具体来说，如果您只有一个application.properties或application.yml文件，那么您不使用spring.profiles<.*>属性，也不使用多文档YAML，那么升级应该可以正常工作。
如果您有更高级的设置，则应遵循本文档其余部分中的建议。

多文档YAML排序 Multi-document YAML Ordering

如果您使用多文档YAML文件（带有---分隔符的文件），那么您需要注意，现在按照文档声明的顺序添加属性源。对于SpringBoot2.3和更早版本，单个文档的添加顺序基于概要文件激活顺序。如果属性相互覆盖，则需要确保要“win”的属性在文件中的位置较低。这意味着您可能需要对YAML中的文档重新排序。

配置文件特定外部配置 Profile Specific External Configuration

如果您使用在你jar之外的配置，并且使用特定于profile-specific概要文件的配置文件，那么应该检查您的属性是否按预期加载。在SpringBoot的早期版本中，jar外部的application.properties文件不会覆盖jar内部的application-.properties文件。
从SpringBoot2.4开始，外部文件总是覆盖打包文件 (profile-specific or not)。您可以在GitHub上的3845期中阅读更多有关此更改的基本原理的信息。您还可以查看更新文档。

配置文件特定文档 Profile Specific Documents

例如，如果在多文档YAML文件中使用spring.profiles属性，则应迁移到spring.config.activate.on profile。与上一个属性一样，您可以指定需要激活才能应用属性的配置文件列表。您还可以使用配置文件表达式，例如（prod&cloud）
例如，如果您有以下application.yaml：

spring:
  profiles: "prod"
secret: "production-password"

它可以迁移成下面这样:

spring:
  config:
    activate:
      on-profile: "prod"
secret: "production-password"

激活配置文件

spring.profiles.active属性仍应用于激活特定配置文件。例如，可以从命令行运行

$ java -jar myapp.jar --spring.profiles.active=prod

您也可以在application.properties或application.yaml中设置该属性，但从Spring Boot 2.4开始，您不能在特定于概要文件的文档中设置该属性。换句话说，您不能再将其与具有spring.config.activate.on-profile属性的文档组合。同样，您仍然可以使用spring.profiles.include属性，但只能在非配置文件特定（profile-specific）的文档中使用。
例如，以下配置的第二个文档无效：

# this document is valid
spring:
  profiles:
    active: "prod"

---

# this document is invalid
spring:
  config:
    activate:
      on-profile: "prod"
  profiles:
    include: "metrics"

|注|
我们引入此限制的原因是，on profile条件只计算一次。如果没有此限制，spring.config.activate.on profile表达式可能会根据计算时间返回不同的结果|

配置文件组

在SpringBoot2.3及更早版本中，用户通常会将spring.profiles与spring.profiles.include组合起来，以扩展活动配置文件。
例如，它们可能有以下application.yaml文件：

spring.profiles: "debug"
spring.profiles.include: "debugdb,debugcloud"

这允许他们运行java-jar--spring.profiles.active=debug，并自动激活debug，debugdb和debugcloud配置文件。
如果我们将此示例迁移到Spring Boot 2.4application.yaml中，我们会得到：

spring:
  config:
    activate:
      on-profile: "debug"
  profiles:
    include: "debugdb,debugcloud"

如上所述，在特定于概要文件的文档中不再可能使用spring.profiles.include，因此此文件无效。
由于这个用例非常常见，我们试图提供另一种方法来支持它。在SpringBoot2.4中，您可以使用“profile groups”功能。
配置文件组允许您说：

如果您看到配置文件“x”，请同时激活配置文件“y”和“z”

配置文件组是用spring.profiles.group.属性定义的。例如，上面的配置将编写如下：

spring:
  profiles:
    group:
      "debug": "debugdb,debugcloud"

|注|无法在配置文件特定的profile-specific文档中使用spring.profile.group属性。您不能在同时具有spring.config.activate.on profile属性的文档中使用它

迁移示例

让我们看一下 Spring Boot 2.3 应用程序的迁移示例。假设我们有一个应用程序在 jar 中带有一个application.yaml，如下所示：

spring.application.name: "customers"
---
spring.profiles: "production"
spring.profiles.include: "mysql,rabbitmq"
---
spring:
  profiles: "mysql"
  datasource:
    url: "jdbc:mysql://localhost/test"
    username: "dbuser"
    password: "dbpass"
---
spring:
  profiles: "rabbitmq"
  rabbitmq:
    host: "localhost"
    port: 5672
    username: "admin"
    password: "secret"

In addition, a application-prod.yaml file is included next to the jar when the app is deployed:
此外，部署应用程序时，jar 旁边会包含一个application-prod.yaml文件：

spring:
  datasource:
    username: "proddbuser"
    password: "proddbpass"
  rabbitmq:
    username: "prodadmin"
    password: "prodsecret"

To migrate the application, we can start by updating the application.yaml packaged in the jar to use the new property names:
要迁移应用程序，我们可以首先更新打包在 jar 中的lapplication.yaml 以使用新的属性名称：

spring.application.name: "customers"
---
spring:
  config:
    activate:
      on-profile: "production"
  profiles:
    include: "mysql,rabbitmq"
---
spring:
  config:
    activate:
      on-profile: "mysql"
  datasource:
    url: "jdbc:mysql://localhost/test"
    username: "dbuser"
    password: "dbpass"
---
spring:
config:
  activate:
    on-profile: "rabbitmq"
  rabbitmq:
    host: "localhost"
    port: 5672
    username: "admin"
    password: "secret"

This almost works, except that we’ve tried to use spring.profiles.include in a profile-specific document. We can migrate that property by using profile groups:
这几乎有效，除了我们尝试在特定于配置文件的文档中使用 spring.profiles.include。我们可以使用配置文件组迁移该属性：

spring:
  application:
    name: "customers"
  profiles:
    group:
      "production": "mysql,rabbitmq"
---
spring:
  config:
    activate:
      on-profile: "mysql"
  datasource:
    url: "jdbc:mysql://localhost/test"
    username: "dbuser"
    password: "dbpass"
---
spring:
  config:
    activate:
      on-profile: "rabbitmq"
  rabbitmq:
    host: "localhost"
    port: 5672
    username: "admin"
    password: "secret"

在这一点上，我们的迁移已经完成，事情应该像以前一样。生产实例可以以通常的方式设置配置文件（例如使用 SPRING_PROFILES_ACTIVE=prod 系统环境变量），并且之前的 application-prod.yaml 文件将被选中。