optional: и политика старта

1. Отсутствие файла как политика

Когда начинаешь работать с внешней конфигурацией, очень легко попасть в режим «ну, иногда файлов нет — и ладно». А потом внезапно оказывается, что приложение запустилось в «полурабочем» состоянии: порт не тот, флаги не те, данных нет, а в логах тишина. В Spring Boot отсутствие конфигурационного ресурса — это сигнал, по которому вы выбираете стратегию: строго валить старт (fail-fast) или разрешать мягкий запуск (tolerant startup).

Представьте, что конфигурация — это инструкции для сборки мебели. Если вы потеряли страницу с тем, как прикручивать ножки, то «мягкий старт» означает собрать шкаф без ножек и радостно сказать: «Готово!». Вряд ли вы будете довольны результатом, когда попробуете поставить туда чашки. С другой стороны, если вы потеряли «декоративную наклейку 3×3 мм», то падать с ошибкой тоже странно. Вот это и есть выбор политики.

В Spring Boot 4 идея проста: если вы явно сказали «подключи вот этот файл/каталог», то Boot по умолчанию воспринимает это как обязательное требование. Если ресурс не найден — это почти всегда ошибка, и старт должен прерываться. Но у нас есть механизм, который позволяет сказать: «это подключение необязательное, если не найдёшь — просто пропусти». Этот механизм называется optional:.

2. Поведение по умолчанию

Теперь чуть ближе к практике. Есть два типа ситуаций, где появляется «файл не найден».

Первая — вы используете spring.config.import и указываете конкретную локацию: classpath:... или file:.... Если Boot не может найти этот ресурс, он обычно прерывает старт. Это логично: вы сами добавили явную зависимость конфигурации от файла.

Вторая — вы управляете поиском конфигурации через spring.config.location или расширяете его через spring.config.additional-location. Там та же логика: если вы сказали «ищи конфиг ещё вот тут», и там ничего нет, для Boot это может быть признаком того, что вы ошиблись путём или забыли положить файлы. И снова: по умолчанию лучше остановиться и заставить человека исправить ситуацию, чем запустить сервис «как-нибудь».

Важно уловить философию: Spring Boot старается быть предсказуемым. Он скорее выберет «не стартовать совсем», чем «стартовать непонятно как» — потому что вторая ситуация очень плохо диагностируется. Приложение “живое”, порт открыт, но всё поведение не то — и вы тратите час на гадание.

Именно поэтому optional: — не «косметика», а рычаг, который меняет строгость старта. Он должен использоваться осознанно, иначе вы можете сами себе организовать “тихий режим ошибок”.

3. optional: что делает и чего не делает

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

Давайте сразу уберём три популярных иллюзии.

Первая иллюзия: «optional: снижает приоритет конфигурации». Нет. Если файл существует и подхватился, он участвует в конфигурации как обычно. Приоритеты (кто кого переопределяет) зависят от механизма (import, additional-location, порядок), а optional: на это не влияет.

Вторая иллюзия: «optional: лечит кривой YAML». Тоже нет. Если файл существует, но внутри синтаксическая ошибка YAML, битая кодировка или просто невалидная структура, приложение упадёт. optional: защищает только от ситуации “ресурс отсутствует”, а не от ситуации “ресурс есть, но плохой”.

Третья иллюзия: «optional: меняет способ вычисления пути». Не меняет. Фиксированный путь остаётся фиксированным (file:... / classpath:...), относительный остаётся относительным, директория остаётся директорией. optional: — это чисто реакция на отсутствие.

Чтобы зафиксировать это в голове, удобно представить маленький алгоритм:

flowchart TD
    %% `optional:` влияет только на реакцию на отсутствие ресурса
    A["Boot пытается загрузить конфиг по локации"] --> B{"Ресурс существует?"}
    B -->|Да| C["Читает файл/директорию и добавляет свойства"]
    B -->|Нет| D{"Есть префикс optional: ?"}
    D -->|Да| E["Пропускает локацию и продолжает старт"]
    D -->|Нет| F["Падает на старте (fail-fast)"]

Эта схема намеренно простая. В реальности Boot ещё делает кучу шагов вокруг профилей и слоёв, но смысл optional: именно такой.

4. optional: в spring.config.import: «подключи, если найдёшь»

Когда мы делали декомпозицию конфигурации через spring.config.import, мы фактически сказали: «прочитай application.yaml, а потом подцепи ещё вот этот документ». Это удобно для модульной структуры, но сразу рождает вопрос: импортируемый файл должен быть обязательным или нет?

С обязательными импортами всё просто: если файл — часть базовой конфигурационной модели приложения, без него сервис не имеет смысла, тогда лучше падать сразу. Например, если мы вынесли список курсов в classpath:catalog-data.yaml, то в нашем проекте catalog-service это часть артефакта. Если этого файла нет, значит сборка сломана, jar неполный, или кто-то «почистил ресурсы». Такой старт лучше валить, а не пытаться работать «без каталога».

Пример обязательного импорта:

# src/main/resources/application.yaml
spring:
  config:
    # Обязательный импорт: если файла нет в classpath, это почти всегда ошибка сборки
    import: "classpath:catalog-data.yaml"

Теперь про необязательные импорты. Типичный сценарий — локальные/внешние переопределения, которые могут существовать, а могут не существовать. Мы как раз хотим, чтобы разработчик мог создать файл в ./config/, но если он этого не сделал — приложение всё равно стартовало.

Пример:

# src/main/resources/application.yaml
spring:
  config:
    # Необязательный импорт: если файла рядом нет — просто пропускаем слой
    import: "optional:file:./config/catalog-extra.yaml"

Здесь важная тонкость: это не “дополнительная директория”, это конкретный файл. Если он есть — он будет прочитан, и его свойства войдут в итоговую конфигурацию. Если его нет — Boot просто пойдёт дальше.

Очень практичный микро-кейс для catalog-service: вы можете локально переопределить заголовок приложения, не трогая application-local.yaml и не коммитя локальные изменения в репозиторий.

Например, у вас в base-конфиге:

# src/main/resources/application.yaml
app:
  catalog:
    # Базовое значение (будет использовано, если нет внешнего override-слоя)
    title: "Spring+ Catalog"

А в ./config/catalog-extra.yaml (если вы его создали локально):

# ./config/catalog-extra.yaml
app:
  catalog:
    # Локальный override: применяется только если файл существует и был импортирован
    title: "Spring+ Catalog (Ivan's laptop edition)"

Если файл существует — заголовок станет “Ivan’s laptop edition”. Если файла нет — останется базовый. Никакой магии, просто дополнительный слой.

5. optional: и spring.config.location

Мы уже обсуждали, что spring.config.location и spring.config.additional-location отвечают не на вопрос «что импортировать», а на вопрос «где вообще искать конфигурацию». И есть ещё одна методическая важность: эти свойства читаются очень рано, поэтому чаще всего их задают снаружи, а не внутри application.yaml. Иначе вы пытаетесь изменить правила поиска файла… из самого файла, который ещё надо найти. Получается конфигурационный “квест”.

И здесь optional: тоже работает. Если вы добавляете внешнюю директорию, которая может отсутствовать (например, в чистом клоне репозитория), вы почти всегда хотите пометить её как optional — иначе у каждого новичка будет “красный старт” на ровном месте.

Пример мягкого расширения стандартного поиска:

# Добавляем внешнюю папку как "ещё один слой поиска", не ломая старт при её отсутствии
./gradlew bootRun --args="--spring.config.additional-location=optional:file:./config/"

Смысл такой: «если рядом есть папка ./config/, попробуй найти там стандартные application*.yaml и применить их как внешний override-слой; если папки нет — не ломай старт».

Если вы вместо additional-location используете location, то вы заменяете стандартный поиск. Тут optional становится ещё важнее, потому что вы можете случайно “отрубить” packaged config и остаться без конфигурации вообще.

Например:

# Важно: location ЗАМЕНЯЕТ стандартные места поиска, поэтому это очень "острая" настройка
./gradlew bootRun --args="--spring.config.location=optional:file:./custom-config/"

Если директории нет — не упадём, да. Но есть ловушка: вы заменили стандартный поиск на (потенциально пустую) директорию. В таком запуске вы можете неожиданно стартовать вообще с дефолтами и без привычных application.yaml из ресурсов. Это уже не просто «мягкий старт», а «мягкий старт в неизвестность». Поэтому spring.config.location обычно используют аккуратно и редко, а optional: там — не повод расслабляться.

6. Fail-fast vs tolerant startup: как выбрать строгость

Выбор между fail-fast и мягким стартом не сводится к “строгость хорошо” или “строгость плохо”. Это про то, насколько вам важно, чтобы приложение не могло стартовать без конкретного слоя конфигурации.

Ниже — небольшая таблица, которая помогает принять решение без гадания:

В реальной жизни хорошее правило для junior-проекта звучит почти грубо: если вы сомневаетесь — не ставьте optional:. Потому что отсутствие файла — это редкая ситуация, а “тихий неправильный старт” — очень частая боль.

И ещё один важный момент: мягкий старт имеет смысл только тогда, когда у вас есть разумные значения по умолчанию или другие источники, которые гарантированно дадут корректную конфигурацию. Иначе optional: превращается в кнопку “игнорировать проблему”.

Как применить это в catalog-service

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

application.yaml внутри src/main/resources — это базовая рамка. Она должна существовать всегда, иначе сервис просто не является тем, чем мы его описали. Там живут spring.application.name, общие флаги, и декларации import для модульной конфигурации. Это не место для optional: — это “скелет”.

catalog-data.yaml (внутри ресурсов) — это большие данные каталога, которые мы вынесли, чтобы не превращать application.yaml в свалку. Этот файл обычно тоже должен быть обязательным, потому что без него наш read-only сервис каталога теряет смысл. Если вы запустили catalog-service и он «вроде живой», но список курсов пустой, то в учебном проекте это почти всегда ошибка, а не допустимый режим.

А вот ./config/catalog-extra.yaml — внешняя добавка. Это хороший кандидат на optional:. Его роль — не “сделать приложение работоспособным”, а “дать возможность переопределить поведение без правки jar и без коммита локальных изменений”. Если файла нет — нормально. Если есть — тоже нормально.

Пример хорошей схемы, где optional выглядит уместно:

# src/main/resources/application.yaml
spring:
  application:
    name: catalog-service
  config:
    # Сначала обязателен data-слой (часть артефакта), затем опциональный внешний override
    import: "classpath:catalog-data.yaml,optional:file:./config/catalog-extra.yaml"

app:
  catalog:
    # Значения по умолчанию (должны быть разумными, иначе optional превращается в "игнорировать проблему")
    title: "Spring+ Catalog"
    max-featured-count: 4

Здесь всё объяснимо словами. “У нас есть базовый конфиг. К нему всегда подцепляется data-файл. И, если рядом лежит внешний оверрайд — он может поменять отдельные значения”.

7. Быстрая диагностика optional-слоя

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

Пока мы ещё не ушли в типобезопасную конфигурацию, можно делать это через Environment в нашем StartupSummaryRunner. Минимальный пример:

import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.core.env.Environment;
import org.springframework.stereotype.Component;

@Component
class StartupSummaryRunner implements ApplicationRunner {

    private final Environment env;

    StartupSummaryRunner(Environment env) {
        this.env = env;
    }

    @Override
    public void run(ApplicationArguments args) {
        // Берём значение из итогового Environment (с учётом всех слоёв: base, import, optional-override и т.д.)
        String title = env.getProperty("app.catalog.title");

        // Быстрая диагностика: видим, какое значение реально получилось после наложения конфигурации
        System.out.println("app.catalog.title = " + title); // app.catalog.title = Spring+ Catalog
    }
}

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

Сценарий A: файла ./config/catalog-extra.yaml нет. Тогда вывод будет базовый.

Сценарий B: вы создаёте ./config/catalog-extra.yaml и переопределяете app.catalog.title. Тогда вывод изменится. И вы сразу видите, что optional-слой реально подключился, без гаданий “кажется, Boot должен был…”.

И вот здесь появляется взрослая мысль: optional: полезен, но диагностика нужна всегда. Если вы не можете легко проверить, применился слой или нет, вы превращаете конфигурацию в гадание по кофейной гуще. А кофе жалко.

8. Типичные ошибки при использовании optional:

Ошибка №1: делать обязательный слой конфигурации optional “чтобы не падало”.
Такое решение выглядит как быстрый прогресс: приложение стартует, все довольны. Но через некоторое время вы ловите самую неприятную категорию багов — “оно запустилось, но ведёт себя странно”. Если файл реально обязателен для корректной работы (данные каталога, критичные флаги окружения), fail-fast будет не жестокостью, а заботой о вашем времени.

Ошибка №2: превращать optional: в универсальный пластырь и помечать необязательным вообще всё подряд.
Когда optional-локаций становится много, у вас исчезает чёткая граница между “приложение стартовало правильно” и “приложение стартовало случайно”. В итоге вы уже не можете устно объяснить, почему получилось именно это значение свойства. А если схему нельзя объяснить словами, она обычно становится очень дорогой в поддержке.

Ошибка №3: думать, что optional: влияет на приоритеты и “делает файл слабее”.
Это распространённая ментальная ловушка: будто optional-файл — это какой-то “fallback” с низким приоритетом. На самом деле optional: не меняет ни порядок наложения слоёв, ни правило “кто кого переопределяет”. Он меняет только реакцию на отсутствие. Если файл нашёлся — он участвует в конфигурации как обычный слой и вполне может переопределить базовые значения.

Ошибка №4: ожидать, что optional: спасёт от кривого YAML или неправильного формата.
optional: — не “try/catch вокруг парсинга”. Если файл существует, но в нём ошибка, Boot упадёт (и это правильно: иначе вы получите запуск с частично прочитанной конфигурацией). Поэтому optional подходит для “файла может не быть”, но не подходит для “файл есть, но мы не уверены, что он валиден”.

Ошибка №5: использовать optional: как способ спрятать непонятные ошибки.
Иногда разработчик видит, что Boot ругается на не найденный ресурс, и вместо того чтобы разобраться с путём или моделью слоёв, просто добавляет optional:. Это может “починить красный старт”, но сломает архитектурную ясность. Лучше честно решить: этот ресурс обязателен (тогда исправляем путь/упаковку) или он действительно необязателен (тогда optional оправдан).