application.yaml как конфиг проекта

1. Выбор application.yaml

Когда приложение ещё живёт только в IDE и запускается вами одним человеком, легко думать: «да ладно, пусть пока будет константа в коде». Но Spring Boot как платформа создавался для того, чтобы одна и та же кодовая база могла запускаться с разными настройками без переписывания классов. Поэтому конфигурационный файл — не украшение, а базовая часть архитектуры.

Как только мы перестали считать такие значения частью классов, сразу возникает практический вопрос: где им теперь жить. В Boot-проекте таким базовым домом и становится application.yaml.

Spring Boot умеет работать и с application.properties, и с application.yaml. Проблема не в том, что один формат “правильный”, а другой “плохой”. Проблема в том, что если у вас одновременно два равноправных формата, вы быстро получаете два источника правды и странные вопросы уровня «почему приложение ведёт себя не так, как я только что настроил». На уровне курса мы фиксируем один основной формат, чтобы не тренировать хаос как навык.

Ещё один практический мотив — читаемость. В catalog-service у нас неизбежно появятся вложенные настройки: блок “настройки каталога”, внутри него флаги поведения, лимиты, возможно, подписи. YAML показывает такую структуру глазами, как дерево, а не как длинную цепочку точек.

2. Расположение application.yaml

На этом этапе нам не нужно держать в голове всю магию “property sources” и приоритетов. Пока достаточно простого и полезного правила: базовый конфигурационный файл проекта кладём в src/main/resources. Spring Boot автоматически подхватывает ресурсы из classpath и ищет там стандартные имена конфигов, одно из которых — application.yaml.

Именно src/main/resources — это “папка для файлов, которые должны попасть в приложение как ресурсы”. Туда же у нас уже попала welcome-страница static/index.html, и туда же логично положить настройки. При сборке проекта ресурсы поедут вместе с приложением, и оно сможет стартовать в одинаковом виде хоть у вас, хоть у коллеги, хоть на другом компьютере.

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

Файл: src/main/resources/application.yaml

spring:
  application:
    # Техническое имя приложения (часто всплывает в логах/метриках)
    name: catalog-service

Boot не просит вас регистрировать этот файл, не требует аннотаций, не заставляет писать код “загрузчика YAML”. Он просто читает его на старте, если файл лежит где положено и называется как ожидается.

3. YAML как дерево и ключи Spring Boot

YAML часто пугает новичков не потому, что он сложный, а потому, что он чувствительный к отступам. Но если принять простую модель “YAML — это дерево”, всё становится намного спокойнее. Каждый уровень вложенности задаётся отступами, и эта вложенность потом превращается в обычные property-ключи через точки.

Представьте, что YAML — это не текст, а папки на диске: если вы “положили файл” не в ту папку (не в тот отступ), то он окажется совсем в другом месте. Spring Boot читает YAML-дерево и разворачивает его в плоские ключи вида a.b.c.

Например:

Файл: src/main/resources/application.yaml

app:
  catalog:
    # Человеческое название каталога (например, для UI/логов)
    title: "Spring+ Catalog"
    # Лимит: сколько элементов можно показать в "featured"
    max-featured-count: 4

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

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

Чтобы почувствовать “отступ = смысл”, полезно сравнить два YAML-фрагмента. Первый корректный:

app:
  catalog:
    title: "Spring+ Catalog"
    max-featured-count: 4

А вот этот уже другой по смыслу, даже если выглядит почти так же:

app:
  catalog:
    title: "Spring+ Catalog"
  # Важно: этот ключ теперь НЕ внутри catalog, а на уровне app
  max-featured-count: 4

Во втором варианте max-featured-count относится не к catalog, а к app. И Boot будет видеть ключ app.max-featured-count, а не app.catalog.max-featured-count. Ошибка не всегда будет “красной” и очевидной — иногда приложение просто начнёт вести себя странно, и вы будете минут десять подозревать Spring, потом Jackson, потом ретроградный Меркурий… а виноват окажется один пробел.

4. YAML vs .properties

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

При этом нужно помнить: YAML — это не “другой мир”. Это просто другой способ записать те же ключи. Чтобы это закрепить, давайте возьмём один и тот же кусок конфигурации и запишем его двумя способами.

Вариант на YAML:

Файл: src/main/resources/application.yaml

spring:
  application:
    # Имя приложения (идентификатор сервиса)
    name: catalog-service

app:
  catalog:
    # Заголовок каталога (любой читабельный текст)
    title: "Spring+ Catalog"
    # Максимум элементов в "избранном" блоке
    max-featured-count: 4

Ровно то же самое на .properties:

Файл: src/main/resources/application.properties

# Имя приложения (то же самое, что и spring.application.name в YAML)
spring.application.name=catalog-service

# Пользовательские настройки приложения
app.catalog.title=Spring+ Catalog
app.catalog.max-featured-count=4

Если конфиг маленький, .properties выглядит вполне нормально. Но как только появляются, например, “подписи” или группы настроек, YAML становится заметно дружелюбнее глазу:

app:
  catalog:
    labels:
      # Подпись для "featured" в интерфейсе/ответах
      featured: "Featured"
      # Подпись для "archived" в интерфейсе/ответах
      archived: "Archived"

И вот тут .properties уже начинает выглядеть как заклинание:

# Те же подписи, но уже в виде "цепочки" ключей
app.catalog.labels.featured=Featured
app.catalog.labels.archived=Archived

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

5. Стартовый application.yaml для catalog-service

Сейчас нам нужно сделать очень практичную вещь: зафиксировать базовый конфигурационный файл, который уже выглядит как контракт нашего сервиса. Мы ещё не читаем эти значения в коде (это будет позже в рамках дня), но мы готовим “дом” для настроек: сначала — стандартные Spring-настройки, затем — пользовательские настройки приложения.

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

Вот хороший стартовый шаблон (обратите внимание, что мы используем kebab-case в названиях ключей — это просто стиль записи с дефисами, он хорошо читается):

Файл: src/main/resources/application.yaml

spring:
  application:
    # Идентификатор сервиса
    name: catalog-service

app:
  catalog:
    # Публичный заголовок/название каталога
    title: "Spring+ Catalog"
    # Флаг техобслуживания (если включить — дальше можно будет менять поведение сервиса)
    maintenance-mode: false
    # Ограничение для "featured" элементов
    max-featured-count: 4
    # По умолчанию показываем только опубликованные
    default-published-only: true
    # Включаем/выключаем стартовый отчёт (например, логирование настроек на старте)
    startup-report-enabled: true

Здесь мы видим две “зоны ответственности”. Блок spring.* — это то, что относится к инфраструктуре Spring Boot. Блок app.* — это наши прикладные настройки. Такой порядок — не “обязательное правило Spring”, а простая гигиена: любой, кто откроет файл, сразу поймёт, где framework, а где ваш сервис.

Это базовый вариант файла, от которого дальше и пляшем. Новые фрагменты будут либо уточнять уже знакомый app.catalog.*, либо накладывать локальные патчи поверх него, а не изобретать другой набор ключей с нуля.

6. Минимальная YAML-гигиена

YAML — формат дружелюбный, но он требует дисциплины. Не дисциплины уровня “я теперь взрослый и серьёзный инженер”, а дисциплины уровня “я хочу, чтобы через неделю этот файл можно было открыть без боли”. Самые частые проблемы в YAML связаны не со Spring Boot, а с тем, что YAML чувствителен к пробелам и некоторым символам.

Главное правило: используйте пробелы (обычно 2 пробела на уровень вложенности) и не используйте табы. Второе правило: если строка содержит что-то подозрительное (например, двоеточие : или #), лучше взять её в кавычки и спать спокойно. Третье правило: не пытайтесь “умничать” с форматами — мы здесь не пишем YAML-роман, мы описываем настройки.

Пара примеров, которые часто спасают время:

Строка с # без кавычек может неожиданно превратиться в комментарий:

app:
  catalog:
    # Здесь "#1" будет воспринято как комментарий, а не как часть значения
    title: Spring+ Catalog #1

Это будет прочитано как title = "Spring+ Catalog", а #1 станет комментарием. Если вам реально нужен # в значении, берите в кавычки:

app:
  catalog:
    # В кавычках # становится обычным символом строки
    title: "Spring+ Catalog #1"

С булевыми значениями тоже полезно быть аккуратным. true и false — это булевы значения, а "true" и "false" — строки. Иногда вам всё равно, но лучше не размазывать типы “как придётся”, иначе потом сложно объяснять, почему что-то не связалось туда, куда ожидалось.

И ещё одно: комментарии в YAML начинаются с #, и это вполне нормальный способ оставить пояснение. Но старайтесь писать комментарии так, чтобы они не дублировали очевидное. Комментарий “это title” рядом с title: обычно не делает жизнь лучше.

7. Проверка загрузки application.yaml

Новичку часто хочется “потрогать руками”: а Spring Boot точно прочитал мой YAML, или он просто красиво лежит на диске и грустит? Хорошая новость: даже без специального кода файл участвует в старте приложения. Плохая новость: “успешное чтение” не всегда видно отдельной строкой в логах. Поэтому проверка чаще всего делается через простую логику: если YAML сломан, приложение обычно падает на старте.

Самый честный способ проверить, что файл вообще на месте и корректно парсится — запустить приложение обычным способом. Если application.yaml содержит синтаксическую ошибку (неправильный отступ, забыли двоеточие, таб вместо пробелов), Spring Boot, как правило, не будет молчать. Он устроит вам “аттракцион” с stacktrace, где будет видно, что YAML не распарсился.

Например, такой фрагмент YAML со сломанным отступом:

app:
  catalog:
    title: "Spring+ Catalog"
   # Ошибка: этот ключ сдвинут на 1 пробел влево, структура ломается
   max-featured-count: 4

Очень похоже на нормальный, да? Но один лишний пробел слева ломает структуру. Результат обычно выглядит примерно так: приложение не стартует, а в логах появится ошибка парсинга YAML (часто от SnakeYAML) с указанием строки/колонки. И это, на самом деле, полезно: лучше упасть сразу и громко, чем тихо “не применить настройку” и потом час искать, почему фича не работает.

Если же файл корректный, приложение стартует как обычно — и это уже хороший знак: конфигурация хотя бы читается. На этом месте нам и нужен фундамент: файл на classpath, валидный синтаксис и понятные ключи. Когда эти ключи начнут попадать в реальные beans, тот же YAML уже станет частью поведения сервиса, а не просто аккуратным файлом в resources.

8. Типичные ошибки при работе с application.yaml

Переход на YAML почти всегда начинается с ощущения “ну что там сложного, это же просто текст”. И почти всегда продолжается тем, что один невидимый пробел заставляет вас смотреть на stacktrace, как на древнюю карту сокровищ. Ниже — самые частые грабли, которые встречаются в Boot-проектах у начинающих.

Ошибка №1: файл лежит не в src/main/resources.
Очень распространённый сценарий: вы создали application.yaml, но положили его в src/main/java или рядом с build.gradle.kts, потому что “так удобнее”. Spring Boot по умолчанию ищет конфиги на classpath, а src/main/resources — это стандартная папка, которая туда попадает. Поэтому файл “рядом с кодом” может просто не оказаться в итоговом приложении.

Ошибка №2: смешали application.yaml и application.properties и забыли, что они оба читаются.
Иногда начинающий делает так: в YAML прописал одно значение, в properties случайно осталось другое (или IDE сгенерировала). Потом начинается магия: “я же поменял, почему не поменялось?”. Не потому что Boot плохой, а потому что у вас два места, где можно задать одно и то же. На уровне курса мы держимся одного основного формата, чтобы не плодить загадки.

Ошибка №3: табы вместо пробелов и пляшущие отступы.
YAML — это не формат “где пробелы для красоты”. Отступы задают структуру данных. Таб в YAML часто воспринимается как ошибка, а “чуть-чуть не тот отступ” может превратить настройку из app.catalog.* в app.*. В результате приложение не падает, но и ваша настройка “как будто игнорируется”.

Ошибка №4: забыли кавычки там, где они нужны.
Если в значении есть #, YAML начинает думать, что дальше комментарий. Если в строке есть двоеточие или какие-то “подозрительные” символы, YAML может распарсить это не так, как вы ожидаете. Для строковых значений, которые являются “названиями/подписями”, кавычки — хороший способ убрать двусмысленность и не спорить с парсером.

Ошибка №5: попытались сделать YAML “слишком умным” раньше времени.
Иногда хочется сразу использовать все возможности YAML: якоря, сложные структуры, хитрые сокращения. Но учебный проект выигрывает не от хитрости, а от читаемости. Если ваш application.yaml нельзя быстро понять глазами, он начинает работать против вас: любой следующий шаг в обучении становится тяжелее, потому что вы тратите силы на расшифровку конфигурации, а не на понимание Spring Boot.