Czym jest YAML? Zrozum podstawy, składnię i zastosowania

Przez lata pracowałem z niezliczonymi plikami konfiguracyjnymi, a YAML wyróżnia się prostotą i czytelnością. Niezależnie od tego, czy ustawiasz workflowy w Kubernetesie, definiujesz usługi w Dockerze, czy strukturyzujesz żądania API, YAML ułatwia zarządzanie złożonymi konfiguracjami. Jego przejrzysta, oparta na wcięciach struktura eliminuje „szum” formatów takich jak XML, zachowując elastyczność.

W tym przewodniku przeprowadzę cię przez składnię, strukturę, funkcje zaawansowane i dobre praktyki YAML, abyś mógł pracować z nim pewnie. 

Czym jest YAML?

YAML (Yet Another Markup Language / YAML Ain’t Markup Language) to format serializacji danych, który stawia na czytelność i łatwość użycia. Podczas gdy XML używa zagnieżdżonych, „HTML-owych” tagów, a JSON nawiasów klamrowych i cudzysłowów, podobnie jak słowniki w Pythonie, YAML jest zwięzły i używa wcięć do definiowania struktury, co czyni go bardziej przyjaznym dla człowieka.

YAML obsługuje różne typy danych, w tym skalary (łańcuchy, liczby, wartości logiczne), sekwencje (listy) i mapowania (pary klucz-wartość). Jest szeroko stosowany w plikach konfiguracyjnych, automatyzacji infrastruktury i wymianie danych, zwłaszcza w narzędziach takich jak Kubernetes, Docker i Ansible.

Dodatkowo YAML jest nadzbiorem JSON, co oznacza, że prawidłowe pliki JSON mogą być parsowane jako YAML. Pliki YAML zazwyczaj mają rozszerzenie .yaml lub .yml.

Więcej o YAML znajdziesz również na jego stronie.

Składnia i struktura YAML

W tej sekcji poznasz podstawowe zasady składni YAML, w tym pary klucz-wartość, listy, dane zagnieżdżone i komentarze.

Podstawowe zasady składni

Istnieje kilka podstawowych reguł składni YAML: 

• Wcięcia spacjami wyznaczają strukturę, więc unikaj tabulatorów! 
• Pary klucz-wartość mają postać key: value, podobnie jak w innych językach. 
• Myślniki na początku linii oznaczają listę. 
• Użycie # tworzy linie komentarzy.

# Here is an example of YAML
name: John Doe
age: 30
skills:
  - Python
  - YAML

Pary klucz-wartość

YAML przedstawia dane jako pary klucz-wartość, podobnie jak słowniki w Pythonie. Często służy to do przekazywania informacji do różnych plików konfiguracyjnych i ustawień. Nie ma potrzeby oznaczania łańcuchów czy kluczy cudzysłowami; po prostu zapisz potrzebny klucz i wartości:

location: New York
country: USA
security-level: user

Listy w YAML

Listy są reprezentowane przy użyciu myślników (-). Dzięki temu możesz wymienić wiele obiektów pod jednym kluczem. Edytory znaczników często wizualizują to jako wypunktowania.

fruits:
  - Apple
  - Banana
  - Cherry

Dane zagnieżdżone

Zagnieżdżone struktury pozwalają na hierarchiczną reprezentację danych poprzez wcięcia. Traktuj je jak zagnieżdżone słowniki. Używając wcięć, wskazujesz, które klucze są podzestawami innych.

person:
  name: Alice
  details:
    age: 25
    city: London

Komentarze

Komentarze zaczynają się od # i są ignorowane przez parsery YAML. To komentarze jednolinijkowe.

# This is a comment
username: admin
password: secret

Zaawansowane funkcje YAML

YAML zawiera funkcje takie jak wielolinijkowe łańcuchy, typy danych oraz kotwice, które sprawiają, że dokumenty są bardziej efektywne i uporządkowane. W tej sekcji omówimy je na praktycznych przykładach.

Wielolinijkowe łańcuchy

YAML obsługuje wielolinijkowe łańcuchy z użyciem | (blok literału) lub > (blok składany). 

• Blok literału | utworzy nową linię \n dla każdego podziału linii. 
• Blok składany > utworzy nową linię tylko dla kolejnych podziałów linii.

literal: |
  This is a
  multi-line string.

folded: >
  This is another
  multi-line string.

Powyższe najlepiej zrozumieć, pokazując wynik.

• Dla | (blok literału):

This is a
multi-line string.

• Dla > (blok składany):

This is another multi-line string.

Typy danych w YAML

YAML obsługuje różne typy danych, w tym łańcuchy, liczby, wartości logiczne oraz null. Automatycznie wykrywa typy na podstawie formatowania, ale pozwala też na jawne definicje typów.

Poniższy przykład pokazuje użycie podstawowych typów danych w YAML:

string_implicit: Hello, YAML!  # No quotes needed unless necessary
string_double_quoted: "Supports escape sequences like \n and \t"
string_single_quoted: 'Raw text, no escape sequences'

integer: 42  # Whole numbers
float: 3.14  # Numbers with decimals

boolean_true: true
boolean_false: false

null_value: null  # Null value
null_tilde: ~  # Another way to represent null

YAML umożliwia jawne deklaracje typów za pomocą !!type, gdy jest to potrzebne:

explicit_string: !!str 123  # Forces 123 to be a string
explicit_integer: !!int "42"  # Forces "42" to be an integer
explicit_float: !!float "3.14"  # Forces "3.14" to be a float

Ponieważ YAML często służy do danych strukturalnych, wspiera:

• Listy (sekwencje):

fruits:
  - Apple
  - Banana
  - Cherry

• Słowniki (mapowania):

person:
  name: Alice
  age: 30
  is_student: false

Kotwice i aliasy

YAML pozwala definiować wartości wielokrotnego użytku przy użyciu kotwic (&) i odwoływać się do nich później za pomocą aliasów (*). Pomaga to zmniejszyć redundancję w plikach konfiguracyjnych, czyniąc je czystszymi i łatwiejszymi w utrzymaniu.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  host: example.com
  retries: *default_settings  # Reuses the retries value from defaults

Składnia <<: pozwala scalać pary klucz-wartość z kotwicy do innego mapowania. Jeśli dany klucz istnieje w obu miejscach, nowa wartość nadpisuje oryginalną.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  <<: *default_settings  # Merges all key-value pairs from default_settings
  host: example.com  # This key is added to the merged data

Tak wygląda finalna, rozstrzygnięta struktura:

server1:
  retries: 3
  timeout: 30
  host: example.com

Kotwice i aliasy są szczególnie przydatne w dużych plikach konfiguracyjnych, gdzie ręczne powtarzanie wartości byłoby nieefektywne. Pomagają utrzymać pliki YAML w duchu DRY (Don't Repeat Yourself) i ułatwiają aktualizacje.

Typowe zastosowania YAML

YAML jest szeroko używany w tworzeniu oprogramowania, automatyzacji infrastruktury i zarządzaniu API. Jego czytelna składnia sprawia, że jest preferowanym formatem dla plików konfiguracyjnych, serializacji danych i Infrastructure as Code (IaC). Przyjrzyjmy się najczęstszym zastosowaniom.

Pliki konfiguracyjne

YAML jest szeroko stosowany do konfiguracji w aplikacjach takich jak Docker Compose, Kubernetes i pipeline’y CI/CD. Jego zrozumiałość sprawia, że każdy łatwo podłapie pliki konfiguracyjne YAML Dockera i zrozumie, co się dzieje.

version: '3'
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - NGINX_HOST=localhost
      - NGINX_PORT=80

Czytelność YAML oraz wsparcie dla kotwic i aliasów pomagają ograniczyć powtórzenia, co czyni go łatwiejszym w utrzymaniu niż JSON czy XML.

Dowiedz się więcej o YAML i jego użyciu w Dockerze w tym kursie Docker dla średnio zaawansowanych.

Serializacja i transfer danych

YAML służy do serializacji danych dla API i narzędzi do zarządzania konfiguracją, przekształcając złożone struktury danych w format czytelny dla ludzi i łatwy do przetwarzania przez maszyny. 

Przykładowo, treść żądania API sformatowana w YAML:

user:
  id: 123
  name: "John Doe"
  email: "johndoe@example.com"
  active: true

Struktura oparta na wcięciach eliminuje zbędną składnię, dzięki czemu YAML jest lżejszy, czytelniejszy i łatwiejszy do modyfikacji w porównaniu z JSON.

Infrastructure as Code (IaC)

Narzędzia do zarządzania konfiguracją, takie jak Ansible i Kubernetes, wykorzystują YAML do definiowania stanów systemów, automatyzacji procesów i zapewniania spójności między środowiskami.

• W Ansible YAML służy do pisania playbooków, które definiują stany systemów, zadania i zależności, zapewniając spójną konfigurację komponentów infrastruktury. 
• Kubernetes używa manifestów YAML do definiowania zasobów, takich jak pody, usługi i deploymenty, umożliwiając automatyczną orkiestrację aplikacji konteneryzowanych.

Oto przykład konfiguracji poda w Kubernetes:

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
    - name: app-container
      image: my-app:latest
      ports:
        - containerPort: 8080

Dowiedz się więcej o tym, jak YAML jest używany w Kubernetesie w kursie Wprowadzenie do Kubernetes.

Dokumentacja API

Specyfikacje API, takie jak OpenAPI i Swagger, używają YAML do definiowania endpointów i struktur danych w czytelny sposób. YAML służy do opisu metod API, parametrów żądań, formatów odpowiedzi i metod uwierzytelniania.

Oto przykład specyfikacji OpenAPI w YAML:

openapi: 3.0.0
info:
  title: User API
  version: "1.0"
paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        "200":
          description: Successful response

Specyfikacje OpenAPI, na przykład, używają YAML do dokumentowania REST-owych API. Dzięki temu mogą stanowić jasną podstawę do generowania klientskich SDK, interaktywnej dokumentacji API i testów automatycznych. Ta ustrukturyzowana forma zapewnia spójność implementacji API.

Praca z plikami YAML

YAML jest szeroko używany w plikach konfiguracyjnych, automatyzacji i serializacji danych, ale ponieważ opiera się na wcięciach, poprawne formatowanie jest kluczowe. Oto jak skutecznie czytać, pisać, walidować i edytować YAML.

Odczyt i zapis YAML w Pythonie

Biblioteka Pythona PyYAML potrafi parsować i generować YAML.

Załóżmy, że masz następujący plik konfiguracyjny YAML:

database:
  host: localhost
  port: 5432
  user: admin
  password: secret

Oto jak możesz pracować z tym plikiem konfiguracyjnym w Pythonie:

import yaml

# Load YAML data
with open("config.yaml", "r") as file:
    data = yaml.safe_load(file)  # safe_load prevents arbitrary code execution

# Modify data (optional)
data["database"]["user"] = "new_user"

# Write YAML data
with open("output.yaml", "w") as file:
    yaml.dump(data, file, default_flow_style=False)

Jeśli chcesz pracować z danymi JSON w Pythonie, sprawdź kompleksowy samouczek Python JSON.

Walidacja plików YAML

Aby upewnić się, że struktura jest poprawna, możesz użyć narzędzi wykrywających tabulatory zamiast spacji lub różne problemy, takie jak powtórzone znaki, błędy składni czy spacje końcowe.

Oto kilka popularnych walidatorów YAML:

• Narzędzie CLI: yamllint (linter oparty na Pythonie)
• Walidatory online: YAML Lint, YAML Validator od JSON Formatter

Edycja YAML

YAML możesz pisać i edytować w dowolnym edytorze tekstu, ale lintowanie i podświetlanie składni poprawiają czytelność.

Niektóre z moich ulubionych edytorów:

• VS Code (z wtyczkami YAML)
• PyCharm (wbudowane wsparcie)
• Sublime Text (z podświetlaniem składni YAML)

Najczęstsze błędy w YAML i jak ich unikać

Mimo swojej prostoty, przy pracy z YAML łatwo o problemy i literówki. Ta sekcja omawia te błędy i podaje dobre praktyki pisania czystych i poprawnych plików. Dlatego też polecam używanie lintera lub odpowiedniego edytora tekstu!

Mieszanie tabulatorów i spacji

YAML opiera się na spacjach do wcięć — nigdy nie mieszaj spacji i tabulatorów. Tabulatory po prostu zepsują twój skrypt YAML. To świadoma decyzja: różne systemy różnie interpretują tabulatory, dlatego, by zminimalizować problemy, preferowane są spacje.

Nieprawidłowe wcięcia

Dbaj o spójne wcięcia, by uniknąć błędów parsowania. Ponieważ wcięcia to jedyny sposób YAML na oznaczanie hierarchii, nieprawidłowe wcięcia mogą powodować problemy z twoim kodem. Łatwo „schować” parę key: value w niewłaściwym miejscu, więc miej oko na wcięcia!

Brak cudzysłowów przy znakach specjalnych

Używaj cudzysłowów dla łańcuchów zawierających znaki specjalne lub spacje. Rzeczy takie jak backslash, przecinki, wykrzykniki itd. wymagają cudzysłowów, by były odczytane jako łańcuchy.

path: "/home/user/documents"
message: "Hello, World!"

Korzystając z odpowiedniej walidacji, uporządkowanej edycji i biblioteki PyYAML w Pythonie, możesz sprawnie pracować z plikami YAML, unikając typowych pułapek.

Podsumowanie

YAML to potężny, a zarazem prosty format szeroko stosowany w konfiguracji, serializacji danych i automatyzacji infrastruktury. Rozumiejąc jego składnię, strukturę i dobre praktyki, możesz efektywnie używać YAML w różnych zastosowaniach.

Jeśli chcesz zastosować YAML w praktycznych scenariuszach:

• Dowiedz się, jak YAML jest używany w workflowach CI/CD w tym kursie CI/CD dla uczenia maszynowego.
• Zobacz, jak API wykorzystują YAML w swoich specyfikacjach, w tym kursie Wprowadzenie do API w Pythonie.
• Wejdź głębiej w konteneryzację i automatyzację infrastruktury na tej ścieżce Konteneryzacja i wirtualizacja.