Шпаргалка по YAML: скрытые грабли и как их обходить

YAML кажется простым, пока не наткнёшься на «магические» значения, отступы и странные преобразования типов. Ниже — короткая, практичная статья с примерами, как не наступать на грабли в реальных конфигах (Ansible, Kubernetes, CI/CD).

1) Булевы ловушки: yes/no, on/off

Многие «человеческие» слова YAML превращает в true/false. Это часто ломает логику.

# Плохо
enabled: yes # станет true
mode: on # станет true
answer: No # станет false 

# Хорошо
enabled: true
mode: "on" # строка
answer: "No" # строка 

Совет: для логики — true/false; для текстов — берите в кавычки.

2) Ведущие нули: 01, 08, 09

Числа с нулями в начале могут парситься как восьмеричные (или вызвать ошибку).

# Плохо
port: 080
user_id: 0123

# Хорошо
port: "080" # именно строка "080"
user_id: 123 # число 

Правило: числа — без ведущих нулей; форматированный код — строка.

3) Даты vs строки

Запись вида 2025-08-16 может распознаться как дата, хотя ожидалась строка.

# Плохо
version: 2025-08-16

# Хорошо
version: "2025-08-16" 

Если это не дата — заключайте в кавычки.

4) Отступы: только пробелы

Табы в YAML запрещены. Любая смесь табов и пробелов ломает структуру.

# Плохо
items:
\t- a
\t- b

# Хорошо
items:
  - a
  - b

Базовый стандарт: 2 пробела на уровень.

5) Анкоры и алиасы: DRY без хаоса

Анкоры (&) объявляют блок, алиасы (*) ссылаются на него. Удобно для общих настроек. Будьте аккуратны с merge-ключом «.

Пример:

defaults: &def
  image: nginx:latest
  resources:
    limits:
      cpu: "500m"

web:
  <<: *def
  replicas: 2

api:
  <<: *def
  image: nginx:stable   # точечное переопределение

Советы:

• Давайте говорящие имена: &base, &limits.
• Не делайте глубоких каскадов мержей — сложнее отлаживать.

6) Многострочные строки: | и >

• | — сохраняет переносы строк.
• > — сворачивает переносы в пробелы (получается один абзац).

Пример:

# перенос сохранится
literal: |
  line1
  line2

# станет "line1 line2"
folded: >
  line1
  line2

Правило: конфиги/скрипты — через |; тексты-абзацы — через >.

7) Порядок ключей в словаре не гарантирован

Если порядок важен — используйте список словарей.

# Плохо (расчёт на порядок ключей):
fields:
  title: ...
  date: ...
  author: ...

# Хорошо
fields:
  - name: title
  - name: date
  - name: author

8) Явные типы с тегами

Иногда полезно жёстко указать тип: !!str, !!int, !!bool.

Пример:

flag: !!str yes     # строка "yes", не bool
count: !!int "042"  # число 42

Используйте точечно, когда важно избежать автоприведения.

9) Спецсимволы в строках

Двоеточие, решётка и другие внутри значения — лучше экранировать кавычками.

# Плохо
title: Hello: World   # двоеточие может сломать парсер
note: # not a comment  # YAML решит, что это комментарий

# Хорошо
title: "Hello: World"
note: "# not a comment"

10) Пустые значения: null, ~, и пустая строка

• null и ~ — это null.
• "" — пустая строка.

Пример:

empty: ""      # пустая строка
nothing: null  # null
also_null: ~

Выбирайте осознанно: отсутствие значения или «пустой текст».

11) Смешение стилей списков

Так можно, но старайтесь быть единообразными в рамках файла или секции.

Пример (допустимо):

envs: [prod, stage]
servers:
  - web01
  - web02

Правило: читаемость важнее компактности.

12) Валидируйте и форматируйте автоматически

Подключите линтер и единые правила в репозитории (pre-commit hooks). Это спасает от мелких, но болезненных ошибок.

Минимальный yamllint:

extends: default
rules:
  indentation:
    spaces: 2
    indent-sequences: consistent
  line-length:
    max: 120
    level: warning

Также пригодятся:

• .editorconfig с настройкой отступов и финальных переводов строк.
• Автоформат в IDE (VS Code: YAML plugin + yamllint).

Быстрый чек-лист перед коммитом

• Пробелы вместо табов, 2 пробела на отступ.
• Булевы — только true/false; всё неоднозначное — в кавычки.
• Числа без ведущих нулей; формат — строкой.
• Даты/похожие паттерны — в кавычки, если это не дата.
• Многострочные: | для конфигов/скриптов, > для абзацев.
• Если порядок важен — список словарей, не map.
• Анкоры с понятными именами, избегать «матрёшек» из мержей.
• Прогон через валидатор/линтер обязателен.

Где это особенно важно

• Ansible: переменные окружения, шаблоны, when/vars — следите за типами.
• Kubernetes: значения env, ресурсы, аннотации — кавычки спасают от неожиданных типов.
• CI/CD: secrets, матрицы стратегий, условия — меньше «магии», больше явности.