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.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-<profile>.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.<source>属性定义的。例如，上面的配置将编写如下：

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"

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.

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

如果我们愿意，我们可以将 application-prod.yaml 重命名为 application.yaml，因为 Spring Boot 2.4 所有外部文件都会覆盖内部文件。

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 206,126评论 6赞 481
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 88,254评论 2赞 382
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 152,445评论 0赞 341
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 55,185评论 1赞 278
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 64,178评论 5赞 371
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,970评论 1赞 284
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 38,276评论 3赞 399
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,927评论 0赞 259
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 43,400评论 1赞 300
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,883评论 2赞 323
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,997评论 1赞 333
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,646评论 4赞 322
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 39,213评论 3赞 307
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,204评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,423评论 1赞 260
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 45,423评论 2赞 352
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,722评论 2赞 345

推荐阅读更多精彩内容