Цель

Вспомогательная функция настройки автоматического запроса может ускорить запись конфигурации и значительно повысить точность.

JAR-файл springboot содержит файлы метаданных, в которых содержатся сведения обо всех поддерживаемых свойствах конфигурации. Цель файла — позволить разработчикам IDE использоватьapplication.propertiesилиapplication.ymlПредоставляет контекстную справку и завершение кода при документировании.

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

Версия

Ссылаться наSpringBoot 2.2.0.RELEASEДокументация

документ

в упаковке баночкиMETA-INF/spring-configuration-metadata.json(генерируется автоматически) илиMETA-INF/additional-spring-configuration-metadata.json(добавить вручную)

настоящий бой

<!-- 引入相关依赖 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-configuration-processor</artifactId>
  <optional>true</optional>
</dependency>

@Configuration
@ConfigurationProperties(prefix = "file.upload")
public class FileUploadConfig {
  /** Maximum number of bytes per file */
  private String maxSize = "1024M";

  /** 不允许的文件后缀 */
  private String rejectSuffix;
  //注意：使用的时候必须要有getter/setter，否则不会自动生成该属性对应的提示
  //此处因为篇幅原因省略 getter/setter
}

@Configuration
@ConfigurationProperties("map.test")
public class MapTestConfig {
  /** 测试Map类型数据的提示 */
  private Map<String, Object> data;
  //注意：使用的时候必须要有getter/setter，否则不会自动生成该属性对应的提示
  //此处因为篇幅原因省略 getter/setter
}

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

additional-spring-configuration-metadata.json

{
  "properties": [
    {
      "name": "file.upload.reject-suffix",
      "type": "java.lang.String",
      "defaultValue": "exe,jar",
      "description": "The file suffix is not allowed.",
      "sourceType": "com.lw.metadata.config.FileUploadConfig"
    },
    {
      "name": "map.test.data",
      "type": "java.util.Map",
      "description": "Tips for testing Map type data.",
      "sourceType": "com.lw.metadata.config.MapTestConfig"
    }
  ],
  "hints": [
    {
      "name": "map.test.data.keys",
      "values": [
        {
          "value": "name",
          "description": "The name of the person."
        },
        {
          "value": "sex",
          "description": "The sex of the person."
        }
      ]
    }
  ]
}

После компиляции maven сгенерированныйadditional-spring-configuration-metadata.jsonКак и в исходном коде, сгенерированныйspring-configuration-metadata.jsonследующее:

{
  "groups": [
    {
      "name": "file.upload",
      "type": "com.lw.metadata.config.FileUploadConfig",
      "sourceType": "com.lw.metadata.config.FileUploadConfig"
    },
    {
      "name": "map.test",
      "type": "com.lw.metadata.config.MapTestConfig",
      "sourceType": "com.lw.metadata.config.MapTestConfig"
    }
  ],
  "properties": [
    {
      "name": "file.upload.max-size",
      "type": "java.lang.String",
      "description": "Maximum number of bytes per file",
      "sourceType": "com.lw.metadata.config.FileUploadConfig",
      "defaultValue": "1024M"
    },
    {
      "name": "file.upload.reject-suffix",
      "type": "java.lang.String",
      "description": "The file suffix is not allowed.",
      "sourceType": "com.lw.metadata.config.FileUploadConfig",
      "defaultValue": "exe,jar"
    },
    {
      "name": "map.test.data",
      "type": "java.util.Map<java.lang.String,java.lang.Object>",
      "description": "Tips for testing Map type data.",
      "sourceType": "com.lw.metadata.config.MapTestConfig"
    }
  ],
  "hints": [
    {
      "name": "map.test.data.keys",
      "values": [
        {
          "value": "name",
          "description": "The name of the person."
        },
        {
          "value": "sex",
          "description": "The sex of the person."
        }
      ]
    }
  ]
}

Эффект

SpringBoot配置提示效果

Отсюда можно увидеть следующие явления:

Значение по умолчанию в коде будет автоматически сгенерировано в файл подсказки, например: FileUploadConfig#maxSize
Комментарии в коде автоматически генерируются в файле подсказки, например FileUploadConfig # maxsize
Подскажите в файле дополнительных пружинных конфигураций - Metadata.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."
                }
            ]
        }
    ]
}

groups

Группа, чтобы сгруппировать классы конфигурации.Вы можете группировать по файлам, то есть: поместить все свойства одного и того же файла конфигурации в одну группу

Атрибуты	тип	Это необходимо	использовать
name	String	Y	полное название группы
type	String	N	Имя класса сгруппированного типа данных (например: полное имя класса с аннотацией @ConfigurationProperties, тип возвращаемого значения метода с аннотацией @Bean)
description	String	N	сгруппированыкороткаяописывать.
sourceType	String	N	Предоставляет название класса источника группировки.
sourceMethod	String	N	Предоставляет методы для группировки, включая круглые скобки и типы параметров.

properties

Подскажите тему, обязательно

Атрибуты	тип	Это необходимо	использовать
name	String	Y	Полное название объекта. имя принятоСтрочные, разделенные периодамиформат, например:`server.address`
type	String	N	Полная подпись типа данных атрибута (например:`java.lang.String`) или полный универсальный тип (например:`java.util.Map`). Это свойство запрашивает у пользователя тип значения. Нативные типы используют здесь свои типы-оболочки (например:`boolean`использовать`java.lang.Boolean`).
description	String	N	сгруппированыкороткаяописывать.
sourceType	String	N	Предоставляет имя класса источника группировки.
defaultValue	Object	N	По умолчанию. Используется, когда указано свойство.
deprecation	Deprecation	N	Указывает, является ли свойство устаревшим.

Свойства устаревания следующие:

Атрибуты	тип	Это необходимо	использовать
level	String	N	уровень устаревания, который может быть`warning`(по умолчанию) или`error`.`warning`: свойства должны быть доступны;`error`: Имущество не гарантирует, что вы можете использовать
reason	String	N	Краткая причина устаревания атрибута.
replacement	String	N	Полное имя нового свойства, которое заменяет это устаревшее свойство.обнуляемый

Уведомление:До Spring Boot 1.3 использовался логический типdeprecated.

Следующий пример из официальной документации показывает, как справиться с этим сценарием:

`java

@ConfigurationProperties("app.acme")

public class AcmeProperties {

private String name;

public String getName() { ... }

public void setName(String name) { ... }

@DeprecatedConfigurationProperty(replacement = "app.acme.name")

@Deprecated

public String getTarget() {

return getName();

}

@Deprecated

public void setTarget(String target) {

setName(target);

}

}

`

однаждыgetTargetиsetTargetМетод удален из общедоступного API, а подсказка об автоматическом устаревании в метаданных исчезла. Если вы хотите оставить подсказку, добавьтеerrorРучные метаданные на уровне устаревания гарантируют, что пользователи по-прежнему знают об этом свойстве. Это особенно полезно при предложении альтернатив.

hints

Вспомогательные наконечники, не обязательные

Атрибуты	тип	Это необходимо	использовать
name	String	Y	提示关联的属性的完整名称。 имяточка в нижнем регистре с разделителемформат (например:`spring.mvc.servlet.path`), если свойство связано с типом карты (например:`system.contexts`), запрашивая ключи, которые можно связать с картой (`system.contexts.keys`) или значение (`system.contexts.values`).
values	ValueHint[]	N	Коллекция допустимых значений. (подробности в таблице ниже)
providers	ValueProvider[]	N	Сбор провайдера. (подробности в таблице ниже)

valuesСвойства следующие:

Атрибуты	тип	Это необходимо	использовать
value	Object	Y	Подсказка относится к допустимому значению элемента. Если свойство является массивом, значение и описание также могут быть массивами.
description	String	N	Краткое описание соответствующего значения

ValueHint

Карта для типов поддержки выглядит следующим образом:

@ConfigurationProperties("sample")
public class SampleProperties {

    private Map<String,Integer> contexts;
    // getters and setters
}

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

Подсказки — это подсказки для каждой пары ключ-значение на карте.

.keysи.valuesПрефикс должен быть связан с ключами и значениями Карты соответственно.

providersСвойства следующие:

Атрибуты	тип	Это необходимо	использовать
name	String	N	Имя поставщика, используемого для предоставления дополнительной помощи по содержимому для элемента, на который ссылается подсказка.
parameters	JSON object	N	Любые другие параметры, поддерживаемые провайдером (подробности см. в документации провайдера).

ValueProvider

* Обычно не используется, рекомендуется пропустить*

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

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

any

Все значения, соответствующие типу атрибута.

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

class-reference

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

параметр	тип	По умолчанию	описывать
target	Строка (класс)	никто	Полное имя класса для присвоения значению. Обычно используется для проверки классов, не являющихся кандидатами.
concrete	boolean	true	Указывает, следует ли рассматривать только конкретные классы в качестве допустимых кандидатов.

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

handle-as

Позволяет заменить тип свойства на более расширенный тип.

Обычно это делается в свойствах сjava.lang.Stringtype, потому что вы не хотите, чтобы ваши классы конфигурации зависели от классов, которые не находятся в пути к классам.

параметр	тип	По умолчанию		описывать
target	Строка (класс)	никто	Y	Полное имя типа, рассматриваемого для свойства.

Доступные значения следующие:

любойjava.lang.Enum: список возможных значений свойства.
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или тип массива

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

logger-name

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

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

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

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

Ниже приведеныlogging.levelАтрибуты. ключи — это имена логгеров, значения связаны со стандартными уровнями логов или пользовательскими уровнями,

{"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"
            }
        ]
    }
]}

spring-bean-reference

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

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

spring-profile-name

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

Следующий пример представляет:spring.profiles.activeИмя профиля, который может включать свойство.

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

Повторяющиеся элементы метаданных

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

Автоматически генерировать файлы подсказок

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

`xml

org.springframework.boot

spring-boot-configuration-processor

true

`

Процессор получает классы и методы, аннотированные @configurationproperties. Javadoc для значений полей в классе конфигурации используется для заполнения свойства описания.

Примечание. В поле @configurationproperties javadoc следует использовать только простой текст, поскольку они не будут обрабатываться, пока не будут добавлены в json.

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

Процессор аннотаций также поддерживает аннотации ломбока с использованием @data, @getter и @setter.

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

@ConfigurationProperties(prefix="acme.messaging")
public class MessagingProperties {

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

    private ContainerType = ContainerType.SIMPLE;

    // ... getter and setters

    public enum ContainerType {
        SIMPLE,
        DIRECT
    }
}

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

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

Примечание. Если вы используете AspectJ в своем проекте, вам необходимо убедиться, что обработчик аннотаций запускается только один раз. При использовании Maven вы можете явно настроитьmaven-apt-pluginplugin, и добавлять зависимости к обработчику аннотаций только туда. Также возможно, чтобы подключаемый модуль AspectJ работал на всех процессах обработки и вmaven-compiler-pluginизconfigurationОтключите обработку аннотаций в , как показано ниже:

`java

org.apache.maven.plugins

maven-compiler-plugin

none

`

привязать свойство

Процессор аннотаций автоматически обрабатывает внутренние классы как вложенные свойства.

@ConfigurationProperties(prefix="server")
public class ServerProperties {
    private String name;
    private Host host;
    // ... getter and setters
    public static class Host {
        private String ip;
        private int port;
        // ... getter and setters
    }
}

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

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

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

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

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

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

использованная литература

Советы по настройке Springboot Официальная документацияОбщедоступный номер: Yifeixi (сосредоточьтесь на знании домена Javaглубокое обучение, от исходного кода до принципа, систематического и упорядоченного обучения)

逸飞兮