03. Кастомные YAML-настройки стартера

Зачем это нужно: проблема «стартер со своими настройками»

Типичный сценарий: вы пишете библиотеку-стартер payment-gateway-starter, которую подключают другие команды. Стартеру нужны свои настройки — URL платёжного шлюза, таймауты, флаги поведения. Есть два варианта их доставки:

• Заставить потребителя всё описать руками — каждый интегратор копирует блок payment-gateway: из README в свой application.yml. Работает, но дублирование, ошибки копипаста и «а какие дефолты вообще разумные?» ложатся на потребителя.
• Положить в jar стартера свой YAML-файл (например, application-payment-gateway.yml) с разумными дефолтами и сделать так, чтобы он сам подхватывался в Environment приложения при старте — а потребитель переопределял бы только то, что ему нужно, в своём обычном application.yml.

# Внутри jar стартера: src/main/resources/application-payment-gateway.yml
# Дефолты, которые приложение получает "бесплатно" при подключении зависимости
payment-gateway:
  base-url: "https://api.payment-gw.example.com"
  connect-timeout: 2s
  read-timeout: 5s
  max-retries: 2
  idempotency-key-header: "X-Request-Id"

Базовое использование: spring.config.import

Начиная со Spring Boot 2.4 существует декларативный механизм импорта дополнительных конфигов — свойство spring.config.import. Потребитель добавляет одну строку, и файл из classpath (в том числе из чужого jar) попадает в общую систему конфигурации со всеми её возможностями — профили, плейсхолдеры, релаксед-биндинг:

# application.yml ПРИЛОЖЕНИЯ (потребителя стартера)
spring:
  config:
    import:
      - "classpath:application-payment-gateway.yml"   # из jar стартера
      - "optional:file:./local-overrides.yml"          # локальный файл, если есть

Ключевые свойства механизма:

Недостаток очевиден: строку всё равно должен написать потребитель. Если хочется «подключил зависимость — и ничего больше делать не надо», нужен следующий раздел.

Механика внутри: EnvironmentPostProcessor + YamlPropertySourceLoader

Это классический программный способ, которым сама экосистема Spring Boot решала эту задачу до появления spring.config.import (и которым до сих пор пользуются многие инфраструктурные стартеры). Он опирается на точку расширения жизненного цикла — EnvironmentPostProcessor: колбэк, который вызывается до создания контекста и всех бинов, когда уже собран объект Environment, но в него ещё можно дописывать PropertySource.

public class PaymentGatewayEnvironmentPostProcessor
        implements EnvironmentPostProcessor, Ordered {

    // Ресурс лежит в том же jar, что и этот класс
    private static final Resource DEFAULTS =
            new ClassPathResource("application-payment-gateway.yml");

    @Override
    public void postProcessEnvironment(ConfigurableEnvironment environment,
                                       SpringApplication application) {
        try {
            // Готовый парсер YAML из spring-boot: возвращает список
            // PropertySource — по одному на каждый документ (---) в файле
            YamlPropertySourceLoader loader = new YamlPropertySourceLoader();
            List<PropertySource<?>> sources =
                    loader.load("paymentGatewayDefaults", DEFAULTS);
            sources.forEach(environment.getPropertySources()::addLast);
        } catch (IOException e) {
            throw new IllegalStateException(
                "Не удалось загрузить дефолты payment-gateway-starter", e);
        }
    }

    @Override
    public int getOrder() {
        // После стандартного загрузчика application.yml,
        // чтобы наши дефолты гарантированно имели меньший приоритет
        return Ordered.LOWEST_PRECEDENCE;
    }
}

Регистрация — не через аннотацию и не через бин, а через service-файл в resources стартера:

# src/main/resources/META-INF/spring.factories (в jar стартера)
org.springframework.boot.env.EnvironmentPostProcessor=\
com.example.payment.starter.PaymentGatewayEnvironmentPostProcessor

Почему именно так, а не @Component:

1. EnvironmentPostProcessor вызывается до старта контекста — бины ещё не существуют, компонент-скан ничего не увидит. Spring находит реализации только сканированием META-INF/spring.factories на этапе подготовки Environment (механизм тот же, что и у автоконфигураций, но другой ключ).
2. Фаза выполнения — событие ApplicationEnvironmentPreparedEvent: SpringApplication.run() уже прочитал application.yml и переменные окружения (это делает встроенный ConfigDataEnvironmentPostProcessor), но контекст ещё не создан. Ваш постпроцессор просто дописывает источник в конец списка.

Обходной путь для @PropertySource: кастомная фабрика

Если по какой-то причине нужен именно @PropertySource (например, конфигурация используется и вне Spring Boot, в чистом Spring Framework), YAML можно прикрутить вручную — через собственную реализацию PropertySourceFactory, которая парсит файл тем же YamlPropertiesFactoryBean:

public class YamlPropertySourceFactory implements PropertySourceFactory {

    @Override
    public PropertySource<?> createPropertySource(String name,
                                                  EncodedResource resource) throws IOException {
        YamlPropertiesFactoryBean factory = new YamlPropertiesFactoryBean();
        factory.setResources(resource.getResource());
        Properties props = factory.getObject();
        return new PropertiesPropertySource(
                name != null ? name : resource.getResource().getFilename(),
                props);
    }
}

@Configuration
@PropertySource(
        value = "classpath:application-payment-gateway.yml",
        factory = YamlPropertySourceFactory.class)
class PaymentGatewayAutoConfiguration { }

Приоритеты: кто кого переопределяет

MutablePropertySources — упорядоченный список: чем раньше источник в списке, тем выше его приоритет при поиске свойства. От позиции добавления зависит, сможет ли приложение переопределить дефолты стартера:

// environment.getPropertySources() — упорядоченный список, поиск идёт сверху вниз
// addLast  → самый низкий приоритет: дефолты перекрываются всем, что объявлено в приложении
sources.addLast(propertySource);
// addFirst → самый высокий: стартер ПЕРЕБЬЁТ application.yml приложения (обычно не то, что нужно!)
sources.addFirst(propertySource);
// addBefore / addAfter относительно конкретного источника
sources.addBefore("applicationConfig: [classpath:/application.yml]", propertySource);

Для сценария «jar-дефолты + возможность переопределения» правильный порядок такой: дефолты стартера — addLast (низший приоритет). Тогда цепочка разрешения свойства выглядит так:

Привязка настроек к бинам стартера: @ConfigurationProperties

Подтянуть значения в Environment — полдела. Вторая часть — связать их с типизированным объектом конфигурации, который использует автоконфигурация стартера:

@ConfigurationProperties(prefix = "payment-gateway")
public class PaymentGatewayProperties {

    // Дубль дефолтов кодом — страховка, если YAML не подгрузился;
    // setter'ы позволяют переопределять из любого PropertySource
    private String baseUrl = "https://api.payment-gw.example.com";
    private Duration connectTimeout = Duration.ofSeconds(2);
    private Duration readTimeout = Duration.ofSeconds(5);
    private int maxRetries = 2;

    // геттеры и сеттеры ...
}

@AutoConfiguration
@EnableConfigurationProperties(PaymentGatewayProperties.class)
public class PaymentGatewayAutoConfiguration {

    @Bean
    PaymentGatewayClient paymentGatewayClient(PaymentGatewayProperties props) {
        return new DefaultPaymentGatewayClient(
            props.getBaseUrl(), props.getConnectTimeout(), props.getMaxRetries());
    }
}

Регистрация самой автоконфигурации — отдельный файл META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports (не путать с spring.factories для EnvironmentPostProcessor: у каждого механизма свой ключ и свой файл).

Продвинутые приёмы

Условная загрузка по флагу. Иногда дефолты должны применяться только при включённом стартере. Внутри EnvironmentPostProcessor можно читать уже загруженные свойства и ветвиться:

@Override
public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
    // enabled=true — дефолт из самого же файла стартера или из кода
    if (!env.getProperty("payment-gateway.enabled", Boolean.class, true)) {
        return; // стартер выключен — дефолты не добавляем
    }
    // ... загрузка YAML как выше
}

Программный аналог spring.config.import. Если хочется, чтобы потребитель не писал строку import вручную, но использовать spring.factories по каким-то причинам нельзя (например, несколько постпроцессоров конфликтуют по порядку), допустимо добавить источник-«импортёр»: EnvironmentPostProcessor, который читает список файлов из собственного ключа и грузит их все — фактически мини-реализация ConfigData-механизма. Делать это стоит только если готовых средств действительно мало; в остальных случаях проще EnvironmentPostProcessor напрямую.

Плейсхолдеры между источниками. Значения из YAML-дефолтов стартера могут ссылаться на свойства приложения — резолвинг происходит лениво, в момент запроса свойства, поэтому кросс-источниковые ссылки работают:

# в application-payment-gateway.yml (внутри jar стартера)
payment-gateway:
  base-url: "${external.gateway.url:https://api.payment-gw.example.com}"
  # сначала берётся external.gateway.url из приложения/env,
  # если его нет — значение после двоеточия

Сравнение способов

Когда применять, когда избегать

Применять YAML-дефолты в стартере стоит, когда:

• стартер — внутренняя платформенная библиотека, используемая многими сервисами, и у каждого сервиса была бы одинаковая «шапка» настроек;
• настройки имеют безопасные значения по умолчанию (таймауты, лимиты retry, имена хедеров), а переопределяется обычно 1–2 ключа;
• важен опыт «подключил зависимость — клиент заработал» (developer experience внутренних команд).

Избегать стоит, когда:

• значения обязаны задаваться явно (URL прода, секреты, ключи API) — «тихие» дефолты здесь опасны: сервис незаметно уйдёт на дефолтный URL вместо требуемого окружением;
• конфиг сильно зависит от окружения потребителя (разные схемы БД, разные облака) — дефолт всё равно будет перезаписан везде;
• вы планируете часто менять дефолты между версиями стартера: изменение значений в jar — невидимое для потребителя поведение-дрейф при обновлении зависимости; безопаснее держать дефолты в коде Properties-класса и менять их осознанно, а YAML оставить для документирования.

Как тестировать

Главный инструмент для тестов стартера — ApplicationContextRunner: он позволяет поднимать минимальный контекст с вашей автоконфигурацией и проверять эффект от разных наборов свойств, не стартуя целое приложение:

class PaymentGatewayDefaultsTest {

    // withInitializer прогоняет EnvironmentPostProcessor'ы так же,
    // как это делает настоящий SpringApplication.run()
    private final ApplicationContextRunner runner = new ApplicationContextRunner()
            .withInitializer(new ConfigDataApplicationContextInitializer())
            .withUserConfiguration(PaymentGatewayAutoConfiguration.class);

    @Test
    void defaultsFromStarterYamlAreApplied() {
        runner.run(context -> {
            assertThat(context.getEnvironment()
                    .getProperty("payment-gateway.max-retries", Integer.class))
                    .isEqualTo(2); // значение из jar стартера
        });
    }

    @Test
    void applicationCanOverrideStarterDefaults() {
        runner.withPropertyValues("payment-gateway.read-timeout=15s")
              .run(context -> {
                  PaymentGatewayProperties props =
                          context.getBean(PaymentGatewayProperties.class);
                  assertThat(props.getReadTimeout())
                          .isEqualTo(Duration.ofSeconds(15)); // приложение победило
              });
    }

    @Test
    void yamlDefaultsMatchJavaFieldDefaults() {
        // защита от расползания двух наборов дефолтов (см. info-box выше)
        runner.run(context -> {
            PaymentGatewayProperties fresh = new PaymentGatewayProperties();
            assertThat(context.getBean(PaymentGatewayProperties.class))
                    .usingRecursiveComparison().isEqualTo(fresh);
        });
    }
}