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-<profile>.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.<source> 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 文件的處理方式。更新的邏輯旨在簡(jiǎn)化和合理化外部配置的加載方式。它還允許我們提供新功能，例如spring.config.import 支持。
更新的設(shè)計(jì)有意限制某些屬性組合。這意味著從SpringBoot2.3或更早版本升級(jí)時(shí)，您可能需要更改一些內(nèi)容。

傳統(tǒng)模式

如果您還沒有準(zhǔn)備好遷移應(yīng)用程序以使用新的配置數(shù)據(jù)處理邏輯，則需要切換回舊模式。為此，應(yīng)將spring.config.use-legacy-processing 屬性設(shè)置為true 。
需要在Spring環(huán)境中設(shè)置該屬性。最簡(jiǎn)單的方法通常是將其添加到j(luò)ar中的application.properties 或application.yml 中。
例如，您可以有一個(gè)src/main/resources/application.properties ，如下所示：

spring.config.use-legacy-processing=true

# any other properties

簡(jiǎn)單場(chǎng)景 Simple Scenarios

對(duì)于許多應(yīng)用程序，您不需要對(duì)現(xiàn)有屬性文件進(jìn)行任何更改。具體來說，如果您只有一個(gè)application.properties或application.yml文件，那么您不使用spring.profiles<.*>屬性，也不使用多文檔YAML，那么升級(jí)應(yīng)該可以正常工作。
如果您有更高級(jí)的設(shè)置，則應(yīng)遵循本文檔其余部分中的建議。

多文檔YAML排序 Multi-document YAML Ordering

如果您使用多文檔YAML文件（帶有---分隔符的文件），那么您需要注意，現(xiàn)在按照文檔聲明的順序添加屬性源。對(duì)于SpringBoot2.3和更早版本，單個(gè)文檔的添加順序基于概要文件激活順序。如果屬性相互覆蓋，則需要確保要“win”的屬性在文件中的位置較低。這意味著您可能需要對(duì)YAML中的文檔重新排序。

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

如果您使用在你jar之外的配置，并且使用特定于profile-specific概要文件的配置文件，那么應(yīng)該檢查您的屬性是否按預(yù)期加載。在SpringBoot的早期版本中，jar外部的application.properties文件不會(huì)覆蓋jar內(nèi)部的application-<profile>.properties文件。
從SpringBoot2.4開始，外部文件總是覆蓋打包文件 (profile-specific or not)。您可以在GitHub上的3845期中閱讀更多有關(guān)此更改的基本原理的信息。您還可以查看更新文檔。

配置文件特定文檔 Profile Specific Documents

例如，如果在多文檔YAML文件中使用spring.profiles屬性，則應(yīng)遷移到spring.config.activate.on profile。與上一個(gè)屬性一樣，您可以指定需要激活才能應(yīng)用屬性的配置文件列表。您還可以使用配置文件表達(dá)式，例如（prod&cloud）
例如，如果您有以下application.yaml：

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

它可以遷移成下面這樣:

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

激活配置文件

spring.profiles.active屬性仍應(yīng)用于激活特定配置文件。例如，可以從命令行運(yùn)行

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

您也可以在application.properties或application.yaml中設(shè)置該屬性，但從Spring Boot 2.4開始，您不能在特定于概要文件的文檔中設(shè)置該屬性。換句話說，您不能再將其與具有spring.config.activate.on-profile屬性的文檔組合。同樣，您仍然可以使用spring.profiles.include屬性，但只能在非配置文件特定（profile-specific）的文檔中使用。
例如，以下配置的第二個(gè)文檔無效：

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

---

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

|注|
我們引入此限制的原因是，on profile條件只計(jì)算一次。如果沒有此限制，spring.config.activate.on profile表達(dá)式可能會(huì)根據(jù)計(jì)算時(shí)間返回不同的結(jié)果|

配置文件組

在SpringBoot2.3及更早版本中，用戶通常會(huì)將spring.profiles與spring.profiles.include組合起來，以擴(kuò)展活動(dòng)配置文件。
例如，它們可能有以下application.yaml文件：

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

這允許他們運(yùn)行java-jar--spring.profiles.active=debug，并自動(dòng)激活debug，debugdb和debugcloud配置文件。
如果我們將此示例遷移到Spring Boot 2.4application.yaml中，我們會(huì)得到：

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

如上所述，在特定于概要文件的文檔中不再可能使用spring.profiles.include，因此此文件無效。
由于這個(gè)用例非常常見，我們?cè)噲D提供另一種方法來支持它。在SpringBoot2.4中，您可以使用“profile groups”功能。
配置文件組允許您說：

如果您看到配置文件“x”，請(qǐng)同時(shí)激活配置文件“y”和“z”

配置文件組是用spring.profiles.group.<source>屬性定義的。例如，上面的配置將編寫如下：

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

|注|無法在配置文件特定的profile-specific文檔中使用spring.profile.group屬性。您不能在同時(shí)具有spring.config.activate.on profile屬性的文檔中使用它

遷移示例

讓我們看一下 Spring Boot 2.3 應(yīng)用程序的遷移示例。假設(shè)我們有一個(gè)應(yīng)用程序在 jar 中帶有一個(gè)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:
此外，部署應(yīng)用程序時(shí)，jar 旁邊會(huì)包含一個(gè)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:
要遷移應(yīng)用程序，我們可以首先更新打包在 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"

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.

在這一點(diǎn)上，我們的遷移已經(jīng)完成，事情應(yīng)該像以前一樣。生產(chǎn)實(shí)例可以以通常的方式設(shè)置配置文件（例如使用 SPRING_PROFILES_ACTIVE=prod 系統(tǒng)環(huán)境變量），并且之前的 application-prod.yaml 文件將被選中。

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.

如果我們?cè)敢?，我們可以?application-prod.yaml 重命名為 application.yaml，因?yàn)?Spring Boot 2.4 所有外部文件都會(huì)覆蓋內(nèi)部文件。