使用 Spring Boot 属性迁移器轻松升级配置

1. 介绍

Spring Boot 提供了一个强大的升级支持系统，本文将重点探讨其中的 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

然后在开发环境配置文件 application-dev.yaml 中：

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

这些配置包含了在 2.3.0 到 2.6.3 版本间被替换或移除的属性。我们特意同时使用 .properties 和 .yaml 格式来全面演示功能。

2.2. 添加依赖

首先添加 spring-boot-properties-migrator 依赖（Maven）：

<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")

注意：依赖作用域必须设为 runtime。

3. 运行扫描

使用 Maven 打包应用：

mvn clean package

然后启动应用：

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

spring-boot-properties-migrator 会自动扫描配置文件并生成诊断报告——这正是它的神奇之处！

4. 解读扫描结果

通过日志分析扫描报告的建议。

4.1. 可替换的属性

对于有明确替换方案的属性，会看到 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. 不支持的属性

对于没有替换方案的属性，会触发 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

同样提供了：

问题配置文件
属性名及行号
移除原因（本例为 none）

警告：这类属性可能导致应用启动失败或运行时异常，因为模块无法自动迁移它们。

5. 更新配置属性

根据扫描结果，现在可以精准地升级配置：

修改 application.properties：

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

更新 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 包中包含 META-INF/spring-configuration-metadata.json 文件，这些元数据是迁移器的信息源。扫描时，模块会解析这些 JSON 文件生成诊断报告。

以 spring-autoconfigure:2.6.3.jar 中的元数据为例：

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

再如 spring-boot:2.0.0.RELEASE.jar 中的：

{
    "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. 注意事项

使用迁移器时需留意以下限制：

7.1. 不要在生产环境保留该依赖

该模块仅用于开发阶段的升级辅助。完成配置更新后应立即移除依赖，生产环境务必不要包含此模块，因为官方文档明确指出它会带来额外开销。

7.2. 历史属性问题

不要跨大版本升级！模块可能检测不到在旧版本中就已废弃的属性。例如在 application.properties 中添加：

banner.image.location="myBanner.txt"

这个属性在 Spring Boot 2.0 就已废弃。如果直接用 2.6.3 启动，不会收到任何警告。必须使用 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. 总结

我们深入了解了 spring-boot-properties-migrator 这个实用工具，它能：

扫描配置文件生成可操作的迁移报告
运行时自动映射可替换属性
精准定位不再支持的属性

通过元数据解析机制，模块实现了智能化的配置升级支持。只要注意避免生产环境使用和历史属性检测的局限，就能显著简化 Spring Boot 升级流程。

完整示例代码可在 GitHub 获取。

Persistence

REST

Security