В Spring Boot 1.3.0 было выпущено много обновлений, но одно из них было мне выгодно, потому что я не знал об этом раньше, и состояние, в котором он оказался, делает его действительно полезной функцией (к сожалению, доступной только в Spring Boot на момент написания статьи). это). Я говорю о метаданных конфигурации и обработке, относящихся к этой области фреймворка / приложения. Как я покажу далее, есть несколько способов его использования, и инфраструктура также позволяет вам использовать преимущества автоматизированной обработки. Если вы чувствуете необходимость взять дело в свои руки, не беспокойтесь — есть способ ручного ввода, если вы хотите использовать некоторые функции, позволяющие точно настроить вашу настройку. Давайте поговорим о конфигурации.
Метаданные конфигурации в Spring Boot
Посмотрим правде в глаза — мы все были там. Приложение, над которым вы работаете, должно быть настраиваемым, однако, когда дело доходит до реальной документации, все становится немного странным. Обычно есть несколько способов, которыми команда справляется с этой изящной задачей. Описано ли оно и управляется ли оно в вики проекта, является ли оно частью комментариев в файлах свойств, записано ли в комментариях Javadoc, или не существует вообще, мы все можем согласиться с тем, что это далеко от желаемого состояния дел. С этим связано несколько проблем, таких как предоставление документации всем заинтересованным сторонам (например, команде разработчиков), ее версия и поддержание в актуальном состоянии (особенно обновления, которые не являются обратно совместимыми) или просто прояснение того, какие варианты доступны или не рекомендуются, и что они значат для приложения.
Настройка проекта
Первый шаг — все настроить. Как упоминалось ранее, вам нужно будет использовать Spring Boot 1.3.0 или новее вместе со специальной зависимостью, обеспечивающей перекомпиляцию файла, содержащего метаданные, которые позже обрабатываются другими инструментами, такими как IDE. Артефакт называется spring-boot-configruation-processor и должен быть помечен как optional .
Пружинная загрузочная зависимость в pom.xml
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
|
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>1.3.1.RELEASE</version> <relativePath/></parent> <dependencies> ... <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency> ...</dependencies> |
Вторым шагом этой настройки является включение свойств конфигурации и создание класса, который их содержит. Это довольно простая задача (особенно если у вас есть опыт работы с Spring Boot). Давайте назовем этот класс MyProperties .
Класс конфигурации, включающий свойства конфигурации
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
|
@Configuration@EnableConfigurationProperties({MyProperties.class})public class ApplicationConfiguration { @Autowired private MyProperties myProperties; public MyProperties getMyProperties() { return myProperties; } public void setMyProperties(MyProperties myProperties) { this.myProperties = myProperties; }} |
Готовые метаданные конфигурации
Класс MyProperties отражает свойства с префиксом слова my . Теперь, когда у нас все настроено и готово к работе, давайте посмотрим, как этот механизм работает в двух самых основных случаях. Рассмотрим эти два свойства конфигурации — одно свойство String ( property ) и свойство, использующее значение enum ( copyOption ). Оба эти свойства описаны с использованием стандартного Javadoc, плюс в случае StandardCopyOption каждое значение enum имеет свой собственный комментарий Javadoc. Поддержка Spring Boots для метаданных конфигурации пытается извлечь максимальную пользу из кода, так как от разработчика ожидается правильное комментирование их свойств конфигурации (действительно полезно и удобно в случае enum ).
Пример класса свойств конфигурации
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
|
@ConfigurationProperties(prefix = "my")public class MyProperties { /** * String property used to configure my app. */ private String property; /** * Configuration for file operations. */ private StandardCopyOption copyOption; public String getProperty() { return property; } public void setProperty(String property) { this.property = property; } public StandardCopyOption getCopyOption() { return copyOption; } public void setCopyOption(StandardCopyOption copyOption) { this.copyOption = copyOption; } } |
Теперь пришло время увидеть, как происходит волшебство. Упомянутая ранее зависимость Spring гарантирует, что метаданные генерируются во время сборки вашего проекта. Чтобы получить что-то из всей этой установки, вам нужно знать, как ваша IDE поддерживает эту функцию Spring Boot. Например, насколько я знаю, Eclipse IDE при сохранении действия / события запускает сборку, которая заботится о поддержании актуальности метаданных. Когда дело доходит до IntelliJ IDEA, вам нужно запускать сборку вручную, поскольку нет события сохранения / сохранения. После завершения сборки вы можете исследовать target папку (в случае использования maven) и искать новый добавленный файл target\classes\META-INF\spring-configuration-metadata.json . Учитывая приведенный выше код, вы должны увидеть что-то похожее на это:
Содержимое target \ classes \ META-INF \ spring-configuration-metadata.json
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
|
{ "groups": [{ "name": "my", "type": "com.jakubstas.s3downloader.MyProperties", "sourceType": "com.jakubstas.s3downloader.MyProperties" }], "properties": [ { "name": "my.copy-option", "type": "java.nio.file.StandardCopyOption", "description": "Configuration for file operations.", "sourceType": "com.jakubstas.s3downloader.MyProperties" }, { "name": "my.property", "type": "java.lang.String", "description": "String property used to configure my app.", "sourceType": "com.jakubstas.s3downloader.MyProperties" } ], "hints": []} |
Этот файл теперь доступен либо инструменту, который нужно прочитать и обработать, либо члену группы, чтобы проверить, как настроить приложение. При этом, как только я открываю application.properties в редакторе IntelliJ IDEA и начинаю вводить префикс для каждого из моих свойств, меня приветствует знакомое окно автоматического завершения кода, в котором есть понятие, для чего используется каждое из моих свойств (на основе на комментарий Javadoc):
В случае свойства enum я также могу видеть каждое из значений enum с соответствующим комментарием Javadoc:
Выбор значения по умолчанию
Одним из наиболее простых вариантов использования документации конфигурации является выбор разумного значения по умолчанию для свойств конфигурации, чтобы максимально упростить настройку приложения. Давайте посмотрим, как этого добиться в этой настройке. Для того чтобы разрешить любой ручной ввод в spring-configuration-metadata.json file , разработчик должен сначала создать новый отдельный файл, который впоследствии будет выбран процессом сборки. Это еще один файл json, называемый additional-spring-configuration-metadata.json который должен быть создан в папке META-INF и должен соответствовать синтаксису, описанному в Приложении B. additional-spring-configuration-metadata.json конфигурации .
Таким образом, как только я определюсь со своими значениями по умолчанию и доступными параметрами (я хочу представить два предопределенных параметра, но все же разрешить использование любых других значений String в моем свойстве String ), я могу создать этот файл со следующим содержимым:
Содержимое файла дополнения-spring-configuration-metadata.json
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
|
{ "properties": [ { "name": "my.copy-option", "type": "java.lang.String", "sourceType": "java.nio.file.StandardCopyOption", "defaultValue": "replace_existing" }, { "name": "my.property", "defaultValue": "something" } ], "hints": [ { "name": "my.property", "values": [ { "value": "nothing", "description": "Does nothing." }, { "value": "something", "description": "Does something." } ] } ]} |
Это приводит в значительной степени к тому, что можно ожидать, и уже можно увидеть в некоторых зависимостях Spring Boot. В случае свойства String оба параметра представлены с соответствующими описаниями. Опция по умолчанию была закреплена болтами.
Поведение свойства enum немного отличается, так как в среде IDE опция не выделяется, а помещается в верхней части списка.
И, наконец, давайте посмотрим, что вы получаете, когда вы еще не выбрали ни одного конкретного свойства. В этом случае оба свойства показывают их описания из Javadoc и их значения по умолчанию.
Вывод
Это было краткое введение в то, как вы можете сделать вашу конфигурацию сияющей. Этот пост только показал, чего можно достичь, и все же ему удалось показать большой потенциал этой функции. Я рекомендую вам попробовать эту функцию и убедиться, что подобная установка работает для вас и вашей команды. Я буду вдаваться в подробности и расширенные возможности поддержки этой конфигурации в следующем посте. Будьте на связи!
| Ссылка: | Добавьте в свою конфигурацию метаданные конфигурации в Spring Boot от нашего партнера по JCG Якуба Стаса в блоге |