Spring Boot2.4 Config Data Migration Guide

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.propertiesapplication.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.propertiesapplication.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.propertiesapplication.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.propertiesapplication.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.profilesspring.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)激活debugdebugdbdebugcloud配置文件产场。
如果我們將此示例遷移到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)部文件良狈。

最后編輯于
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
  • 序言:七十年代末后添,一起剝皮案震驚了整個(gè)濱河市,隨后出現(xiàn)的幾起案子薪丁,更是在濱河造成了極大的恐慌遇西,老刑警劉巖,帶你破解...
    沈念sama閱讀 218,941評(píng)論 6 508
  • 序言:濱河連續(xù)發(fā)生了三起死亡事件严嗜,死亡現(xiàn)場(chǎng)離奇詭異粱檀,居然都是意外死亡,警方通過查閱死者的電腦和手機(jī)漫玄,發(fā)現(xiàn)死者居然都...
    沈念sama閱讀 93,397評(píng)論 3 395
  • 文/潘曉璐 我一進(jìn)店門茄蚯,熙熙樓的掌柜王于貴愁眉苦臉地迎上來,“玉大人睦优,你說我怎么就攤上這事渗常。” “怎么了汗盘?”我有些...
    開封第一講書人閱讀 165,345評(píng)論 0 356
  • 文/不壞的土叔 我叫張陵皱碘,是天一觀的道長(zhǎng)。 經(jīng)常有香客問我隐孽,道長(zhǎng)癌椿,這世上最難降的妖魔是什么? 我笑而不...
    開封第一講書人閱讀 58,851評(píng)論 1 295
  • 正文 為了忘掉前任菱阵,我火速辦了婚禮踢俄,結(jié)果婚禮上,老公的妹妹穿的比我還像新娘晴及。我一直安慰自己都办,他們只是感情好,可當(dāng)我...
    茶點(diǎn)故事閱讀 67,868評(píng)論 6 392
  • 文/花漫 我一把揭開白布抗俄。 她就那樣靜靜地躺著脆丁,像睡著了一般。 火紅的嫁衣襯著肌膚如雪动雹。 梳的紋絲不亂的頭發(fā)上槽卫,一...
    開封第一講書人閱讀 51,688評(píng)論 1 305
  • 那天,我揣著相機(jī)與錄音胰蝠,去河邊找鬼歼培。 笑死震蒋,一個(gè)胖子當(dāng)著我的面吹牛,可吹牛的內(nèi)容都是我干的躲庄。 我是一名探鬼主播查剖,決...
    沈念sama閱讀 40,414評(píng)論 3 418
  • 文/蒼蘭香墨 我猛地睜開眼,長(zhǎng)吁一口氣:“原來是場(chǎng)噩夢(mèng)啊……” “哼噪窘!你這毒婦竟也來了笋庄?” 一聲冷哼從身側(cè)響起,我...
    開封第一講書人閱讀 39,319評(píng)論 0 276
  • 序言:老撾萬榮一對(duì)情侶失蹤倔监,失蹤者是張志新(化名)和其女友劉穎直砂,沒想到半個(gè)月后,有當(dāng)?shù)厝嗽跇淞掷锇l(fā)現(xiàn)了一具尸體浩习,經(jīng)...
    沈念sama閱讀 45,775評(píng)論 1 315
  • 正文 獨(dú)居荒郊野嶺守林人離奇死亡静暂,尸身上長(zhǎng)有42處帶血的膿包…… 初始之章·張勛 以下內(nèi)容為張勛視角 年9月15日...
    茶點(diǎn)故事閱讀 37,945評(píng)論 3 336
  • 正文 我和宋清朗相戀三年,在試婚紗的時(shí)候發(fā)現(xiàn)自己被綠了谱秽。 大學(xué)時(shí)的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片洽蛀。...
    茶點(diǎn)故事閱讀 40,096評(píng)論 1 350
  • 序言:一個(gè)原本活蹦亂跳的男人離奇死亡,死狀恐怖疟赊,靈堂內(nèi)的尸體忽然破棺而出郊供,到底是詐尸還是另有隱情仪糖,我是刑警寧澤仇哆,帶...
    沈念sama閱讀 35,789評(píng)論 5 346
  • 正文 年R本政府宣布,位于F島的核電站返敬,受9級(jí)特大地震影響椅挣,放射性物質(zhì)發(fā)生泄漏。R本人自食惡果不足惜塔拳,卻給世界環(huán)境...
    茶點(diǎn)故事閱讀 41,437評(píng)論 3 331
  • 文/蒙蒙 一鼠证、第九天 我趴在偏房一處隱蔽的房頂上張望。 院中可真熱鬧靠抑,春花似錦量九、人聲如沸。這莊子的主人今日做“春日...
    開封第一講書人閱讀 31,993評(píng)論 0 22
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽。三九已至载城,卻和暖如春肌似,著一層夾襖步出監(jiān)牢的瞬間,已是汗流浹背诉瓦。 一陣腳步聲響...
    開封第一講書人閱讀 33,107評(píng)論 1 271
  • 我被黑心中介騙來泰國打工川队, 沒想到剛下飛機(jī)就差點(diǎn)兒被人妖公主榨干…… 1. 我叫王不留力细,地道東北人。 一個(gè)月前我還...
    沈念sama閱讀 48,308評(píng)論 3 372
  • 正文 我出身青樓固额,卻偏偏與公主長(zhǎng)得像眠蚂,于是被迫代替她去往敵國和親。 傳聞我的和親對(duì)象是個(gè)殘疾皇子斗躏,可洞房花燭夜當(dāng)晚...
    茶點(diǎn)故事閱讀 45,037評(píng)論 2 355

推薦閱讀更多精彩內(nèi)容