Рубрики
Без рубрики

Руководство по метаданным конфигурации Spring Boot

Узнайте о процессоре конфигурации Spring Boot и связанных с ним файлах метаданных JSON, которые документируют значение каждого свойства, ограничения и т. Д.

Автор оригинала: Dionis Prifti.

1. Обзор

При написании приложения Spring Boot полезно сопоставить свойства конфигурации с компонентами Java . Как лучше всего документировать эти свойства?

В этом уроке мы рассмотрим процессор конфигурации Spring Boot и связанные файлы метаданных JSON , которые документируют значение каждого свойства, ограничения и т. Д.

2. Метаданные конфигурации

Большинство приложений, над которыми мы работаем как разработчики, должны быть в какой-то степени настраиваемыми. Однако обычно мы действительно не понимаем, что делает параметр конфигурации, если он имеет значение по умолчанию, если он устарел, а иногда мы даже не знаем, что это свойство существует.

Чтобы помочь нам, Spring Boot генерирует метаданные конфигурации в файле JSON, который дает нам полезную информацию о том, как использовать эти свойства. Итак, метаданные конфигурации-это описательный файл, содержащий необходимую информацию для взаимодействия со свойствами конфигурации.

Самое приятное в этом файле то, что IDE тоже могут его читать , давая нам автозаполнение свойств Spring, а также другие подсказки по настройке.

3. Зависимости

Чтобы сгенерировать эти метаданные конфигурации, мы будем использовать процессор конфигурации из spring-boot-configuration-processor dependency .

Итак, давайте продолжим и добавим зависимость как необязательную :


    org.springframework.boot
    spring-boot-configuration-processor
    2.1.6.RELEASE
    true

Эта зависимость предоставит нам процессор аннотаций Java, вызываемый при построении нашего проекта. Подробнее об этом мы поговорим позже.

Рекомендуется добавить зависимость как необязательную в Maven, чтобы предотвратить применение @ConfigurationProperties к другим модулям, используемым нашим проектом.

4. Пример Свойств Конфигурации

Чтобы увидеть процессор в действии, давайте представим, что у нас есть несколько свойств, которые нам нужно включить в наше приложение Spring Boot через Java bean:

@Configuration
@ConfigurationProperties(prefix = "database")
public class DatabaseProperties {
	
    public static class Server {

        private String ip;
        private int port;

        // standard getters and setters
    }
	
    private String username;
    private String password;
    private Server server;
	
    // standard getters and setters
}

Для этого мы используем аннотацию @ConfigurationProperties . Процессор конфигурации сканирует классы и методы с этой аннотацией для доступа к параметрам конфигурации и генерации метаданных конфигурации.

Давайте добавим несколько таких свойств в файл свойств. В этом случае мы назовем его database properties-test.properties :

#Simple Properties
database.username=baeldung
database.password=password

И, чтобы быть уверенным, мы также добавим тест, чтобы убедиться, что мы все выстроились в очередь:

@RunWith(SpringRunner.class)
@SpringBootTest(classes = AnnotationProcessorApplication.class)
@TestPropertySource("classpath:databaseproperties-test.properties")
public class DatabasePropertiesIntegrationTest {

    @Autowired
    private DatabaseProperties databaseProperties;

    @Test
    public void whenSimplePropertyQueriedThenReturnsPropertyValue() 
      throws Exception {
        Assert.assertEquals("Incorrectly bound Username property", 
          "baeldung", databaseProperties.getUsername());
        Assert.assertEquals("Incorrectly bound Password property", 
          "password", databaseProperties.getPassword());
    }
    
}

Мы также добавили вложенные свойства database.server.id и database.server.port через внутренний класс Server . Мы должны добавить внутренний класс Server , а также поле server со своими собственными геттером и сеттером.

В нашем тесте давайте сделаем быструю проверку, чтобы убедиться, что мы также можем успешно устанавливать и читать вложенные свойства:

@Test
public void whenNestedPropertyQueriedThenReturnsPropertyValue() 
  throws Exception {
    Assert.assertEquals("Incorrectly bound Server IP nested property",
      "127.0.0.1", databaseProperties.getServer().getIp());
    Assert.assertEquals("Incorrectly bound Server Port nested property", 
      3306, databaseProperties.getServer().getPort());
}

Итак, теперь мы готовы использовать процессор.

5. Генерация Метаданных Конфигурации

Мы уже упоминали ранее, что процессор конфигурации генерирует файл – он делает это с помощью обработки аннотаций.

Итак, после компиляции нашего проекта мы увидим файл под названием spring-configuration-metadata.json inside target/classes/META-INF :

{
  "groups": [
    {
      "name": "database",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceMethod": "getServer()"
    }
  ],
  "properties": [
    {
      "name": "database.password",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server.ip",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server"
    },
    {
      "name": "database.server.port",
      "type": "java.lang.Integer",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "defaultValue": 0
    },
    {
      "name": "database.username",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    }
  ],
  "hints": []
}

Далее давайте посмотрим, как изменение аннотаций на ваших Java-бобах влияет на метаданные.

5.1. Дополнительная информация о Метаданных конфигурации

Во-первых, давайте добавим комментарии JavaDoc на Server .

Во-вторых, давайте дадим значение по умолчанию полю database.server.port и, наконец, добавим аннотации @Min и @Max :

public static class Server {

    /**
     * The IP of the database server
     */
    private String ip;

    /**
     * The Port of the database server.
     * The Default value is 443.
     * The allowed values are in the range 400-4000.
     */
    @Min(400)
    @Max(800)
    private int port = 443;

    // standard getters and setters
}

Если мы сейчас проверим файл spring-configuration-metadata.json , то увидим, что эта дополнительная информация отражена:

{
  "groups": [
    {
      "name": "database",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceMethod": "getServer()"
    }
  ],
  "properties": [
    {
      "name": "database.password",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server.ip",
      "type": "java.lang.String",
      "description": "The IP of the database server",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server"
    },
    {
      "name": "database.server.port",
      "type": "java.lang.Integer",
      "description": "The Port of the database server. The Default value is 443.
        The allowed values are in the range 400-4000",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "defaultValue": 443
    },
    {
      "name": "database.username",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    }
  ],
  "hints": []
}

Мы можем проверить различия с помощью полей database.server.ip и database.server.port . Действительно, дополнительная информация весьма полезна. В результате разработчикам и разработчикам идей гораздо легче понять, что делает каждое свойство.

Мы также должны убедиться, что запускаем сборку, чтобы получить обновленный файл. В Eclipse, если мы проверим опцию Build Automatically , каждое действие сохранения вызовет сборку. В IntelliJ мы должны запустить сборку вручную.

5.2. Понимание формата метаданных

Давайте подробнее рассмотрим файл метаданных JSON и обсудим его компоненты.

Группы -это элементы более высокого уровня, используемые для группировки других свойств без указания самого значения. В нашем примере у нас есть группа database , которая также является префиксом свойств конфигурации. У нас также есть группа server , которую мы создали с помощью внутреннего класса и групп ip и port properties.

Свойства – это элементы конфигурации, для которых мы можем указать значение. Эти свойства задаются в файлах .properties или .yml и могут содержать дополнительную информацию, например значения по умолчанию и проверки, как мы видели в приведенном выше примере.

Подсказки – это дополнительная информация, помогающая пользователю установить значение свойства. Например, если у нас есть набор допустимых значений для свойства, мы можем предоставить описание того, что делает каждый из них. ИДЕЯ обеспечит автоконкурсную помощь для этих подсказок.

Каждый компонент метаданных конфигурации имеет свои собственные атрибуты для более подробного объяснения свойств конфигурации.

6. Заключение

В этой статье мы рассмотрели процессор конфигурации Spring Boot и его способность создавать метаданные конфигурации. Использование этих метаданных значительно упрощает взаимодействие с нашими параметрами конфигурации.

Мы приводим пример сгенерированных метаданных конфигурации и подробно объясняем их формат и компоненты.

Мы также увидели, насколько полезной может быть поддержка автозаполнения с нашей СТОРОНЫ.

Как всегда, все фрагменты кода, упомянутые в этой статье, можно найти в нашем репозитории GitHub .