Yaml для веб разработчиков

Оригинальная статья: Raul Melo — Yaml for Web Developers

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

Если вы начинаете карьеру в качестве фронтенд разработчика, вы можете встретить в разных репозитариях множество файлов .yml, таких как .travis.yml (для Travis Build), .gitlab-ci.yml (для git lab CI) и т. д. И давайте будем честными, что порой могут возникать вопрос, что это такое?

Почему люди используют этот тип файлов? В чем от них выгода? Как это работает?

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

---

Что такое YAML?

Согласно официальному сайту, Yaml это:

YAML (сокращение от YAML Ain’t Markup Language — YAML не является языком разметки) — это удобный для людей стандарт сериализации данных для всех языков программирования

Часто используется для записи файлов конфигурации, что многое объясняет, верно?

В какой то момент времени возникла усталость от множество форматов разных конфигов, которые никто не мог понять, пока кто-то просто не сказал:

Что если бы мы могли как-то написать нашу конфигурацию как «рецепт торта»? Я имею в виду минимальный голый текст, максимально простым способом?

Бум, и в мае 2001 года был создан Yaml.

---

YAML против JSON

Удивительно (хотя вроде и не совсем), Yaml — это расширенная версия нашего известного друга JSON.

«Yaml — это язык разметки, который содержит все функции разметки JSON и был расширен для включения других функций».

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

В мире фронтенда Yaml и JSON можно сравнить как TypeScript и JavaScript

Чтобы лучше понять, давайте посмотрим на этот пример конфига:

{
  "compilerOptions": {
    "module": "system",
    "noImplicitAny": true,
    "removeComments": true,
    "preserveConstEnums": true,
    "outFile": "../../built/local/tsc.js",
    "sourceMap": false,
    "types": ["node", "lodash", "express"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

Это пример tsconfig.json, он очень легко читаться, мы можем легко определить, что к чему, но … у него есть некоторые ограничения, например:

• Нельзя создавать переменные;
• Невозможно использовать внешние переменные (например, переменные окружения);
• Нельзя переопределить значения;

В мире JS, если мы можем создать .json файл конфигурации, мы почти всегда можем также создать .js (например, .eslintrc или .eslint.js), который позволяет нам смягчить недостатки, упомянутые ранее.

Но, если вы используете другой язык программирования, файлы JS не вариант. И именно в этот момент Yaml начинает сиять.

Если бы нам пришлось переписать tsconfig.json в синтаксисе YAML и получить такой же результат, это было бы так:

compilerOptions:
  module: system
  noImplicitAny: true
  removeComments: true
  preserveConstEnums: true
  outFile: '../../built/local/tsc.js'
  sourceMap: false
  types:
    - node
    - lodash
    - express
include:
  - src/**/*
exclude:
  - node_modules
  - '**/*.spec.ts'

Обратите внимание, что это только пример. Вы не можете написать свой tsconfig в YAML!😜

Я надеюсь, что вы поняли идею из этих примеров.

---

Концепции, Типы, и синтаксис

Теперь давайте немного углубимся в концепцию языка.

Отступы

В Yaml отступы очень важны. Он использует отступы для разделения информации. Помнить нужно использовать только пробелы, табы не допускаются.

Если вы похожи на меня и используете табы для всего, установите какой-нибудь плагин в вашей IDE, чтобы заменить все пропуски на пробелы (например, editorconfig). Это может делаться автоматически, когда вы нажимаете на пропуск, он автоматически заменяется пробел! 😉

Root (Начало)

Поскольку здесь важен отступ, отсутствия отступа перед первым объявлением YAML поймет, что это корень (уровень 0) вашего файла:

person:
  age: 20

Как и в JSON с первым символом { фигурной скобки:

{
  "person": {
    "age": 20
  }
}

Ключ/Значение

Как и в JSON/JS, YAML также использует синтаксис ключ/значение, и вы можете использовать его различными способами:

key: value
key_one: value one
key one: value # это тоже будет работать, но такое использование странно
'my key': somekey

Комментарии

Чтобы написать комментарий, вы просто можете использовать #, а затем ваше сообщение.

# Это комментарий
person: # это то же комментарий
  age: 20

Это круто, чтобы документировать какое-то решение или сделать заметку в конфиге. К сожалению, мы не можем так эе сделать это в JSON.

Списки

Есть 2 способа написания списков:

Синтаксис JSON: массив строк

Помните, Yaml — это расширенный JSON? мы можем использовать его синтаксис:

people: ['Anne', 'John', 'Max']

Синтаксис дефиса

Наиболее распространенный (и, вероятно, рекомендуется)

people:
  - Anne
  - John
  - Max

Строки

Есть несколько способов объявить строку в Yaml:

company: Google # Отдельные слова, без кавычек
full_name: John Foo Bar Doe # Полное предложение, без кавычек
name: 'John' # Использование одинарных кавычек
surname: "Christian Meyer" # Использование двойных кавычек

В то время как в JSON у нас есть только один способ использовать двойные кавычки:

{
  "company": "Google",
  "full_name": "John Foo Bar Doe",
  "name": "John",
  "surname": "Christian Meyer"
}

В качестве предложения предпочитайте использовать кавычки, если вы хотите использовать какой-либо специальный символ, такой как _, @ и т. Д.

Номера

Как и в любом языке программирования, у нас есть 2 типа чисел: целое число и число с плавающей запятой:

year: 2019 # Integer
nodeVersion: 10.8 # Float

Якоря узла (переменные)

Якорь — это механизм для создания группы данных (объекта), который может быть введен или расширен из других объектов.

Давайте представим, что вам нужно создать конфигурацию для вашего CI. Он будет иметь версию для production, и для staging (промежуточную) сред. Обе версии будут иметь почти одинаковые базовые настройки.

В мире JSON нам пришлось бы дублировать эти конфиги:

{
  "production": {
    "node_version": "13.0.0",
    "os": "ubuntu",
    "package_manager": "yarn",
    "run": ["yarn install", "NODE_ENV=${ENVIRONMENT} yarn build"],
    "env": {
      "ENVIRONMENT": "production"
    }
  },
  "staging": {
    "node_version": "13.0.0",
    "os": "ubuntu",
    "package_manager": "yarn",
    "run": ["yarn install", "NODE_ENV=${ENVIRONMENT} yarn build"],
    "env": {
      "ENVIRONMENT": "staging"
    }
  }
}

Копирование и вставка очень раздражают, особенно когда вам нужно что-то изменить во всех местах, где это использовалось.

Якоря, решают эту проблему. Мы можем:

1. Во-первых, создайте наш якорь

# Я называл это "base-config", но это может быть что угодно
# &base будет "именем переменной", которое вы будете использовать при внедрении
base-config: &base
  node_version: 13.0.0
  os: ubuntu
  package_manager: yarn
  run:
    - yarn install
    - NODE_ENV=${ENVIRONMENT} yarn build

1. Затем, используем эту переменную:

base-config: &base
  node_version: 13.0.0
  os: ubuntu
  package_manager: yarn
  run:
    - yarn install
    - NODE_ENV=${ENVIRONMENT} yarn build

production:
  # Я внедряю все «base» атрибуты и значения в production
  <<: *base
  env:
    - ENVIRONMENT: production

staging:
  # Я внедряю все «base» атрибуты и значения в staging подготовки 
  <<: *base
  env:
    - ENVIRONMENT: staging

Выглядит очень просто, верно? И это также проще в обслуживании.

Если вы скопируете этот код и вставите его в онлайн-инструмент «Конвертер Yaml в JSON», вы увидите тот же код, который я упоминал ранее в примере JSON, но с добавлением базовой конфигурации:

{
  "base-config": {
    "node_version": "13.0.0",
    "os": "ubuntu",
    "package_manager": "yarn",
    "run": ["yarn install", "NODE_ENV=${ENVIRONMENT} yarn build"]
  },
  "production": {
    "node_version": "13.0.0",
    "os": "ubuntu",
    "package_manager": "yarn",
    "run": ["yarn install", "NODE_ENV=${ENVIRONMENT} yarn build"],
    "env": [
      {
        "ENVIRONMENT": "production"
      }
    ]
  },
  "staging": {
    "node_version": "13.0.0",
    "os": "ubuntu",
    "package_manager": "yarn",
    "run": ["yarn install", "NODE_ENV=${ENVIRONMENT} yarn build"],
    "env": [
      {
        "ENVIRONMENT": "staging"
      }
    ]
  }
}

Синтаксис JSON (да, JSON)

Как объяснялось ранее, расширенный язык является таким же как базовый язык, плюс некоторые дополнительные функции, что означает, что мы можем написать файл Yaml в формате JSON.

{
  "details": {
    "company": {
      "name": "Google",
      "year": 2019,
      "active": true
    },
    "employees": [
      "Anne",
      "John",
      "Max"
    ]
  }
}

Сомневаетесь? Скопируйте этот код и вставьте его сюда

Если вы преобразуете этот YAML в JSON, у вас будет такая же структура:

{
  "details": {
    "company": {
      "name": "Google",
      "year": 2019,
      "active": true
    },
    "employees": ["Anne", "John", "Max"]
  }
}

Shell/Bash окружение

Как я говорил в начале этой статьи, очень часто файлы .yml используются как файлы конфигурации для многих вещей, но особенно для среды CI/CD.

Для использования CI/CD вам нужно будет описать, как должен работать компьютер/docker, что должно быть установлено, запущено и т. д.

Обычно все это делается через среды — Linux, что означает, что у вас также будет доступ к самой среде.

Например, в GitLab CI вы можете указать на глобальном уровне переменные среды, которые должны быть доступными для всех процессов:

variables:
  NODE_IMAGE: node:10

stages:
  - build

test:
  image: $NODE_IMAGE
  stage: build

Обратите внимание, что синтаксис для использования переменных $ не из YAML, а из shell/bash.

GitLab CI делает все, что вы определили в переменных, и создает переменные оболочки.

Некоторые другие платформы также вводят другие значения, такие как ref, имя ветки (branch name), время сборки (build time), авторы (author), а также секретные ключи (secret keys), определенные вне конфигурации:

variables:
  NODE_IMAGE: node:10

stages:
  - build

test:
  image: $NODE_IMAGE
  stage: build
  artifacts:
    name: $CI_COMMIT_REF_NAME

В приведенном выше примере мы используем переменную внешней среды $CI_COMMIT_REF_NAME, которую предоставляет платформа GitLab CI, которая описывает имя ветви или тега, для которого построен проект.

---

Заключение

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

Всегда читайте документацию по платформе, над которой вы работаете, чтобы узнать, что можно или не нужно делать! 🙂

---

Ссылки

• YAML Website. (Тут вы можете найти парсеры для всех языков);
• Learn X in Y Minutes: YAML: Здесь полное руководство/введение о том, что YAML может сделать для вас;
• JSON ←→ YAML Online converter: Может быть полезно для визуализации того, что в JSON соответствует в YAML;
• YAML by Wikipedia