Мигратор свойств конфигурации Spring Boot

1. Введение

В этом руководстве мы рассмотрим систему поддержки, предоставляемую Spring для облегчения обновлений 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

Для YAML - файла профиля разработчика 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. Заменяемые свойства

Для свойств, имеющих известную замену, мы видим журналы WARN от класса PropertiesMigrationListener :

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 из класса PropertiesMigrationListener :

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

Аналогичным образом обновим YAML - файл профиля разработчика 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. Как все это работает? Заглянуть под капот

JAR-файл Spring Boot Module содержит файл spring-configuration-metadata.json в папке META- INF . Эти файлы JSON являются источниками информации для модуля spring-boot-properties-migrator . Когда он сканирует наши файлы свойств, он извлекает метаданные соответствующих свойств из этих файлов JSON для создания отчета о сканировании.

На примере из файла показана различная информация, которую мы видим в сгенерированных отчетах:

В spring-autoconfigure:2.6.3.jar META-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"
    }
}

Точно так же в spring-boot:2.0.0.RELEASE.jar META-INF/spring-configuration-metadata.json мы найдем запись для banner.image.location :

{
    "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. Историческая недвижимость

Мы не должны переключаться между версиями во время обновлений, потому что модуль может быть не в состоянии обнаружить действительно старые свойства, которые устарели в гораздо более старых версиях. Например, давайте добавим banner.image.location в наш файл application.properties : ``

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. Заключение

В этой статье мы рассмотрели spring-boot-properties-migrator . Это удобный инструмент, который сканирует наш файл свойств и предоставляет удобные отчеты о сканировании. Мы также рассмотрели общее представление о том, как модуль достигает своих целей. Наконец, чтобы обеспечить наилучшее использование этого инструмента, мы сделали несколько предостережений.

Как всегда, код доступен на GitHub .