Namespaces, placeholders и defaults

1. Конфиг как “словарь” и структура ключей

Если смотреть на конфигурацию Spring Boot очень приземлённо, то она напоминает большую карту “ключ → значение”, где ключ — строка вроде app.catalog.title, а значение — например "Spring+ Catalog". Проблема начинается, когда ключи появляются “как попало”: сегодня title, завтра catalogTitle, послезавтра mainTitle, а потом вы уже не уверены, что именно вы меняете. Spring Boot не запрещает этот хаос — он просто честно считает, что вы взрослый человек и сами себе хозяин. Поэтому наша задача — сделать хаос невозможным по привычке.

Базовый application.yaml у нас уже есть, и следующая проблема теперь не “куда положить настройки”, а “как не превратить файл в свалку из title, mode и limit без структуры”.

Представим конфиг как обычную Map<String, String> в Java. Это не “как внутри Spring”, но как модель для мозга — отлично работает:

import java.util.HashMap;
import java.util.Map;

// Представляем конфиг как "ключ → значение" (упрощённая модель для понимания)
Map<String, String> props = new HashMap<>();

// Хороший ключ: с понятным namespace, чтобы не было двусмысленности
props.put("app.catalog.title", "Spring+ Catalog");

// Читаем значение строго по полному ключу
System.out.println(props.get("app.catalog.title")); // Spring+ Catalog

Теперь представьте, что вы положили туда просто title без префикса:

import java.util.HashMap;
import java.util.Map;

// Ключи в такой "карте" глобальные — и легко наступить на свои же грабли
Map<String, String> props = new HashMap<>();

props.put("title", "Spring+ Catalog");

// Второй put по тому же ключу перезатирает первое значение
props.put("title", "Oops, another title");

System.out.println(props.get("title")); // Oops, another title

Да, пример слегка нарочно “в лоб”, но смысл такой: ключи глобальные, и если вы не вводите структуру, вы сами себе устраиваете квест “угадай, какой title сейчас главный”.

Именно поэтому Spring Boot‑приложения обычно используют “пространства имён” через префиксы: spring.*, server.*, logging.*, и (для пользовательских настроек) что‑то вроде app.*. Это не “формальность”, а способ сделать конфигурацию читаемой, предсказуемой и расширяемой.

2. Namespaced properties и стиль ключей

Когда вы пишете свой конфиг, вам очень хочется сделать так:

title: "Spring+ Catalog"
maxFeaturedCount: 4
maintenanceMode: false

Первые 15 минут это кажется гениально простым. Потом проект растёт, появляется второй “title” (например, title для landing page, title для логов, title для каких‑то метаданных), и внезапно выясняется, что “простота” была просто отсутствием структуры.

В catalog-service мы заранее фиксируем: все пользовательские настройки каталога живут под префиксом app.catalog. Тогда даже без комментариев понятно, что это наши ключи (не Spring) и что они относятся именно к модулю каталога.

Вот “плохая” форма (не делайте так в проекте, даже если очень хочется):

spring:
  application:
    name: catalog-service

# Плохой сигнал: ключи в корне "висят в воздухе" — непонятно, к чему они относятся
title: "Spring+ Catalog"
max-featured-count: 4
startup-report-enabled: true

Смотрится как будто нормально, но title вообще непонятно чей. Заголовок чего? Каталога? Приложения? Окна браузера? Человек, который откроет этот файл через неделю (и этим человеком будете вы), будет гадать.

А вот “хорошая” форма — уже как контракт:

spring:
  application:
    name: catalog-service

app:
  catalog:
    # Явный namespace: сразу видно, что это настройки именно каталога
    title: "Spring+ Catalog"
    max-featured-count: 4
    startup-report-enabled: true

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

Префикс должен отражать предметную область, а не случайную фантазию. Если вы напишете my.cool.super.config.title, будет… весело, но не очень полезно. app.catalog.* — коротко, понятно, и не конфликтует с самим Spring.

Kebab-case в ключах

Есть редкий случай, когда дефисы действительно делают жизнь лучше, а не добавляют боли: это имена конфигурационных ключей. В Spring Boot почти вся документация и большинство встроенных свойств используют kebab-case: server.port, spring.application.name, spring.jackson.*, и так далее. Если вы для своих ключей выбираете тот же стиль, вы снижаете шанс “нарваться” на смесь стилей в одном файле.

В catalog-service мы держимся простого правила: ключи внутри YAML — lowercase + дефисы, то есть kebab-case. Получается так:

app:
  catalog:
    # kebab-case: нижний регистр + дефисы, чтобы не плодить "зоопарк" вариантов
    maintenance-mode: false
    max-featured-count: 4
    default-published-only: true

Если написать maxFeaturedCount, YAML это проглотит, Spring Boot это тоже, скорее всего, проглотит на этапе чтения как “строку”, но дальше у вас начнутся мелкие раздражающие проблемы: вы то пишете maxFeaturedCount, то max-featured-count, то пытаетесь “угадывать” правильный вариант. И да, такие мелочи — главный источник багов “на ровном месте”, которые потом выглядят как “Spring не читает мой конфиг” (хотя Spring просто читает не тот ключ, который вы имели в виду).

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

3. Placeholder ${...} и переиспользование значений

Как только вы сделали конфиг структурным, возникает вторая типичная проблема: дублирование. И оно коварнее, чем кажется. Потому что пока вы дублируете значение два раза — всё “работает”. А потом вы меняете одно место и забываете второе, и у вас начинается классическая история “почему баннер говорит одно, а заголовок другое”.

В Spring Boot есть штатный механизм “подстановки значения в значение” — placeholder ${...}. Это буквально: “возьми значение такого-то ключа и вставь сюда”.

Например, вы хотите завести дружелюбное текстовое сообщение, которое использует имя приложения из spring.application.name:

spring:
  application:
    name: catalog-service

app:
  catalog:
    # Placeholder: подставляем значение spring.application.name внутрь строки
    banner: "Welcome to ${spring.application.name}"

Теперь если вы поменяете spring.application.name, баннер тоже поменяется, без ручной синхронизации. Это не “магия”, это просто подстановка строк.

Placeholder можно вставлять не только как “всё значение целиком”, но и как часть строки:

spring:
  application:
    name: catalog-service

app:
  catalog:
    title: "Spring+ Catalog"
    # Собираем banner из двух источников: заголовок + имя приложения
    banner: "${app.catalog.title} (${spring.application.name})"

Здесь banner аккуратно собирается из двух источников: человекочитаемого title и технического spring.application.name. В реальном проекте это часто полезно для логов и диагностических сообщений (не потому что “так надо”, а потому что так потом проще понять, что вообще запущено).

Если держать это в голове как маленький конвейер, картина становится очень понятной:

flowchart LR
  A["spring.application.name"] --> C["app.catalog.banner"]
  B["app.catalog.title"] --> C["app.catalog.banner"]

Важно помнить: placeholder — это ссылка на значение, а не “код”. Он не делает вычислений, не умеет “сложить числа”, не “превратит строку в дату”. Это плюс: меньше неожиданностей. И минус: сложную логику не надо пытаться запихнуть в placeholders — у вас получится конфиг‑ребус.

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

4. Defaults ${name:default} и границы использования

Placeholder ${key} хорош, пока key точно существует. Но жизнь любит подкидывать ситуации “ключ забыли”, “ключ переименовали”, “ключ не обязателен”. Чтобы приложение не падало от каждого отсутствующего значения, в placeholders есть механизм значения по умолчанию: ${name:default}. Он читается так: “возьми name, а если его нет — используй default”.

Самый простой пример выглядит так:

app:
  catalog:
    # Если runtime-mode не задан, берём "standard" (важно: двоеточие → лучше в кавычках)
    mode-label: "${app.catalog.runtime-mode:standard}"

Если app.catalog.runtime-mode где-то определён — берём его. Если нет — используем standard. И обратите внимание на кавычки: из-за : внутри строки это просто более безопасный вариант записи в YAML.

Defaults особенно полезны для “мягких” настроек, которые не ломают приложение. Например, для подписи, декоративного флага, или для какого-то поведения, которое имеет очевидный безопасный режим.

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

То есть default — это не “как избежать ошибок”, а “как выбрать поведение при отсутствии значения”. Это разные вещи.

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

app:
  catalog:
    # Здесь runtime-mode обязан прийти извне; иначе Boot честно остановит старт
    mode-label: "${app.catalog.runtime-mode}"

Если app.catalog.runtime-mode нигде не задан и default не указан, Spring Boot обычно упадёт на старте с ошибкой “не могу разрешить placeholder”. Это fail-fast, и для обязательных вещей он полезен.

А вот более осмысленный пример defaults: вы хотите хранить базовый лимит featured‑курсов в одном месте и при этом иметь безопасное запасное значение, если этот узел конфигурации вообще не задан.

app:
  catalog:
    defaults:
      max-featured-count: 6

    max-featured-count: "${app.catalog.defaults.max-featured-count:4}"

Если app.catalog.defaults.max-featured-count задан — он выигрывает. Если нет — используем 4. Такой паттерн помогает не копировать цифры по файлу. Да, тут появляется дополнительный узел defaults, но он как раз и служит “одним местом, где лежат дефолты”. Это учебный фрагмент поверх уже знакомого app.catalog.*, а не обязательная новая структура всего проекта.

Ещё одна фишка: default может сам быть placeholder‑ом. Это удобно, когда у вас есть “более общий” ключ и “более специфичный”, и специфичный должен унаследовать общий, если не задан.

app:
  defaults:
    title: "Catalog Platform"

  catalog:
    display-title: "${app.catalog.title:${app.defaults.title}}"

Читается так: если есть app.catalog.title, берём его; иначе берём app.defaults.title. Это аккуратно и не превращает конфиг в копипасту, но всё ещё остаётся читаемым. Главное — не строить из этого “три этажа вложенности” ради одной строки. И это тоже локальный pattern, а не новый обязательный контракт catalog-service.

5. Конфиг-контракт для catalog-service

К этому месту у нас уже есть базовый application.yaml из предыдущей лекции: spring.application.name и набор app.catalog.*. Здесь важно не собрать второй параллельный контракт проекта, а увидеть, как placeholders и defaults живут поверх уже знакомых ключей.

Самый естественный derived-key для catalog-service — служебный banner, собранный из уже существующих значений:

app:
  catalog:
    banner: "${app.catalog.title} (${spring.application.name})"

Это локальный фрагмент поверх базового файла: title и spring.application.name остаются там же, где и были, а banner просто переиспользует их без копипасты.

Если нужен мягкий default, добавляйте отдельный derived-key или локальный узел defaults только там, где он реально убирает копипасту. Но базовые project-level ключи app.catalog.title, maintenance-mode, max-featured-count, default-published-only и startup-report-enabled остаются теми же, что мы уже завели. Placeholders и defaults не заменяют этот baseline, а помогают наращивать его без копипасты.

6. Типичные ошибки при namespacing, placeholders и defaults

В этом месте обычно возникает ощущение “ну всё, я понял: надо везде ставить ${...} и всё будет красиво”. И вот тут как раз стоит притормозить. Placeholders и defaults — это хороший инструмент, но он может стать источником путаницы, если использовать его без меры.

Ошибка №1: “префикс ради префикса”, без смысла предметной области.
Иногда люди придумывают префиксы, которые ничего не объясняют: my.settings.*, custom.props.*, project.*. Через месяц это не помогает ни читать, ни искать. Хороший namespace отвечает на вопрос “к чему это относится”: app.catalog.* — к каталогу, app.* — к приложению в целом. Если префикс нельзя объяснить одной фразой, значит он, скорее всего, плохой.

Ошибка №2: смешивание стилей ключей в одном файле.
Когда рядом встречаются maxFeaturedCount, max-featured-count, max_featured_count и MaxFeaturedCount, мозг начинает тратить силы не на понимание приложения, а на “как тут вообще принято”. Самый простой способ это предотвратить — договориться о kebab-case для YAML‑ключей и держаться этого как привычки.

Ошибка №3: placeholders превращаются в “головоломку” из цепочек.
${a:${b:${c:${d:42}}}} — это уже не конфигурация, а ребус. Да, технически оно может работать, но человек будет читать это как шифр. Если вы видите, что placeholder‑логика становится слишком хитрой, обычно это сигнал, что вы пытаетесь запихнуть в конфиг “программирование”, а конфиг для этого не предназначен.

Ошибка №4: default ставится на обязательные значения “чтобы не падало”.
Это очень человеческое желание: пусть как-нибудь стартует. Но оно приводит к самым неприятным багам — тихим. Если title обязателен, пусть приложение падает и говорит об этом честно. Defaults хороши для мягких настроек, но плохо подходят для тех частей, без которых ваша логика теряет смысл.

Ошибка №5: ${name:default} пишут без кавычек и потом ловят странные YAML‑ошибки.
YAML чувствителен к символам, а двоеточие — это вообще “служебный” символ формата. Иногда запись без кавычек действительно сработает, а иногда вы получите ошибку парсинга или неожиданную трактовку значения. Если в строке есть ${...:...}, самый спокойный и предсказуемый вариант — просто взять значение в кавычки и не играть в “угадай, как YAML прочитает это сегодня”.