Spring Boot: создание собственной автоконфигурации, создание собственного стартера

Полная версия Spring Boot для библиотеки может содержать следующие компоненты:

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

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

Именование

Вы должны убедиться, что предоставили правильное пространство имен для своего стартера. Не начинайте имена модулей со spring-boot, даже если вы используете другой Maven groupId. В будущем возможна официальная поддержка для вещи, которую вы автоматически настраиваете.

Как правило, вы должны назвать комбинированный модуль как стартер. Например, предположим, что вы создаете стартер для "acme" назовите модуль автоконфигурации acme-spring-boot-autoconfigure, а стартер acme-spring-boot-starter. Если у вас есть только один модуль, который объединяет оба, назовите его acme-spring-boot-starter.

Конфигурационные ключи

Если ваш стартер предоставляет конфигурационные ключи, используйте для них уникальное пространство имен. В частности, не включайте ваши ключи в пространства имен, которые использует Spring Boot (например, server, management, spring и т. д.). Если вы используете пространства имен Spring Boot, возможно изменение этих пространств имен в будущем таким образом, что это будет нарушать работу ваших модулей. Как правило, перед всеми вашими ключами добавьте пространство имен, которым вы владеете (например, acme).

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

@ConfigurationProperties("acme")
public class AcmeProperties {

    /**
     * Нужно ли проверять расположение ресурсов acme.
     */
    private boolean checkLocation = true;

    /**
     * Таймаут для установления соединения с сервером acme.
     */
    private Duration loginTimeout = Duration.ofSeconds(3);

    // getters & setters

}

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

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

Не начинайте описание с "The" или "A" (артиклей в английском языке, при описании на английском).
Для логических типов начните описание с "Whether" или "Enable".
Для основанных на коллекции типов, начните описание с "Comma-separated list"
Используйте java.time.Duration вместо long и опишите модуль по умолчанию, если он отличается от миллисекунд, например "Если суффикс продолжительности не указан, будут использованы секунды".
Не указывайте значение по умолчанию в описании, если оно не должно быть определено во время выполнения.

Обязательно запустите генерацию метаданных, чтобы помощь IDE была доступна и для ваших ключей. Вы можете просмотреть сгенерированные метаданные (META-INF/spring-configuration-metadata.json), чтобы убедиться, что ваши ключи правильно документированы. Использование собственного стартера в совместимой IDE также является хорошей идеей для проверки качества метаданных.

Модуль autoconfigure

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

Вы должны пометить зависимости от библиотеки как optional, чтобы вы могли легче включить модуль autoconfigure в свои проекты.

Spring Boot использует процессор аннотаций для сбора условий автоконфигурирования в файле метаданных (META-INF/spring-autoconfigure-metadata.properties). Если этот файл присутствует, он используется для активной фильтрации автоконфигураций, которые не совпадают, что улучшит время запуска. Рекомендуется добавить следующую зависимость в модуль, который содержит автоконфигурации:

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

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

dependencies {
    compileOnly "org.springframework.boot:spring-boot-autoconfigure-processor"
}

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

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

Модуль Starter

Стартер на самом деле пустой jar. Его единственная цель - предоставить необходимые зависимости для работы с библиотекой. Вы можете думать об этом как о рекомендуемом взгляде на то, что требуется, чтобы начать.

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

В любом случае, ваш стартер должен прямо или косвенно ссылаться на основной стартер Spring Boot (spring-boot-starter) (то есть нет необходимости добавлять его, если ваш стартер использует другой стартер). Если проект создается только с вашим пользовательским стартером, основные функции Spring Boot будут учитываться наличием основного стартера.

Поиск по этому блогу

Java Blog