Полное название YAMLYAML Ain't Markup Language(рекурсивная аббревиатура) — это удобный для чтения человеком формат сериализации данных.
YAML часто используется для файлов конфигурации, обмена данными и в различных сценариях, где данные нужно хранить структурированным образом.
Синтаксис YAML похож на другие высокоуровневые языки и позволяет легко выражать списки, хеш-таблицы, скаляры и другие формы данных.
Он использует отступы пробелами и в значительной степени опирается на внешний вид, что делает его особенно подходящим для выражения или редактирования структур данных, различных файлов конфигурации, вывода отладочной информации и структур файлов.
Расширение файла для конфигурационных файлов YAML —.yml, например:example.yml 。

Особенности и преимущества YAML
Цели дизайна YAML включают высокую читабельность, лаконичный синтаксис, близость к естественным языковым привычкам написания и почти полное отсутствие необходимости в дополнительных символах.
По сравнению с XML и JSON, YAML сокращает множество скобок и кавычек, что упрощает написание.
Он поддерживает сложные структуры данных, позволяет выражать списки, словари, вложенные структуры и даже поддерживает такие продвинутые возможности, как ссылки и якоря.
Почти все распространённые языки программирования имеют библиотеки для разбора YAML, и экосистема очень зрелая.
Сравнение YAML с JSON и XML
У этих трёх форматов свои акценты; в таблице ниже они сравниваются по нескольким параметрам:
| Характеристика | YAML | JSON | XML |
|---|---|---|---|
| Читаемость | Высокая | Средняя | Низкая |
| Поддержка комментариев | Поддерживается | Не поддерживается | Поддерживается |
| Сложность синтаксиса | Низкая | Средняя | Высокая |
| Распространённые варианты использования | Файлы конфигурации | Обмен данными / API | Документ / обмен данными |

Типичные сценарии использования YAML
YAML практически вездесущ в современном стеке разработки; вот наиболее распространённые сценарии:
Файлы конфигурации приложений, напримерapplication.yml в Spring Boot。
Инструменты оркестрации контейнеров, такие как файлы описания развёртывания для Docker Compose и Kubernetes.
Конфигурация конвейеров CI/CD, такая как определения рабочих процессов для GitHub Actions, GitLab CI и CircleCI.
Front Matter для генераторов статических сайтов, например метаданные страниц для Jekyll и Hugo.
Основные правила синтаксиса
Освойте самые базовые правила написания YAML, включая отступы, комментарии, структуру файла и т. д.
Правила отступов
YAML используетпробелыдля отступов, чтобы обозначать иерархию,нельзя использовать клавишу Tab。
Элементы одного уровня должны иметь одинаковый размер отступа; обычно рекомендуется использовать 2 пробела в качестве единицы отступа.
person: name: 张三 age: 25
Базовый синтаксис
Ниже приведены основные правила синтаксиса YAML, которые нужно запомнить:
- Регистрозависимость
- Используйте отступы для обозначения иерархии
- В отступах не допускаются табуляции, только пробелы
- Количество пробелов для отступа не важно, главное, чтобы элементы одного уровня были выровнены по левому краю
- #Обозначает комментарий
- :После символа нужно добавлять пробел
Чувствительность к регистру
Имена ключей, строки и т. д. в YAML чувствительны к регистру.
Nameиnameбудут считаться двумя разными ключами; при написании нужно следить за согласованностью.
Синтаксис комментариев
Использование#Содержимое в начале является комментарием; комментарии могут занимать целую строку или располагаться после содержимого.
# 这是一行注释 name: 张三 # 这也是注释
Расширения файлов
Файлы YAML обычно используют.yamlили.ymlв качестве расширения; между ними нет существенной разницы, всё зависит от соглашений проекта.
Разделители документов
---Используется для обозначения начала нового документа; особенно важно в файлах с несколькими документами.
...Используется для обозначения конца документа и является необязательным маркером.
--- doc: 第一个文档 --- doc: 第二个文档
Базовые типы данных
YAML поддерживает базовые типы данных, такие как строки, числа, логические значения и null; каждый тип имеет определённый стиль записи.
Обзор типов данных
YAML поддерживает следующие типы данных:
- Объекты: коллекция пар ключ-значение, также известная как отображение / хеши / словарь
- Массивы: набор значений, упорядоченных по порядку, также известный как последовательность / список
- Скаляры: единичные, неделимые значения
Скаляр
Скаляры — это самые базовые единицы данных в YAML, которые делятся на следующие типы:
Строки
Строки можно записывать без кавычек, либо заключать в двойные или одинарные кавычки.
Двойные кавычки поддерживают escape-последовательности (например,\n), а одинарные кавычки не поддерживают экранирование.
name: 张三 # 不加引号 name: "张三" # 双引号,支持转义字符 name: '张三' # 单引号,不支持转义
Цифры
YAML автоматически распознаёт целые числа и числа с плавающей точкой без необходимости объявлять типы.
age: 25 # 整数 price: 19.99 # 浮点数
Логические значения
Для представления логических значений используютсяtrueиfalse.
is_active: true is_deleted: false
Null
Null можно представить с помощьюnull、~или не указывать ничего.
value: null value: ~ value: # 什么都不写也表示 null
Полный пример скаляров
В следующем примере показано, как использовать все типы скаляров, включая логические значения, числа с плавающей точкой, целые числа, null, строки, даты и время:
boolean:
- TRUE # true,True 都可以
- FALSE # false,False 都可以
float:
- 3.14
- 6.8523015e+5 # 可以使用科学计数法
int:
- 123
- 0b1010_0111_0100_1010_1110 # 二进制表示
null:
nodeName: 'node'
parent: ~ # 使用 ~ 表示 null
string:
- 哈哈
- 'Hello world' # 可以使用双引号或者单引号包裹特殊字符
- newline
newline2 # 字符串可以拆成多行,每一行会被转化成一个空格
date:
- 2018-02-17 # 日期必须使用 ISO 8601 格式,即 yyyy-MM-dd
datetime:
- 2018-02-17T15:02:31+08:00 # 时间使用 ISO 8601 格式,时间和日期之间使用 T 连接,最后使用 + 代表时区
Даты и время должны использовать формат ISO 8601. Формат даты —yyyy-MM-dd, формат времени —yyyy-MM-ddTHH:mm:ss+timezone, посерединеTдля соединения.
Многострочные строки
YAML предоставляет два способа записи многострочных строк, каждый из которых подходит для разных сценариев.
Свёрнутый стиль (>)
Используйте символ>, чтобы свернуть многострочный текст в одну строку; символы новой строки заменяются пробелами.
description: > 这是第一行 这是第二行 这是第三行
Приведённая выше запись эквивалентна:"This is the first line This is the second line This is the third line\n"
Литеральный стиль (|)
Использование|символа сохраняет исходные переводы строк, подходит для написания многострочного текста (например, содержимого скриптов).
script: | echo "第一行" echo "第二行" echo "第三行"
Сравнение | и >
Ниже, используя одинаковое содержимоеFoo\nBar, сравним различия между двумя стилями:
this: | Foo Bar that: > Foo Bar
Преобразуется в код JavaScript следующим образом:
{ this: 'Foo\nBar\n', that: 'Foo Bar\n' }
Видно, что|сохраняет переводы строк, в результате получаетсяFoo\nBar\n; тогда как>сворачивает переводы строк в пробелы, в результате получаетсяFoo Bar\n。
Выбор>или|зависит от ваших потребностей: если вам нужно объединить многострочное содержимое в один абзац, используйте>; если вам нужно сохранить исходный формат переводов строк (например, скрипты, стихи), используйте|。
Составные структуры данных
YAML поддерживает две составные структуры: отображения и последовательности. Они могут свободно вкладываться друг в друга для выражения сколь угодно сложных связей данных.
Отображение / Словарь
Отображение — это набор пар ключ-значение, и это наиболее часто используемая структура данных в YAML.
Базовый синтаксис пары ключ-значение
name: 张三 age: 25 city: 北京
Вложенное отображение
С помощью отступов можно вложить одно отображение в другое, образуя иерархическую структуру.
person:
name: 张三
address:
city: 北京
zipcode: "100000"
Синтаксис отображения в потоковом стиле
Вы также можете использоватьkey:{key1: value1, key2: value2, ...}синтаксис в потоковом стиле.
key: {child-key: value, child-key2: value2}
Сложный ключ
Используйте знак вопроса, за которым следует пробел, для представления сложного ключа, в паре с двоеточием и пробелом для представления значения:
?
- complexkey1
- complexkey2
:
- complexvalue1
- complexvalue2
Это означает, что свойство объекта — это массив[complexkey1, complexkey2], а соответствующее значение также является массивом[complexvalue1, complexvalue2]。
Последовательность / Список
префиксная нотация-для хранения упорядоченных коллекций данных.
Базовый синтаксис списка
fruits: - 苹果 - 香蕉 - 橙子
Вложенные списки
matrix: - [1, 2, 3] - [4, 5, 6] - [7, 8, 9]
Многомерные массивы
YAML поддерживает многомерные массивы, которые можно представить встроенно:
key: [value1, value2, ...]
Когда подэлемент структуры данных является массивом, можно сделать отступ в один пробел под этим элементом:
- - A - B - C
Сложный пример, где элементы массива являются объектами
Распространённый реальный сценарий: каждый элемент массива — объект, состоящий из нескольких свойств:
companies:
-
id: 1
name: company1
price: 200W
-
id: 2
name: company2
price: 500W
Это означаетcompaniesсвойство является массивом, и каждый элемент массива состоит изid、name、priceтрёх свойств.
Массивы также можно представить в потоковом стиле:
companies: [{id: 1,name: company1,price: 200W},{id: 2,name: company2,price: 500W}]
Смешивание отображений и последовательностей
Отображения и последовательности можно гибко комбинировать для выражения сложных структур данных.
students:
- name: 张三
age: 20
subjects:
- 数学
- 英语
- name: 李四
age: 22
subjects:
- 物理
- 化学
В приведённом выше примереstudents— это последовательность, каждый элемент — отображение, а у отображенияsubjectsснова является последовательностью. Такое вложенное сочетание — основа выразительности YAML.
Пример составной структуры
Массивы и объекты могут образовывать составные структуры. Ниже приведён пример, содержащий как список, так и отображение:
languages: - Ruby - Perl - Python websites: YAML: yaml.org Ruby: ruby-lang.org Python: python.org Perl: use.perl.org
После преобразования в JSON:
{
languages: [ 'Ruby', 'Perl', 'Python'],
websites: {
YAML: 'yaml.org',
Ruby: 'ruby-lang.org',
Python: 'python.org',
Perl: 'use.perl.org'
}
}
Потоковый синтаксис
Помимо блочной нотации, YAML также поддерживает потоковую нотацию, подобную JSON, подходящую для компактных сценариев.
Потоковое отображение
Используйте фигурные скобки{}для обёртывания пар ключ-значение, разделённых запятыми.
person: {name: 张三, age: 25, city: 北京}
Потоковая последовательность
Используйте квадратные скобки[]для обёртывания элементов, разделённых запятыми.
fruits: [苹果, 香蕉, 橙子]
Сравнение и сценарии использования потокового и блочного стилей
| Style | Особенности | Применимые сценарии |
|---|---|---|
| Блок | Лучшая читаемость, чёткая иерархия | Структурно сложные данные с глубокой вложенностью |
| Потоковый | Более компактный, выражен в одну строку | Простые данные или небольшие данные, встроенные в блочные структуры |
Эти два стиля также можно смешивать:
users:
- {name: 张三, age: 25}
- {name: 李四, age: 30}
Расширенные функции
YAML предоставляет расширенные возможности, такие как якоря, ссылки и ключи слияния, помогающие уменьшить дублирование содержимого.
Якоря и ссылки
Используйте&, чтобы определить якорь, и используйте*, чтобы ссылаться на якорь, избегая повторного написания одного и того же содержимого.
default_settings: &defaults adapter: postgres host: localhost development: <<: *defaults database: dev_db test: <<: *defaults database: test_db
В приведённом выше примере,&defaultsопределяет якорь,*defaultsссылается на содержимое этого якоря,<<указывая на слияние с текущими данными.
Приведённая выше конфигурация разворачивается в:
defaults: adapter: postgres host: localhost development: database: myapp_development adapter: postgres host: localhost test: database: myapp_test adapter: postgres host: localhost
Ссылки на якоря в списках
Якоря также можно использовать в списках:
- &showell Steve - Clark - Brian - Oren - *showell
После преобразования в массив JavaScript:
[ 'Steve', 'Clark', 'Brian', 'Oren', 'Steve' ]
Ключи слияния
<<Используется для слияния содержимого одного отображения в текущее отображение, часто используется вместе с якорями.
Ключ слияния<<— это возможность в спецификации YAML 1.1, поддерживаемая большинством парсеров YAML. Он может сделать конфигурационные файлы более лаконичными, но учтите, что он не является частью спецификации JSON и будет развёрнут в фактическое содержимое при преобразовании в JSON.
Поддержка нескольких документов
В YAML-файле можно использовать---для разделения и хранения нескольких независимых документов, что часто встречается в конфигурационных файлах Kubernetes.
--- kind: Pod metadata: name: pod-1 --- kind: Pod metadata: name: pod-2
Теги и преобразование типов
YAML поддерживает явное указание типов данных через теги, используя объявление с префиксом!!.
explicit_string: !!str 123 explicit_int: !!int "123" explicit_float: !!float "3.14"
Обычные теги включают!!str(строка),!!int(целое число),!!float(число с плавающей точкой),!!bool(логическое значение),!!null(null), и т. д.
Распространённые ошибки и предостережения
YAML очень чувствителен к форматированию. Ниже перечислены наиболее распространённые типы ошибок и способы их избежать.
Сбои разбора, вызванные ошибками отступов
YAML чрезвычайно чувствителен к отступам. Отступы на одном уровне должны быть строго одинаковыми, иначе это приведёт к ошибкам разбора.
# 错误示例:缩进不一致 person: name: 张三 age: 25 # 缩进多了一个空格,会报错
Смешивание табуляции и пробелов
Спецификация YAML чётко указывает, чтотабуляция не допускается для отступов, а пробелы должны использоваться единообразно, иначе большинство парсеров сообщит об ошибке.
Рекомендуется включить в редакторе настройку "Convert Tab to Spaces", чтобы избежать случайного добавления символов табуляции. Большинство современных редакторов поддерживают.yamlи.ymlавтоматически включая эту настройку для файлов.
Экранирование специальных символов
Когда строка содержит:、#、{、}、[、]и другие специальные символы, рекомендуется заключать строку в кавычки, чтобы избежать неверного определения парсером.
title: "标题: 副标题" # 冒号需要用引号包裹 tag: "#重要" # 井号需要用引号包裹,否则会被当作注释
Когда заключать строки в кавычки
В следующих случаях рекомендуется явно добавлять кавычки, чтобы избежать неверного вывода типа парсером YAML:
| Сценарий | Пример | Описание |
|---|---|---|
| Строка начинается с цифры | "100000" | Без кавычек она будет распознана как число |
| Слова, которые легко спутать с булевыми значениями | "true"、"false"、"yes"、"no" | Без кавычек это будет распознано как логическое значение |
| Слова null | "null"、"~" | Без кавычек это будет распознано как null |
| Содержит специальные символы | "Заголовок: Подзаголовок" | Двоеточия, решётки и т. п. будут ошибочно приняты за маркеры синтаксиса |
Практическое применение
Изучите использование YAML в реальных проектах на полных примерах из реальных сценариев.
Написание простого файла конфигурации
Ниже приведён типичный файл конфигурации приложения, демонстрирующий обычную структуру YAML в реальных проектах:
# 应用基本配置 app: name: MyApplication version: 1.0.0 debug: false # 数据库连接配置 database: host: localhost port: 5432 username: admin password: "secret" # 日志配置 logging: level: info file: /var/log/app.log
YAML в Docker Compose
Docker Compose использует YAML для определения оркестрации сервисов многоконтейнерных приложений:
version: "3"
services:
web:
image: nginx:latest
ports:
- "80:80"
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: example
YAML в Kubernetes
Kubernetes использует YAML для определения различных ресурсных объектов. Ниже приведён пример определения Pod:
apiVersion: v1
kind: Pod
metadata:
name: nginx-pod
spec:
containers:
- name: nginx
image: nginx:latest
ports:
- containerPort: 80
YAML в GitHub Actions
GitHub Actions использует YAML для определения рабочих процессов CI/CD:
name: CI
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run tests
run: npm test
Инструменты и валидация
Порекомендуйте несколько практичных инструментов и ресурсов YAML, которые помогут вам более эффективно писать и проверять файлы YAML.
Онлайн-валидаторы YAML
YAML Lint — наиболее часто используемый онлайн-инструмент проверки. Можно поискать «yamllint online», чтобы найти доступные сайты онлайн-проверки.
Различные IDE также имеют встроенную проверку синтаксиса YAML, обеспечивая подсказки об ошибках в реальном времени во время написания.
Библиотеки парсинга YAML для распространённых языков программирования
| Язык | Популярные библиотеки | Особенности |
|---|---|---|
| Python | PyYAML、ruamel.yaml | PyYAML — самый популярный, ruamel.yaml поддерживает YAML 1.2 |
| JavaScript / Node.js | js-yaml | Работает как в браузере, так и в среде Node.js |
| Java | SnakeYAML | Библиотека парсинга YAML, используемая по умолчанию в Spring Boot |
| Go | gopkg.in/yaml.v3 | Самая часто используемая библиотека YAML в экосистеме Go |
| Ruby | Psych | Встроена в стандартную библиотеку, дополнительная установка не требуется |
Рекомендуемые плагины для редакторов
| Редактор | Рекомендуемый плагин | Особенности |
|---|---|---|
| VSCode | YAML-плагин от Red Hat | Подсветка синтаксиса, проверка формата, проверка схемы |
| IntelliJ IDEA / PyCharm | Встроенная поддержка | Дополнительная установка не требуется, работает из коробки |
| Sublime Text | Плагины, связанные с YAML | Улучшает подсветку синтаксиса и форматирование |