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 thaton-profile
conditions are only evaluated once. Without this limitation, it would be possible for aspring.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 |
Thespring.profile.group
property cannot be used in profile-specific documents. You can’t use it in a document that also has aspring.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)部文件良狈。