知識庫 / Spring / Spring Boot RSS 訂閱

1. 介紹

本教程將探討 Spring 提供的支持系統，以簡化 Spring Boot 升級過程。特別是，我們將研究 <em title="spring-boot-properties-migrator 模塊。該模塊有助於遷移應用程序屬性。

隨着每個 Spring Boot 版本的升級，可能會有屬性被標記為已過時、已停止支持，或者被新引入。Spring 會發布每個升級的 全面的變更日誌。然而，這些變更日誌可能比較繁瑣需要仔細閲讀。這時，spring-boot-properties-migrator 模塊就派上用場了。它通過為我們的配置提供個性化信息來實現這一點。

讓我們看看它在實踐中的效果！

2. 演示應用程序

讓我們將我們的 Spring Boot 應用程序從版本 2.3.0 升級到 2.6.3。

2.1. 屬性

在我們的演示應用程序中，我們有兩個屬性文件。在默認的 application.properties 文件中，讓我們添加：

spring.resources.cache.period=31536000
spring.resources.chain.compressed=false
spring.resources.chain.html-application-cache=false

對於 dev 配置文件 application-dev.yaml：

spring:
  resources:
    cache:
      period: 31536000
    chain:
      compressed: true
      html-application-cache: true

我們的屬性文件包含在 Spring Boot 2.3.0 和 2.6.3 之間被替換或刪除的多個屬性。此外，我們還擁有 .properties 和 .yaml 文件，以便更好地演示。

2.2. 添加依賴

首先，我們將 spring-boot-properties-migrator 作為依賴添加到我們的模塊中：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

如果使用 Gradle，我們可以添加：

runtime("org.springframework.boot:spring-boot-properties-migrator")

依賴項的範圍應為運行時。

3. 運行掃描

接下來，我們進行應用程序的打包和運行。我們將使用 Maven 進行構建和打包：

mvn clean package

最後，讓我們運行它：

java -jar target/spring-boot-properties-migrator-demo-1.0-SNAPSHOT.jar

因此，spring-boot-properties-migrator模塊掃描了我們的應用程序屬性文件，併發揮了它的魔力！稍後會詳細介紹。

4. 理解掃描輸出

讓我們通過查看日誌來理解掃描的建議。

4.1. 可替換屬性

對於具有已知替換屬性的屬性，我們會在 PropertiesMigrationListener 類中看到 WARN 日誌：

WARN 34777 --- [           main] o.s.b.c.p.m.PropertiesMigrationListener  : 
The use of configuration keys that have been renamed was found in the environment:

Property source 'Config resource 'class path resource [application.properties]' via location 'optional:classpath:/'':
	Key: spring.resources.cache.period
		Line: 2
		Replacement: spring.web.resources.cache.period
	Key: spring.resources.chain.compressed
		Line: 3
		Replacement: spring.web.resources.chain.compressed

Property source 'Config resource 'class path resource [application-dev.yaml]' via location 'optional:classpath:/'':
	Key: spring.resources.cache.period
		Line: 5
		Replacement: spring.web.resources.cache.period
	Key: spring.resources.chain.compressed
		Line: 7
		Replacement: spring.web.resources.chain.compressed


Each configuration key has been temporarily mapped to its replacement for your convenience. To silence this warning, please update your configuration to use the new keys.

我們能夠從日誌中獲取所有關鍵信息，例如每個條目關聯的屬性文件、鍵、行號和替換鍵。這有助於我們輕鬆識別和替換這些屬性。 此外，模塊會在運行時將這些屬性替換為可用的替換值，從而使我們能夠在不修改應用程序的情況下運行應用程序。

4.2. 不支持的屬性

對於沒有已知替代值的屬性，我們會在 日誌中看到 PropertiesMigrationListener 類產生的 ERROR 記錄：

ERROR 34777 --- [           main] o.s.b.c.p.m.PropertiesMigrationListener  : 
The use of configuration keys that are no longer supported was found in the environment:

Property source 'Config resource 'class path resource [application.properties]' via location 'optional:classpath:/'':
	Key: spring.resources.chain.html-application-cache
		Line: 4
		Reason: none

Property source 'Config resource 'class path resource [application-dev.yaml]' via location 'optional:classpath:/'':
	Key: spring.resources.chain.html-application-cache
		Line: 8
		Reason: none

與之前的情況類似，我們看到問題的屬性文件、鍵、屬性文件中該行的行號以及該鍵被移除的原因。但與之前的情況不同，應用程序的啓動可能取決於該屬性，可能會失敗。我們還可能遇到運行時問題，因為這些屬性無法自動遷移。

5. 更新配置屬性

現在，有了掃描儀提供的重要信息，我們已經處於更好的狀態，可以升級屬性。我們知道要修改的屬性文件、行號以及鍵，可以根據建議替換它們，或者查閲特定鍵在發佈説明中是否有替代方案。

讓我們修復我們的屬性文件。在默認屬性文件 application.properties 中，按照建議替換屬性：

spring.web.resources.cache.period=31536000
spring.web.resources.chain.compressed=false

同樣，我們來更新 dev 配置文件 application-dev.yaml：

spring:
  web:
    resources:
      cache:
        period: 31536000
      chain:
        compressed: false

總而言之，我們已將屬性 spring.resources.cache.period 替換為 spring.web.resources.cache.period，以及 spring.resources.chain.compressed 替換為 spring.web.resources.chain.compressed。 spring.resources.chain.html-application-cache 鍵在新版本中已不再受支持，因此在本例中已將其移除。

讓我們再次運行掃描。首先，讓我們構建應用程序：

mvn clean package

然後，讓我們運行它：

java -jar target/spring-boot-properties-migrator-demo-1.0-SNAPSHOT.jar

現在，我們之前從 PropertiesMigrationListener 類中看到的所有信息日誌都消失了，這表明我們的屬性遷移已成功！

6. 這一切是如何工作的？ 深入瞭解內部構造

Spring Boot 模塊 JAR 文件包含一個 spring-configuration-metadata.json 文件，位於 META-INF 文件夾中。 這些 JSON 文件是 spring-boot-properties-migrator 模塊的信息來源。 當它掃描我們的屬性文件時，它會從這些 JSON 文件中提取相關屬性的元數據信息，以構建掃描報告。

以下是一個示例，展示了我們在生成的報告中看到的信息：

在 spring-autoconfigure:2.6.3.jarMETA-INF/spring-configuration-metadata.json 中，我們將會找到 spring.resources.cache.period 的條目：

{
    "name": "spring.resources.cache.period",
    "type": "java.time.Duration",
    "deprecated": true,
    "deprecation": {
        "level": "error",
        "replacement": "spring.web.resources.cache.period"
    }
}

同樣，在 <em >spring-boot:2.0.0.RELEASE.jar</em> 的 <em >META-INF/spring-configuration-metadata.json</em> 中，我們能找到 <em >banner.image.location</em> 的條目：

{
    "defaultValue": "banner.gif",
    "deprecated": true,
    "name": "banner.image.location",
    "description": "Banner image file location (jpg\/png can also be used).",
    "type": "org.springframework.core.io.Resource",
    "deprecation": {
        "level": "error",
        "replacement": "spring.banner.image.location"
    }
}

7. 注意事項

在總結本文之前，我們先來回顧一下與 spring-boot-properties-migrator 的一些注意事項。

7.1. 不要將此依賴項部署到生產環境

本模塊僅供在開發環境中進行升級時使用。一旦我們確定需要更新或刪除的屬性，並進行修正，我們就可以從我們的依賴項中移除該模塊。最終，我們不應在更高環境中包含該模塊。由於與該模塊相關的某些成本，因此不建議在生產環境中使用它。 不建議 在生產環境中使用它。

7.2. 歷史屬性

我們不應在升級過程中跳過版本，因為模塊可能無法檢測在較舊版本中已棄用的真正舊屬性。例如，讓我們將 <em >banner.image.location</em > 添加到我們的 <em >application.properties</em > 文件中：

banner.image.location="myBanner.txt"

該屬性在 Spring Boot 2.0 中已棄用 （配置變更日誌）。 如果我們嘗試使用 Spring Boot 版本 2.6.3 運行應用程序，將不會看到有關此屬性的任何警告或錯誤消息。 我們需要使用 Spring Boot 2.0 運行掃描，才能檢測到該屬性：

WARN 25015 --- [           main] o.s.b.c.p.m.PropertiesMigrationListener  : 
The use of configuration keys that have been renamed was found in the environment:

Property source 'applicationConfig: [classpath:/application.properties]':
    Key: banner.image.location
	Line: 5
	Replacement: spring.banner.image.location


Each configuration key has been temporarily mapped to its replacement for your convenience. To silence this warning, please update your configuration to use the new keys.

8. 結論

在本文中，我們探討了 <em >spring-boot-properties-migrator</em>。這是一個便捷的工具，它掃描我們的屬性文件並提供易於操作的掃描報告。我們還對該模塊實現高層功能進行了瞭解。最後，為了確保該工具的最佳利用，我們還討論了一些注意事項。