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

JAR-файлы Spring Boot содержат файлы метаданных, которые предоставляют подробную информацию обо всех поддерживаемых свойствах конфигурации. Эти файлы разработаны для того, чтобы разработчики IDE могли предлагать контекстную помощь и «автозаполнение» кода по мере работы пользователей с файлами application.properties или application.yaml.

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

1. Формат метаданных

Файлы метаданных конфигурации находятся внутри JAR-файлов по адресу META-INF/spring-configuration-metadata.json. Они используют формат JSON с элементами, категоризованными как «группы» или «свойства», и дополнительными подсказками, категоризованными как «подсказки», как показано в следующем примере:

{"groups": [
    {
        "name": "server",
        "type": "org.springframework.boot.autoconfigure.web.ServerProperties",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    },
    {
        "name": "spring.jpa.hibernate",
        "type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate",
        "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties",
        "sourceMethod": "getHibernate()"
    }
    ...
],"properties": [
    {
        "name": "server.port",
        "type": "java.lang.Integer",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    },
    {
        "name": "server.address",
        "type": "java.net.InetAddress",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    },
    {
          "name": "spring.jpa.hibernate.ddl-auto",
          "type": "java.lang.String",
          "description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.",
          "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate"
    }
    ...
],"hints": [
    {
        "name": "spring.jpa.hibernate.ddl-auto",
        "values": [
            {
                "value": "none",
                "description": "Disable DDL handling."
            },
            {
                "value": "validate",
                "description": "Validate the schema, make no changes to the database."
            },
            {
                "value": "update",
                "description": "Update the schema if necessary."
            },
            {
                "value": "create",
                "description": "Create the schema and destroy previous data."
            },
            {
                "value": "create-drop",
                "description": "Create and then destroy the schema at the end of the session."
            }
        ]
    }
]}

Каждое «свойство» — это элемент конфигурации, который пользователь задаёт определённым значением. Например, server.port и server.address могут быть заданы в вашем файле application.properties/application.yaml, следующим образом:

Свойства

server.port=9090
server.address=127.0.0.1

Yaml

server:
  port: 9090
  address: 127.0.0.1

«Группы» — это элементы более высокого уровня, которые сами по себе не задают значения, а вместо этого обеспечивают контекстную группировку свойств. Например, свойства server.port и server.address являются частью группы server.

Необязательно, чтобы каждое «свойство» имело «группу». Некоторые свойства могут существовать самостоятельно.

Наконец, «подсказки» — это дополнительная информация, используемая для помощи пользователю в настройке данного свойства. Например, когда разработчик настраивает свойство spring.jpa.hibernate.ddl-auto, инструмент может использовать подсказки, чтобы предложить автозаполнение значений none, validate, update, create, и create-drop.

1.1. Атрибуты групп

Объект JSON, содержащийся в массиве groups, может содержать атрибуты, показанные в следующей таблице:

Имя Тип Назначение

Имя	Тип	Назначение
`name`	Строка	Полное имя группы. Этот атрибут обязателен.
`type`	Строка	Имя класса типа данных группы. Например, если группа основана на классе, помеченном аннотацией `@ConfigurationProperties`, атрибут будет содержать полное имя этого класса. Если она основана на методе `@Bean`, то это будет тип возвращаемого значения этого метода. Если тип неизвестен, атрибут может быть опущен.
`description`	Строка	Краткое описание группы, которое может отображаться пользователям. Если описание недоступно, оно может быть опущено. Рекомендуется использовать краткие абзацы, где первая строка даёт краткое изложение. Последняя строка описания должна заканчиваться точкой (`.`).
`sourceType`	Строка	Имя класса источника, который внес вклад в эту группу. Например, если группа основана на методе `@Bean` с аннотацией `@ConfigurationProperties`, этот атрибут будет содержать полное имя класса `@Configuration`, который содержит метод. Если тип источника неизвестен, атрибут может быть опущен.
`sourceMethod`	Строка	Полное имя метода (включая скобки и типы аргументов), внесшего вклад в эту группу (например, имя метода `@ConfigurationProperties` с аннотацией `@Bean`). Если исходный метод неизвестен, атрибут может быть опущен.

name

Строка

Полное имя группы. Этот атрибут обязателен.

type

Строка

Имя класса типа данных группы. Например, если группа основана на классе, помеченном аннотацией @ConfigurationProperties, атрибут будет содержать полное имя этого класса. Если она основана на методе @Bean, то это будет тип возвращаемого значения этого метода. Если тип неизвестен, атрибут может быть опущен.

description

Строка

Краткое описание группы, которое может отображаться пользователям. Если описание недоступно, оно может быть опущено. Рекомендуется использовать краткие абзацы, где первая строка даёт краткое изложение. Последняя строка описания должна заканчиваться точкой (.).

sourceType

Строка

Имя класса источника, который внес вклад в эту группу. Например, если группа основана на методе @Bean с аннотацией @ConfigurationProperties, этот атрибут будет содержать полное имя класса @Configuration, который содержит метод. Если тип источника неизвестен, атрибут может быть опущен.

sourceMethod

Строка

Полное имя метода (включая скобки и типы аргументов), внесшего вклад в эту группу (например, имя метода @ConfigurationProperties с аннотацией @Bean). Если исходный метод неизвестен, атрибут может быть опущен.

1.2. Атрибуты свойств

Объект JSON, содержащийся в массиве properties, может содержать атрибуты, описанные в следующей таблице:

Имя Тип Назначение

Имя	Тип	Назначение
`name`	Строка	Полное имя свойства. Имена имеют формат, разделенный точкой в нижнем регистре (например, `server.address`). Этот атрибут является обязательным.
`type`	Строка	Полная сигнатура типа данных свойства (например, `java.lang.String`) а также полный тип дженерика (например, `java.util.Map<java.lang.String,com.example.MyEnum>`). Вы можете использовать этот атрибут, чтобы направить пользователя на типы значений, которые он может ввести. Для согласованности, тип примитива определяется с помощью его обертки (например, `boolean` преобразуется в `java.lang.Boolean`). Обратите внимание, что этот класс может быть сложным типом, который преобразуется из `String`, когда значения привязываются. Если тип неизвестен, он может быть опущен.
`description`	Строка	Краткое описание свойства, которое может отображаться пользователям. Если описание недоступно, оно может быть опущено. Рекомендуется, чтобы описания были короткими абзацами, при этом первая строка предоставляла краткое резюме. Последняя строка описания должна заканчиваться точкой (`.`).
`sourceType`	Строка	Имя класса источника, который внес вклад в это свойство. Например, если свойство было из класса, аннотированного как `@ConfigurationProperties`, этот атрибут будет содержать полное квалифицированное имя этого класса. Если тип источника неизвестен, он может быть опущен.
`defaultValue`	Объект	Значение по умолчанию, которое используется, если свойство не указано. Если тип свойства — массив, он может быть массивом значений. Если значение по умолчанию неизвестно, оно может быть опущено.
`deprecation`	Устаревание	Указывает, устарело ли свойство. Если поле не устарело или эта информация неизвестна, оно может быть опущено. В следующей таблице приводится более подробная информация об атрибуте `deprecation`.

name

Строка

Полное имя свойства. Имена имеют формат, разделенный точкой в нижнем регистре (например, server.address). Этот атрибут является обязательным.

type

Строка

Полная сигнатура типа данных свойства (например, java.lang.String) а также полный тип дженерика (например, java.util.Map<java.lang.String,com.example.MyEnum>). Вы можете использовать этот атрибут, чтобы направить пользователя на типы значений, которые он может ввести. Для согласованности, тип примитива определяется с помощью его обертки (например, boolean преобразуется в java.lang.Boolean). Обратите внимание, что этот класс может быть сложным типом, который преобразуется из String, когда значения привязываются. Если тип неизвестен, он может быть опущен.

description

Строка

Краткое описание свойства, которое может отображаться пользователям. Если описание недоступно, оно может быть опущено. Рекомендуется, чтобы описания были короткими абзацами, при этом первая строка предоставляла краткое резюме. Последняя строка описания должна заканчиваться точкой (.).

sourceType

Строка

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

defaultValue

Объект

Значение по умолчанию, которое используется, если свойство не указано. Если тип свойства — массив, он может быть массивом значений. Если значение по умолчанию неизвестно, оно может быть опущено.

deprecation

Устаревание

Указывает, устарело ли свойство. Если поле не устарело или эта информация неизвестна, оно может быть опущено. В следующей таблице приводится более подробная информация об атрибуте deprecation.

Объект JSON, содержащийся в атрибуте deprecation каждого элемента properties, может содержать следующие атрибуты:

Имя Тип Назначение

Имя	Тип	Назначение
`level`	Строка	Уровень устаревания, который может быть либо `warning` (по умолчанию), либо `error`. Когда у свойства уровень устаревания `warning`, оно всё ещё должно быть связано в среде. Однако, когда у него уровень устаревания `error`, свойство больше не управляется и не связывается.
`reason`	Строка	Краткое описание причины устаревания свойства. Если причина недоступна, она может быть опущена. Рекомендуется, чтобы описания были короткими абзацами, при этом первая строка предоставляла краткое резюме. Последняя строка описания должна заканчиваться точкой (`.`).
`replacement`	Строка	Полное имя свойства, которое заменяет это устаревшее свойство. Если для этого свойства нет замены, оно может быть опущено.

level

Строка

Уровень устаревания, который может быть либо warning (по умолчанию), либо error. Когда у свойства уровень устаревания warning, оно всё ещё должно быть связано в среде. Однако, когда у него уровень устаревания error, свойство больше не управляется и не связывается.

reason

Строка

Краткое описание причины устаревания свойства. Если причина недоступна, она может быть опущена. Рекомендуется, чтобы описания были короткими абзацами, при этом первая строка предоставляла краткое резюме. Последняя строка описания должна заканчиваться точкой (.).

replacement

Строка

Полное имя свойства, которое заменяет это устаревшее свойство. Если для этого свойства нет замены, оно может быть опущено.

До Spring Boot 1.3 вместо элемента deprecation можно было использовать единственный булевый атрибут deprecated. Это всё ещё поддерживается устаревшим способом и больше не должно использоваться. Если причина и замена недоступны, должен быть задан пустой объект deprecation.

Устаревание также можно указать декларативно в коде, добавив аннотацию @DeprecatedConfigurationProperty к методу-геттеру, раскрывающему устаревшее свойство. Например, предположим, что свойство my.app.target было запутанным и переименовано в my.app.name. Следующий пример показывает, как обработать эту ситуацию:

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.DeprecatedConfigurationProperty;

@ConfigurationProperties("my.app")
public class MyProperties {

    private String name;

    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @Deprecated
    @DeprecatedConfigurationProperty(replacement = "my.app.name")
    public String getTarget() {
        return this.name;
    }

    @Deprecated
    public void setTarget(String target) {
        this.name = target;
    }

}

Нет способа установить level. warning всегда предполагается, так как код всё ещё обрабатывает свойство.

Предыдущий код гарантирует, что устаревшее свойство всё ещё работает (передавая управление свойству name за кулисами). После того, как методы getTarget и setTarget можно будет удалить из вашего публичного API, подсказка об автоматическом устаревании в метаданных также исчезнет. Если вы хотите сохранить подсказку, добавление метаданных вручную с уровнем устаревания error гарантирует, что пользователи всё ещё будут проинформированы об этом свойстве. Это особенно полезно, когда предоставляется replacement.

1.3. Подсказки атрибутов

Объект JSON, содержащийся в массиве hints, может содержать атрибуты, показанные в следующей таблице:

Имя Тип Назначение

Имя	Тип	Назначение
`name`	Строка	Полное имя свойства, к которому относится данная подсказка. Имена имеют вид нижнего регистра, разделенного точками (например, `spring.mvc.servlet.path`). Если свойство относится к карте (например, `system.contexts`), подсказка применяется либо к ключам карты (`system.contexts.keys`), либо к значениям (`system.contexts.values`) карты. Этот атрибут является обязательным.
`values`	ValueHint[]	Список допустимых значений, определенных объектом `ValueHint` (описан в следующей таблице). Каждая запись определяет значение и может иметь описание.
`providers`	ValueProvider[]	Список поставщиков, определенных объектом `ValueProvider` (описан позднее в этом документе). Каждая запись определяет имя поставщика и его параметры, если таковые имеются.

name

Строка

Полное имя свойства, к которому относится данная подсказка. Имена имеют вид нижнего регистра, разделенного точками (например, spring.mvc.servlet.path). Если свойство относится к карте (например, system.contexts), подсказка применяется либо к ключам карты (system.contexts.keys), либо к значениям (system.contexts.values) карты. Этот атрибут является обязательным.

values

ValueHint[]

Список допустимых значений, определенных объектом ValueHint (описан в следующей таблице). Каждая запись определяет значение и может иметь описание.

providers

ValueProvider[]

Список поставщиков, определенных объектом ValueProvider (описан позднее в этом документе). Каждая запись определяет имя поставщика и его параметры, если таковые имеются.

Объект JSON, содержащийся в атрибуте values каждого элемента hint, может содержать атрибуты, описанные в следующей таблице:

Имя Тип Назначение

Имя	Тип	Назначение
`value`	Объект	Допустимое значение для элемента, к которому относится подсказка. Если тип свойства — массив, это также может быть массив значений. Этот атрибут является обязательным.
`description`	Строка	Краткое описание значения, которое может быть отображено пользователю. Если описание отсутствует, его можно опустить. Рекомендуется, чтобы описания были короткими абзацами, причём первая строка предоставляла краткое резюме. Последняя строка описания должна заканчиваться точкой (`.`).

value

Объект

Допустимое значение для элемента, к которому относится подсказка. Если тип свойства — массив, это также может быть массив значений. Этот атрибут является обязательным.

description

Строка

Краткое описание значения, которое может быть отображено пользователю. Если описание отсутствует, его можно опустить. Рекомендуется, чтобы описания были короткими абзацами, причём первая строка предоставляла краткое резюме. Последняя строка описания должна заканчиваться точкой (.).

Объект JSON, содержащийся в атрибуте providers каждого элемента hint, может содержать атрибуты, описанные в следующей таблице:

Имя Тип Назначение

Имя	Тип	Назначение
`name`	Строка	Имя поставщика, который будет использоваться для предоставления дополнительной помощи по конфигурации элемента, к которому относится подсказка.
`parameters`	Объект JSON	Любые дополнительные параметры, поддерживаемые поставщиком (см. документацию поставщика для получения более подробной информации).

name

Строка

Имя поставщика, который будет использоваться для предоставления дополнительной помощи по конфигурации элемента, к которому относится подсказка.

parameters

Объект JSON

Любые дополнительные параметры, поддерживаемые поставщиком (см. документацию поставщика для получения более подробной информации).

1.4. Повторные элементы метаданных

Объекты с одинаковым именем «свойство» и «группа» могут появляться несколько раз в файле метаданных. Например, вы можете привязать два отдельных класса к одному префиксу, каждый из которых может иметь потенциально перекрывающиеся имена свойств. Хотя одинаковые имена, появляющиеся в метаданных несколько раз, не должны быть распространёнными, потребители метаданных должны позаботиться о том, чтобы они поддерживали такую ситуацию.

2. Предоставление ручных подсказок

Для улучшения пользовательского интерфейса и дополнительной помощи пользователю при конфигурации заданного свойства, можно предоставить дополнительные метаданные, которые:

Описывают список возможных значений для свойства.
Связывают поставщика для привязки чёткого семантического значения к свойству, чтобы инструмент мог определить список возможных значений на основе контекста проекта.

2.1. Подсказка значения

Атрибут name каждой подсказки относится к name свойства. В приведённом ранее примере мы предоставляем пять значений для свойства spring.jpa.hibernate.ddl-auto: none, validate, update, create и create-drop. Каждое значение может также иметь описание.

Если ваше свойство имеет тип Map, вы можете предоставить подсказки как для ключей, так и для значений (но не для самой карты). Специальные суффиксы .keys и .values должны относиться к ключам и значениям соответственно.

Предположим, что my.contexts сопоставляет магические значения String с целым числом, как показано в следующем примере:

import java.util.Map;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("my")
public class MyProperties {

    private Map<String, Integer> contexts;

    // getters/setters ...

    public Map<String, Integer> getContexts() {
        return this.contexts;
    }

    public void setContexts(Map<String, Integer> contexts) {
        this.contexts = contexts;
    }

}

Магические значения (в этом примере) — sample1 и sample2. Для предоставления дополнительной помощи по конфигурации ключей вы можете добавить следующий JSON в ручные метаданные модуля:

{"hints": [
    {
        "name": "my.contexts.keys",
        "values": [
            {
                "value": "sample1"
            },
            {
                "value": "sample2"
            }
        ]
    }
]}

Мы рекомендуем использовать Enum для этих двух значений вместо этого. Если ваш IDE поддерживает это, это, безусловно, самый эффективный подход для автозаполнения.

2.2. Поставщики значений

Поставщики — мощный способ привязки семантики к свойству. В этом разделе мы определяем официальных поставщиков, которые вы можете использовать для собственных подсказок. Однако ваша любимая IDE может реализовывать некоторые из них или ни одного. Кроме того, в будущем она может предоставить свои собственные.

Поскольку это новая функция, поставщикам IDE необходимо разобраться, как она работает. Время внедрения естественно варьируется.

В следующей таблице представлен список поддерживаемых поставщиков:

Имя Описание

Имя	Описание
`any`	Разрешает предоставление любых дополнительных значений.
`class-reference`	Автозаполняет классы, доступные в проекте. Обычно ограничено базовым классом, указанным параметром `target`.
`handle-as`	Обрабатывает свойство так, как будто оно определено типом, указанным обязательным параметром `target`.
`logger-name`	Автозаполняет допустимые имена логгеров и группы логгеров. Как правило, можно автозаполнить имена пакетов и классов, доступных в текущем проекте, а также определённые группы.
`spring-bean-reference`	Автозаполняет доступные имена бинов в текущем проекте. Обычно ограничено базовым классом, указанным параметром `target`.
`spring-profile-name`	Автозаполняет доступные имена профилей Spring в проекте.

any

Разрешает предоставление любых дополнительных значений.

class-reference

Автозаполняет классы, доступные в проекте. Обычно ограничено базовым классом, указанным параметром target.

handle-as

Обрабатывает свойство так, как будто оно определено типом, указанным обязательным параметром target.

logger-name

Автозаполняет допустимые имена логгеров и группы логгеров. Как правило, можно автозаполнить имена пакетов и классов, доступных в текущем проекте, а также определённые группы.

spring-bean-reference

Автозаполняет доступные имена бинов в текущем проекте. Обычно ограничено базовым классом, указанным параметром target.

spring-profile-name

Автозаполняет доступные имена профилей Spring в проекте.

Только один поставщик может быть активным для данного свойства, но вы можете указать несколько поставщиков, если они все могут каким-либо образом обрабатывать свойство. Убедитесь, что наиболее мощный поставщик стоит первым, так как IDE должна использовать первый обработанный поставщик в разделе JSON. Если для данного свойства не поддерживается ни один поставщик, никакая специальная помощь при вводе не предоставляется.

2.2.1. Любое

Специальное значение поставщика any разрешает предоставление любых дополнительных значений. Если это поддерживается, должна применяться стандартная проверка значений на основе типа свойства.

Этот поставщик обычно используется, если у вас есть список значений, и любые дополнительные значения по-прежнему должны считаться допустимыми.

Следующий пример предлагает on и off в качестве значений автозаполнения для system.state:

{"hints": [
    {
        "name": "system.state",
        "values": [
            {
                "value": "on"
            },
            {
                "value": "off"
            }
        ],
        "providers": [
            {
                "name": "any"
            }
        ]
    }
]}

Обратите внимание, что в предыдущем примере также разрешено любое другое значение.

2.2.2. Ссылка на класс

Поставщик class-reference автоматически заполняет классы, доступные в проекте. Этот поставщик поддерживает следующие параметры:

Параметр Тип Значение по умолчанию Описание

Параметр	Тип	Значение по умолчанию	Описание
`target`	`String` (`Class`)	none	Полное имя класса, который должен быть присваиваемым выбранному значению. Обычно используется для фильтрации неподходящих классов. Обратите внимание, что эту информацию может предоставить сам тип, экспонировав класс с соответствующей верхней границей.
`concrete`	`boolean`	true	Указывает, следует ли рассматривать только конкретные классы как допустимые кандидаты.

target

String (Class)

none

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

concrete

boolean

true

Указывает, следует ли рассматривать только конкретные классы как допустимые кандидаты.

Следующий фрагмент метаданных соответствует стандартному свойству server.servlet.jsp.class-name, которое определяет имя класса JspServlet для использования:

{"hints": [
    {
        "name": "server.servlet.jsp.class-name",
        "providers": [
            {
                "name": "class-reference",
                "parameters": {
                    "target": "jakarta.servlet.http.HttpServlet"
                }
            }
        ]
    }
]}

2.2.3. Обработать как

Поставщик handle-as позволяет заменить тип свойства на более высокий уровень. Это обычно происходит, когда свойство имеет тип java.lang.String, потому что вы не хотите, чтобы ваши классы конфигурации зависели от классов, которые могут отсутствовать в пути к классу. Этот поставщик поддерживает следующие параметры:

Параметр Тип Значение по умолчанию Описание

Параметр	Тип	Значение по умолчанию	Описание
`target`	`String` (`Class`)	none	Полное имя типа для рассмотрения для свойства. Этот параметр обязателен.

target

String (Class)

none

Полное имя типа для рассмотрения для свойства. Этот параметр обязателен.

Следующие типы могут быть использованы:

Любой java.lang.Enum: Перечисляет возможные значения для свойства. (Мы рекомендуем определить свойство с типом Enum, так как для автозаполнения значений IDE не должны потребоваться дополнительные подсказки)
java.nio.charset.Charset: Поддерживает автозаполнение значений кодировки (таких как UTF-8).
java.util.Locale: автозаполнение локали (таких как en_US).
org.springframework.util.MimeType: Поддерживает автозаполнение значений типа содержимого (таких как text/plain).
org.springframework.core.io.Resource: Поддерживает автозаполнение абстракции ресурсов Spring для ссылки на файл в файловой системе или в пути к классу (таких как classpath:/sample.properties).

Если могут быть предоставлены несколько значений, используйте тип Collection или Array, чтобы рассказать IDE об этом.

Следующий фрагмент метаданных соответствует стандартному свойству spring.liquibase.change-log, которое определяет путь к журналу изменений для использования. Он фактически используется внутри как org.springframework.core.io.Resource, но не может быть экспонирован как таковой, так как нам необходимо сохранить исходное строковое значение для передачи его API Liquibase.

{"hints": [
    {
        "name": "spring.liquibase.change-log",
        "providers": [
            {
                "name": "handle-as",
                "parameters": {
                    "target": "org.springframework.core.io.Resource"
                }
            }
        ]
    }
]}

2.2.4. Имя логгера

Поставщик logger-name автоматически заполняет допустимые имена логгеров и группы логгеров. Обычно можно автозаполнить имена пакетов и классов, доступные в текущем проекте. Если включены группы (по умолчанию) и в конфигурации указана пользовательская группа логгеров, должно быть обеспечено автозаполнение для неё. Также отдельные фреймворки могут иметь дополнительные магические имена логгеров, которые можно поддерживать.

Этот поставщик поддерживает следующие параметры:

Параметр Тип Значение по умолчанию Описание

Параметр	Тип	Значение по умолчанию	Описание
`group`	`boolean`	`true`	Указать, следует ли учитывать известные группы.

group

boolean

true

Указать, следует ли учитывать известные группы.

Поскольку имя логгера может быть любым произвольным именем, этот поставщик должен допускать любое значение, но может выделять допустимые имена пакетов и классов, которые недоступны в классе проекта.

Следующий фрагмент метаданных соответствует стандартному свойству logging.level. Ключи — это имена логгеров, а значения соответствуют стандартным уровням журналов или любым настраиваемым уровням. Поскольку Spring Boot определяет несколько групп логгеров по умолчанию, были добавлены отдельные подсказки значений для этих групп.

{"hints": [
    {
        "name": "logging.level.keys",
        "values": [
            {
                "value": "root",
                "description": "Root logger used to assign the default logging level."
            },
            {
                "value": "sql",
                "description": "SQL logging group including Hibernate SQL logger."
            },
            {
                "value": "web",
                "description": "Web logging group including codecs."
            }
        ],
        "providers": [
            {
                "name": "logger-name"
            }
        ]
    },
    {
        "name": "logging.level.values",
        "values": [
            {
                "value": "trace"
            },
            {
                "value": "debug"
            },
            {
                "value": "info"
            },
            {
                "value": "warn"
            },
            {
                "value": "error"
            },
            {
                "value": "fatal"
            },
            {
                "value": "off"
            }

        ],
        "providers": [
            {
                "name": "any"
            }
        ]
    }
]}

2.2.5. Ссылка на компонент Spring

Поставщик spring-bean-reference автоматически заполняет компоненты, определённые в конфигурации текущего проекта. Этот поставщик поддерживает следующие параметры:

Параметр Тип Значение по умолчанию Описание

Параметр	Тип	Значение по умолчанию	Описание
`target`	`String` (`Class`)	none	Полное имя класса компонента, который должен быть присваиваемым кандидату. Обычно используется для фильтрации неподходящих компонентов.

target

String (Class)

none

Полное имя класса компонента, который должен быть присваиваемым кандидату. Обычно используется для фильтрации неподходящих компонентов.

Следующий фрагмент метаданных соответствует стандартному свойству spring.jmx.server, которое определяет имя компонента MBeanServer для использования:

{"hints": [
    {
        "name": "spring.jmx.server",
        "providers": [
            {
                "name": "spring-bean-reference",
                "parameters": {
                    "target": "javax.management.MBeanServer"
                }
            }
        ]
    }
]}

Binder не осведомлён о метаданных. Если вы предоставили эту подсказку, вам всё равно нужно преобразовать имя компонента в фактическую ссылку на компонент с помощью ApplicationContext.

2.2.6. Имя профиля Spring

Поставщик spring-profile-name автоматически заполняет профили Spring, которые определены в конфигурации текущего проекта.

Следующий фрагмент метаданных соответствует стандартному свойству spring.profiles.active, которое определяет имя(а) профиля Spring для включения:

{"hints": [
    {
        "name": "spring.profiles.active",
        "providers": [
            {
                "name": "spring-profile-name"
            }
        ]
    }
]}

3. Генерация собственных метаданных с помощью процессора аннотаций

Вы можете легко сгенерировать собственный файл метаданных конфигурации из элементов, аннотированных с помощью @ConfigurationProperties, используя jar-файл spring-boot-configuration-processor. Jar-файл включает процессор аннотаций Java, который вызывается при компиляции вашего проекта.

3.1. Настройка процессора аннотаций

Для использования процессора добавьте зависимость от spring-boot-configuration-processor.

В Maven зависимость должна быть объявлена как необязательная, как показано в следующем примере:

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

В Gradle зависимость должна быть объявлена в конфигурации annotationProcessor, как показано в следующем примере:

dependencies {
    annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
}

Если вы используете файл additional-spring-configuration-metadata.json, задача compileJava должна быть настроена для зависимости от задачи processResources, как показано в следующем примере:

tasks.named('compileJava') {
    inputs.files(tasks.named('processResources'))
}

Эта зависимость гарантирует, что дополнительные метаданные будут доступны во время выполнения процессора аннотаций во время компиляции.

Если вы используете AspectJ в своём проекте, вам нужно убедиться, что процессор аннотаций запускается только один раз. Существует несколько способов сделать это. В Maven вы можете явно настроить maven-apt-plugin и добавить зависимость от процессора аннотаций только туда. Вы также можете позволить плагину AspectJ выполнить всю обработку и отключить обработку аннотаций в конфигурации maven-compiler-plugin, как показано ниже:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <proc>none</proc>
    </configuration>
</plugin>

Если вы используете Lombok в своём проекте, вам нужно убедиться, что его процессор аннотаций выполняется до spring-boot-configuration-processor. Для этого в Maven вы можете указать процессоры аннотаций в нужном порядке, используя атрибут annotationProcessors плагина компилятора Maven. Если вы не используете этот атрибут, и процессоры аннотаций обнаруживаются по зависимостям, доступным в пути к классам, убедитесь, что зависимость lombok определена до зависимости spring-boot-configuration-processor.

3.2. Автоматическая генерация метаданных

Процессор обнаруживает как классы, так и методы, аннотированные с помощью @ConfigurationProperties.

Если у класса есть единственный параметризованный конструктор, то создаётся по одному свойству на каждый параметр конструктора, если только конструктор не аннотирован с помощью @Autowired. Если у класса есть конструктор, явно аннотированный с помощью @ConstructorBinding, то создаётся по одному свойству на каждый параметр конструктора для этого конструктора. В противном случае свойства обнаруживаются по наличию стандартных геттеров и сеттеров со специальной обработкой типов коллекций и карт (это обнаруживается даже если присутствует только геттер). Процессор аннотаций также поддерживает использование аннотаций Lombok @Data, @Value, @Getter, и @Setter.

Рассмотрим следующий пример:

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "my.server")
public class MyServerProperties {

    /**
     * Name of the server.
     */
    private String name;

    /**
     * IP address to listen to.
     */
    private String ip = "127.0.0.1";

    /**
     * Port to listener to.
     */
    private int port = 9797;

    // getters/setters ...

    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getIp() {
        return this.ip;
    }

    public void setIp(String ip) {
        this.ip = ip;
    }

    public int getPort() {
        return this.port;
    }

    public void setPort(int port) {
        this.port = port;
    }
    // fold:off

Это экспонирует три свойства, где my.server.name не имеет значения по умолчанию, а my.server.ip и my.server.port имеют значения по умолчанию "127.0.0.1" и 9797 соответственно. Javadoc для полей используется для заполнения атрибута description. Например, описание my.server.ip — "IP-адрес для прослушивания.".

Вы должны использовать только обычный текст в Javadoc для поля @ConfigurationProperties, так как они не обрабатываются перед добавлением в JSON.

Процессор аннотаций применяет ряд эвристик для извлечения значения по умолчанию из исходной модели. Значения по умолчанию должны быть предоставлены статически. В частности, не следует ссылаться на константу, определённую в другом классе. Кроме того, процессор аннотаций не может автоматически обнаружить значения по умолчанию для Enum и Collections.

В случаях, когда значение по умолчанию не может быть обнаружено, необходимо предоставить ручные метаданные. Рассмотрим следующий пример:

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "my.messaging")
public class MyMessagingProperties {

    private List<String> addresses = new ArrayList<>(Arrays.asList("a", "b"));

    private ContainerType containerType = ContainerType.SIMPLE;

    // getters/setters ...

    public List<String> getAddresses() {
        return this.addresses;
    }

    public void setAddresses(List<String> addresses) {
        this.addresses = addresses;
    }

    public ContainerType getContainerType() {
        return this.containerType;
    }

    public void setContainerType(ContainerType containerType) {
        this.containerType = containerType;
    }

    public enum ContainerType {

        SIMPLE, DIRECT

    }

}

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

{"properties": [
    {
        "name": "my.messaging.addresses",
        "defaultValue": ["a", "b"]
    },
    {
        "name": "my.messaging.container-type",
        "defaultValue": "simple"
    }
]}

Требуется только name свойства для документирования дополнительных метаданных для существующих свойств.

3.2.1. Вложенные свойства

Процессор аннотаций автоматически рассматривает внутренние классы как вложенные свойства. Вместо документирования ip и port в корне пространства имён, мы можем создать подпространство для него. Рассмотрим обновлённый пример:

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "my.server")
public class MyServerProperties {

    private String name;

    private Host host;

    // getters/setters ...

    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Host getHost() {
        return this.host;
    }

    public void setHost(Host host) {
        this.host = host;
    }

    public static class Host {

        private String ip;

        private int port;

        // getters/setters ...

        public String getIp() {
            return this.ip;
        }

        public void setIp(String ip) {
            this.ip = ip;
        }

        public int getPort() {
            return this.port;
        }

        public void setPort(int port) {
            this.port = port;
        }

    }

}

Представленный пример генерирует метаданные для свойств my.server.name, my.server.host.ip, и my.server.host.port. Вы можете использовать аннотацию @NestedConfigurationProperty на поле, чтобы указать, что обычный (не вложенный) класс должен обрабатываться как вложенный.

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

3.3. Добавление дополнительных метаданных

Обработка файлов конфигурации Spring Boot довольно гибкая, и часто бывает, что свойства могут существовать, которые не привязаны к объекту @ConfigurationProperties bean. Вам также может потребоваться настроить некоторые атрибуты существующего ключа. Чтобы поддержать такие случаи и позволить вам предоставить пользовательские «подсказки», процессор аннотаций автоматически объединяет элементы из META-INF/additional-spring-configuration-metadata.json в основной файл метаданных.

Если вы ссылаетесь на свойство, которое было обнаружено автоматически, описание, значение по умолчанию и информация о устаревании переопределяются, если указаны. Если объявление свойства вручную не идентифицируется в текущем модуле, оно добавляется как новое свойство.

Формат файла additional-spring-configuration-metadata.json точно такой же, как у обычного файла spring-configuration-metadata.json . Дополнительный файл свойств является необязательным. Если у вас нет дополнительных свойств, не добавляйте файл.