Полное название YAMLYAML Ain't Markup Language(рекурсивная аббревиатура) — это удобный для чтения человеком формат сериализации данных.

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

Синтаксис YAML похож на другие высокоуровневые языки и позволяет легко выражать списки, хеш-таблицы, скаляры и другие формы данных.

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

Расширение файла для конфигурационных файлов YAML —.yml, например:example.yml 。

Особенности и преимущества YAML

Цели дизайна YAML включают высокую читабельность, лаконичный синтаксис, близость к естественным языковым привычкам написания и почти полное отсутствие необходимости в дополнительных символах.

По сравнению с XML и JSON, YAML сокращает множество скобок и кавычек, что упрощает написание.

Он поддерживает сложные структуры данных, позволяет выражать списки, словари, вложенные структуры и даже поддерживает такие продвинутые возможности, как ссылки и якоря.

Почти все распространённые языки программирования имеют библиотеки для разбора YAML, и экосистема очень зрелая.

Сравнение YAML с JSON и XML

У этих трёх форматов свои акценты; в таблице ниже они сравниваются по нескольким параметрам:

ХарактеристикаYAMLJSONXML
ЧитаемостьВысокаяСредняяНизкая
Поддержка комментариевПоддерживаетсяНе поддерживаетсяПоддерживается
Сложность синтаксисаНизкаяСредняяВысокая
Распространённые варианты использованияФайлы конфигурацииОбмен данными / 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 для распространённых языков программирования

ЯзыкПопулярные библиотекиОсобенности
PythonPyYAML、ruamel.yamlPyYAML — самый популярный, ruamel.yaml поддерживает YAML 1.2
JavaScript / Node.jsjs-yamlРаботает как в браузере, так и в среде Node.js
JavaSnakeYAMLБиблиотека парсинга YAML, используемая по умолчанию в Spring Boot
Gogopkg.in/yaml.v3Самая часто используемая библиотека YAML в экосистеме Go
RubyPsychВстроена в стандартную библиотеку, дополнительная установка не требуется

Рекомендуемые плагины для редакторов

РедакторРекомендуемый плагинОсобенности
VSCodeYAML-плагин от Red HatПодсветка синтаксиса, проверка формата, проверка схемы
IntelliJ IDEA / PyCharmВстроенная поддержкаДополнительная установка не требуется, работает из коробки
Sublime TextПлагины, связанные с YAMLУлучшает подсветку синтаксиса и форматирование