SpringBoot 是原生支援配置遷移的，但是官方文件沒有看到這方面描述，在原始碼中才看到此模組，spring-boot-properties-migrator，幸虧我沒有跳過。看到這篇文章的各位，可算是撿到寶了，相信你繼續往下看下去，定會忍不住點贊、收藏、關注。

效果

先放個效果吸引你 :)

從 SpringBoot 2.0.0 版本開始，配置服務上下文，不支援 server.context-path，而需要server.servlet.context-path配置。但是隻要加上以下一個官方依賴，就可以支援使用 server.context-path

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

server.context-path 所對應的屬性 ServerProperties#contextPath 在 Java 程式碼中已不存在，server.servlet.context-path 所對應的的屬性在內部類 Servlet 中才有，為何加了此依賴就能實現如此神奇的效果呢。

原理

SpringBoot 對外部化配置原生支援遷移功能，所謂遷移，具體是指對應配置的屬性名變動，仍可以使用原來的屬性名配置。
在 spring-configuration-metadata.json 的資訊可以輔助 IDE 進行配置的提示，也可以用來完成配置的遷移。非常的簡單。

相關文章： SpringBoot 配置提示功能

通過閱讀程式碼，獲得以下資訊：

1. 監聽 ApplicationPreparedEvent 事件（即：環境已準備事件），執行以下操作並收集資訊
2. 從 classpath*:/META-INF/spring-configuration-metadata.json 中載入所有配置
3. 從上下文的 environment 中過濾出提示的配置（滿足條件：1. deprecation 不為 null，且提示 level 為 error）
4. 判斷是否相容（相容條件見下一節），提取出相容的屬性
5. 將 value 對應到 replacement 的 key，並將其屬性源命名為：migrate-原名
6. 將配置遷移的新屬性源新增到 environment 中，且新增
   到原屬性源之前（優先順序高）。
7. 監聽事件：ApplicationReadyEvent（應用上下文已準備） 或 ApplicationFailedEvent（應用啟動失敗），列印以上步驟收集的遺留配置資訊。以 warn 級別列印相容的配置，以 error 級別列印不相容的配置

配置相容條件

根據元資料中定義的 type 判斷

1. 如果舊型別、新型別其中之一為 null（元資料中未指定），則不相容
2. 如果兩個型別一樣，相容
3. 如果新型別是 Duration，而舊型別是 Long 或 Integer，則相容
4. 其他情況視為不相容
5. 從 environment 中取配置資訊，理論上支援 SpringBoot 所有的配置方式。

效果

相容效果：
棄用屬性（如果還存在）與替換後的屬性都會使用配置檔案中的棄用的屬性名所對應的的值。

總結

使用配置遷移功能，需要以下步驟：

1. 引入依賴：spring-boot-properties-migrator（支援配置遷移）、spring-boot-configuration-processor（生成元資料檔案，如果已經有完整的，不需要此依賴）
2. 元資料檔案spring-configuration-metadata.json 中棄用屬性名對應的 properties 中必須有 deprecation（在additional-spring-configuration-metadata.json 中新增，相關文章： SpringBoot 配置提示功能）
3. deprecation 中需指定 level 為 error
4. deprecation 中需指定 replacement
5. replacement 對應的屬性配置在元資料檔案中存在，與棄用屬性相容

經典示例之配置上下文

再說回一開始展示的配置上下文示例。

# 配置 servlet 服務上下文
server:
  context-path: test

從 SpringBoot 2.0.0 版本開始，以上配置不支援，點到配置元資料檔案中（spring-configuration-metadata.json），發現如下資訊：

{
  "properties": [
    {
      "name": "server.context-path",
      "type": "java.lang.String",
      "description": "Context path of the application.",
      "deprecated": true,
      "deprecation": {
        "level": "error",
        "replacement": "server.servlet.context-path"
      }
    },
    {
      "name": "server.servlet.context-path",
      "type": "java.lang.String",
      "description": "Context path of the application.",
      "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties$Servlet"
    }

替換屬性名為：server.servlet.context-path，此屬性在org.springframework.boot.autoconfigure.web.ServerProperties 中，且在類中可以發現，server.context-path 所對應的屬性 ServerProperties#contextPath 在程式碼中已不存在，而是在內部類 Servlet 中有，也就是對應 server.servlet.context-path 的屬性才有。

但是其滿足配置相容的條件，為什麼實際上使用卻好像不相容呢？
其實是因為沒有引入依賴，當引入依賴，就會發現此方式配置可以起作用。

示例之兩種屬性都存在

程式碼示例見 https://gitee.com/lw888/spring-boot-source-example/tree/master/properties-migrator

1、引入依賴

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

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-configuration-processor</artifactId>
  <optional>true</optional>
</dependency>

2、Java 配置
此處故意保留棄用屬性

@Data
@Configuration
@ConfigurationProperties(prefix = "my")
public class MyProperties {
  /** the project name */
  private String name;

  private App app;

  @Data
  public static class App {
    private String name;
  }
}

3、元資料配置，spring-configuration-metadata.json 由程式生成，自定義配置放在 additional-spring-configuration-metadata.json 中

{
  "properties": [
    {
      "name": "my.name",
      "type": "java.lang.String",
      "description": "the project name.",
      "deprecation": {
        "reason": "test the properties-migrator feature.",
        "replacement": "my.app.name",
        "level": "error"
      }
    },
    {
      "name": "my.app.name",
      "type": "java.lang.String",
      "sourceType": "com.lw.properties.migrator.config.MyProperties$App",
      "description": "the project name."
    }
  ]
}

4、在 properties 或 yml 檔案中配置

my:
  name: lw
  app:
    name: app

5、列印配置資訊

@Slf4j
@SpringBootApplication
public class PropertiesMigratorApplication {

  public static void main(String[] args) {
    ConfigurableApplicationContext context =
        SpringApplication.run(PropertiesMigratorApplication.class, args);
    MyProperties myProperties = context.getBean(MyProperties.class);
    log.info("myProperties.name:{}", myProperties.getName());
    log.info(
        "myProperties$app.name:{}",
        Optional.ofNullable(myProperties.getApp()).orElse(new App()).getName());
  }
}

6、列印資訊如下：

2019-11-23 21:42:09.580 WARN 109408 --- [ 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.yml]':
Key: my.name
Line: 4
Replacement: my.app.name
Key: server.context-path
Line: 2
Replacement: server.servlet.context-path

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.
......... myProperties.name:lw
......... myProperties\(app.name:lw ......... serverProperties\)servlet.contextPath:/app

7、效果解析
在 yml 中棄用屬性名優先順序更高，棄用屬性與新屬性都使用此棄用屬性名對應的值。

參考資料

SpringBoot 2.2.1.RELEASE 原始碼
公眾號：逸飛兮（專注於 Java 領域知識的深入學習，從原始碼到原理，系統有序的學習）

相關推薦