راهنمای نهایی YAML برای توسعه دهندگان: از اصول اولیه گرفته تا گردش کار پیشرفته DevOps

مقدمه

yaml (yaml زبان نشانه گذاری نیست) یک است زبان سریال سازی داده های خوانده شده انسانی برای پیکربندی و تبادل داده طراحی شده است. برخلاف XML یا JSON ، YAML از حداقل نحو استفاده می کند و تورفتگی (فضاها) برای نشان دادن ساختار ، خواندن و نوشتن انسان را آسان می کند.

توسعه دهندگان تمام وقت با YAML روبرو می شوند: این ستون فقرات بسیاری از ابزارهای DevOps است (مانیفست های Kubernetes ، فایل های آهنگسازی Docker ، کتاب های پخش قابل قبول ، خطوط لوله CI/CD ، گردش کار اقدامات GitHub و غیره).

به عنوان مثال ، گردش کار اقدامات GitHub در پرونده های YAML تعریف شده است (در .github/workflows/) ، از آنجا که “YAML یک زبان نشانه گذاری است که معمولاً برای پرونده های پیکربندی استفاده می شود”. به دلیل همه گیر بودن در ابزار مدرن و تمرکز آن بر خوانایی ، درک YAML برای توسعه دهندگان بسیار ارزشمند است.

نحو و قالب بندی اساسی

نحو YAML با چند قانون ساده تعریف شده است:

• تورفتگی: برای مشخص کردن لانه سازی از فضاها (نه زبانه) استفاده کنید. دو فاصله در هر سطح رایج است به عنوان مثال ، کلیدهای زیر person: در نظر گرفته شده اند تا نشان دهند که متعلق به آن نقشه برداری هستند.
• جفت های کلید -ارزش: نقشه برداری را به عنوان بنویسید key: valueبشر کلیدها معمولاً الفبایی هستند (فقط در صورت لزوم از نقل قول ها استفاده کنید).
• لیست ها: موارد لیست را با یک هیفن شروع کنید (-). هر یک - عنصر جدیدی را در دنباله شروع می کند.
• نظرات: قبل از نظرات با #بشر هر چیزی در یک خط بعد از # توسط yaml parsers نادیده گرفته می شود.

به عنوان مثال:

# Basic YAML example
person:
  name: John Doe
  age: 30
  skills:
    - Python
    - YAML

در اینجا person نقشه برداری حاوی کلیدها است nameبا ageوت skillsبشر در skills نقشه های کلیدی به لیست دو مورد (مشخص شده -).

توجه داشته باشید وجود دارد بدون برگه، و تورفتگی سازگار است (2 فاصله در هر سطح). تورفتگی نادرست یا مخلوط کردن زبانه ها و فضاها باعث ایجاد خطاهای تجزیه می شود.

انواع داده های اصلی

YAML به طور بومی از چندین نوع داده اصلی پشتیبانی می کند:

• SCALARS: اینها شامل رشته ها ، عدد صحیح ، شناور ، بول و تهی است. YAML معمولاً انواع مختلفی از دستگاه ها:

  • رشته ها: رشته های ساده (بدون سیم) (به عنوان مثال title: Hello) ، یا به نقل از " یا ' برای شخصیت های خاص توالی فرار (مانند \n) در رشته های دو طبقه کار کنید.
  • اعداد: عدد صحیح (age: 42) و شناور (pi: 3.14159) بدون نقل قول نوشته شده اند.
  • Booleans: نماینده به عنوان true/false (حروف کوچک).
  • تهی: استفاده کردن null یا ~ برای نشان دادن یک مقدار تهی.

• توالی (لیست): مجموعه های سفارش داده شده توسط - ورودی ها به عنوان مثال:

  fruits:
    - Apple
    - Banana
    - Cherry

این لیستی از سه رشته را ایجاد می کند.

• نگاشت (هش/فرهنگ لغت): جفت های ارزش کلید بدون هماهنگ. به عنوان مثال:

  database:
    host: db.example.com
    port: 5432
    enabled: true

این یک نقشه با سه کلید ایجاد می کند. (نقشه های YAML در برخی از اسناد “آرایه های انجمنی” نامیده می شوند.)

مثال ترکیب انواع:

app:
  name: MyApp
  version: 1.0
  active: true
  description: "A sample YAML file"
  nullable_field: ~
  tags:
    - backend
    - production
  limits:
    cpu: 2
    memory: 512

در بالا ، active بولی است ، nullable_field تهی است (~)) ، و tags یک لیست است تایپ شل یامل به این معنی است که شما اغلب به نقل قول نیاز ندارید: name: Hello خوب است اما مراقب باشید: رشته های بی سیم مانند yesبا noبا onبا off به طور پیش فرض به عنوان booleans تفسیر می شوند. در صورت لزوم ، یک نوع را با برچسب های صریح مجبور کنید (به عنوان مثال !!str قبل از یک مقدار) ، اگرچه این در پیکربندی های معمولی نادر است.

ویژگی های پیشرفته

فراتر از مقادیر اساسی ، YAML ویژگی های قدرتمندی را ارائه می دهد:

• Anchors & Aliases: استفاده کردن &anchorName برای علامت گذاری یک گره ، و *anchorName برای اشاره به آن در جای دیگر. این از تکرار جلوگیری می کند. به عنوان مثال:

  defaults: &default_settings
    retries: 3
    timeout: 30

  service1:
    <<: *default_settings
    host: example.com

در اینجا &default_settings نقشه برداری را لنگر می زند. service1 سپس استفاده می کند <<: *default_settings برای ادغام آن مقادیر کلیدی (قیام ، زمان بندی) در service1بشر این باعث می شود yaml بزرگ خشک شود (خود را تکرار نکنید).

• رشته های چند خط (مقیاس بلوک): استفاده کردن | (تحت اللفظی) یا > (تاشو) برای متن چند خط:

  note: |
    This is a multiline
    string in literal style.
  summary: >
    This is a folded
    style multiline string.

در | سبک ها شکست خط را حفظ می کند. در > سبک آنها را در فضاها می کشد. (در مثال بالا ، summary خط جدید خود را تاشو خواهد کرد.)

• ساختارهای پیچیده/تو در تو: YAML می تواند داده های عمیق تو در تو را بیان کند. به عنوان مثال ، لیست نقشه ها:

  services:
    - name: web
      replicas: 2
      ports:
        - containerPort: 80
    - name: db
      replicas: 1
      ports:
        - containerPort: 5432

در اینجا services لیستی از دو نقشه برداری است. هر نقشه برداری می تواند کلیدهای خاص و لانه سازی بیشتر را داشته باشد. YAML به شما امکان می دهد تا نقشه ها و توالی ها را به طور خودسرانه مخلوط کنید تا سلسله مراتب پیچیده را نشان دهید.

بلوک در مقابل سبک های جریان و پرونده های چند مستند

به طور پیش فرض YAML از آن استفاده می کند سبک بلوک (تورفتگی) برای وضوح. با این حال ، همچنین از یک جمع و جور تر پشتیبانی می کند سبک جریان (JSON مانند) برای مجموعه ها:

• لیست های سبک بلوک/نگاشت: هر مورد در خط خاص خود ، توطئه شده است.

  colors:
    - red
    - green
    - blue
  user:
    name: Alice
    age: 30

• سبک جریان: لیست ها را در [ ] و نقشه در { }، جدا کردن موارد با کاما. به عنوان مثال:

  colors: [red, green, blue]
  user: { name: "Alice", age: 30 }

سبک جریان یامل معتبر و آینه JSON SYNTAX است. این می تواند لیست/نقشه های کوتاه را جمع و جور تر کند. به طور کلی ، سبک بلوک برای خوانایی ترجیح داده می شود ، اما سبک جریان می تواند برای لیست های درون خطی یا کوتاه مفید باشد.

یامل نیز پشتیبانی می کند اسناد چندگانه در یک پرونده اسناد جداگانه با ---بشر می توانید یک سند را با پایان دهید ... (گرچه اختیاری است). به عنوان مثال:

# Document 1
---
name: Document1
value: 123
# Document 2
---
name: Document2
value: 456
...

هر یک --- یک سند جدید YAML را شروع می کند (که اغلب در پرونده های چند منبع Kubernetes ، خطوط لوله CI و غیره استفاده می شود).

نمونه های استفاده در دنیای واقعی

جریان کار اقدامات GitHub

خطوط لوله CI/CD اقدامات GitHub توسط پرونده های YAML تعریف شده است. هر گردش کار (در .github/workflows/*.yml) محرک ها و مشاغل را مشخص می کند. به عنوان مثال:

name: CI Pipeline
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Building the project..."
      - run: make test

این گردش کار با هر فشار اجرا می شود. زمینه های YAML (nameبا onبا jobs، و غیره) مخصوص اقدامات GitHub است ، اما نحو YAML خالص است. توجه کنید که چگونه steps تحت یک کار لیستی از اقدامات است. هرگونه خطای YAML (تورفتگی اشتباه ، روده بزرگ) در اینجا بارگذاری گردش کار را شکست می دهد.

پیکربندی Kubernetes

Kubernetes از YAML برای کلیه تعاریف منابع خود (غلاف ، استقرار ، خدمات و غیره) استفاده می کند. در اینجا قطعه ای از یک آشکار استقرار آورده شده است:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example
  template:
    metadata:
      labels:
        app: example
    spec:
      containers:
        - name: example-container
          image: example-image
          ports:
            - containerPort: 8080

این یک استقرار را تعریف می کند (kind: Deployment) با 3 ماکت example-container دویدن example-imageبشر به کلیدها توجه کنید apiVersionبا kindبا metadataبا spec – این کنوانسیون های Kubernetes هستند ، اما نحو YAML (تورفتگی ، لیست ها ، نقشه ها) از قوانین فوق پیروی می کند. در صورت اشتباه ساختار YAML ، پارسرهای Kubernetes پرونده را رد می کنند.

داکر آهنگسازی

آهنگسازی Docker از a استفاده می کند docker-compose.yml پرونده (YAML) برای تعریف برنامه های چند کانتینر. مثال:

version: '3'
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
  db:
    image: postgres:13
    environment:
      POSTGRES_USER: example
      POSTGRES_DB: exampledb

در اینجا services نقشه برداری از نام خدمات است (webبا db) به تنظیمات آنها. این مثال (از اسناد داکر) دو سرویس را نشان می دهد که هر کدام دارای یک تصویر و تنظیمات دیگر هستند. باز هم ، تورفتگی صحیح و نحو بسیار مهم است – به عنوان مثال ports یک لیست است ، بنابراین عناصر آن با پیشوند هستند -بشر

کتابهای پخش قابل قبول

کتابهای بازی Ansible (وظایف اتوماسیون) در YAML نوشته شده است. یک کتاب پخش ساده ممکن است به نظر برسد:

- name: Update web servers
  hosts: webservers
  tasks:
    - name: Install Apache
      ansible.builtin.yum:
        name: httpd
        state: latest
    - name: Copy config
      ansible.builtin.copy:
        src: httpd.conf
        dest: /etc/httpd.conf

این یک نمایشنامه را تعریف می کند (به پیشرو توجه کنید - در سطح بالا) که هدف قرار می دهد webservers گروه زیر tasks، هر کار نقشه برداری با a است name و ماژول برای اجرا (yumبا copy، و غیره) با استدلال های خود. yaml نادرست (مثل تورفتگی اشتباه قبل - name: Install Apache) باعث می شود که تجزیه و تحلیل کتاب پخش شود.

مثال yaml

# String
name: "John Doe"

# Integer
age: 30

# Boolean
is_active: true

# Null
address: null

# List (Array)
languages:
  - English
  - Spanish
  - French

# Map (Key-Value pairs)
contact:
  email: "johndoe@example.com"
  phone: "+1234567890"

# Nested Map
company:
  name: "Tech Innovators Inc."
  address:
    street: "123 Tech Avenue"
    city: "Innovapolis"
    country: "Techland"

# List of Maps
employees:
  - name: "Alice"
    role: "Developer"
  - name: "Bob"
    role: "Designer"
  - name: "Charlie"
    role: "Manager"

# Mixed types (Map with List)
project:
  name: "YAML Parser"
  status: "In Progress"
  team:
    - Alice
    - Bob
    - Charlie
  milestones:
    - "Design"
    - "Development"
    - "Testing"

بهترین روشها

نوشتن YAML تمیز و قابل حفظ مهم است. برخی از شیوه های پیشنهادی عبارتند از:

• نامگذاری مداوم: از کلیدهای شفاف و توصیفی به سبک یکنواخت استفاده کنید (به عنوان مثال snake_case یا camelCase). از مخفف رمزنگاری خودداری کنید. قوام به خوانایی کمک می کند.
• تورفتگی: همیشه از فضاها (بدون زبانه) برای تورفتگی استفاده کنید. استاندارد کردن 2 فاصله در هر سطحبشر تورفتگی مداوم از خطاهای سخت و سخت جلوگیری می کند.
• از پیچیدگی غیر ضروری خودداری کنید: سبک های جریان و بلوک را به روش های گیج کننده مخلوط نکنید. برای وضوح ، به سبک برای ساختارهای بزرگ یا تو در تو تبدیل شود.
• از لنگرها/نام های عاقلانه استفاده کنید: اگر چندین بخش تنظیمات یکسان را به اشتراک بگذارید ، آنها را یک بار با یک لنگر تعریف کرده و با نام مستعار استفاده مجدد کنید. این روش خشک هنگام به روزرسانی مقادیر مشترک ، خطاها را کاهش می دهد.
• نظرات: اضافه کردن نظرات (#) برای توضیح تنظیمات غیر آشکار یا دلایل مقادیر خاص. نظرات توسط پارسرها نادیده گرفته می شود اما برای خوانندگان انسانی بسیار ارزشمند است.
• اعتبار سنجی: برای اجرای قوانین سبک از yaml lineters (به عنوان مثال ، yamllint) یا ویرایشگر استفاده کنید. این ابزارها می توانند خطاهای تورفتگی ، کلیدهای تکراری و موارد دیگر را بدست آورند. همچنین ، بسیاری از سیستم ها دارای یک حالت “پیکربندی تست” هستند (مانند kubectl apply --dry-run یا ansible-playbook --syntax-check) برای تأیید YAML قبل از دویدن.
• نقل قول: وقتی شک دارید ، رشته هایی را نقل کنید که شامل شخصیت های خاص است (:با @، فضاها) یا با کلمات حساس به YAML شروع کنید. به عنوان مثال ، الگوهای Regex یا مسیرهای پرونده را در نقل قول ها برای جلوگیری از مشکلات تجزیه و تحلیل بسته بندی کنید.
• آگاهی از طرحواره: طرح مورد انتظار YAML خود را بدانید (به عنوان مثال Kubernetes API مشخصات). برخی از مقادیر باید در نقل قول ها یا یک قالب خاص باشند. در صورت وجود راهنماهای رسمی سبک را دنبال کنید (به عنوان مثال ، دستیار خانه سبک جریان را ممنوع می کند).

مشکلات و اشکال زدایی مشترک

حتی اشتباهات ساده می تواند YAML را بشکند. مراقب باشید:

• Tabs vs Spaces: استفاده از یک برگه به ​​جای فضاها باعث ایجاد خطای تجزیه می شود.
• خطاهای تورفتگی: کلیدهای نادرست (به عنوان مثال یک سطح بسیار دور از هم) ساختار را گیج می کنند. یک خطای مشترک این است mapping values are not allowed وقتی یک داش یا روده بزرگ را فراموش می کنید.
• خطوط گمشده: فراموش کردن - قبل از لیست موارد می تواند لیستی را که باید به یک کلید نقشه برداری تبدیل کند ، تبدیل شود.
• نقل قول اشتباه: کلون ها در رشته های بدون سیم یا کاراکترهای خاص می توانند پرونده را بشکنند. به عنوان مثال ، path: C:\Users اغلب باید به عنوان نوشته شود path: "C:\\Users"بشر
• سردرگمی بولی و تهی: درمان یال yesبا noبا onبا off، و بی سیم true/false مخصوصاً رشته “بله” درست می شود. اگر به رشته تحت اللفظی نیاز دارید ، آن را نقل کنید ("yes").
• صفر پیشرو: یک عدد مانند 09 بدون نقل قول به عنوان اکتال (یا شناور) تجزیه می شود و می تواند باعث ایجاد خطا شود. نقل قول چنین ارزشهایی از تفسیر نادرست جلوگیری می کند.
• کلیدهای تکراری: YAML کلیدهای تکراری را در همان نقشه برداری ممنوع می کند (برخی از تجزیه ها به آن اجازه می دهند ، اما رفتار تعریف نشده است). دو بررسی برای تایپ.

برای اشکال زدایی مسائل YAML:

• از اعتبار سنج های آنلاین یا ابزارهای خط فرمان استفاده کنید (به عنوان مثال python -c 'import yaml,sys; yaml.safe_load(sys.stdin)' < file.yaml).
• بسیاری از ویراستاران (در مقابل کد ، IntelliJ و غیره) از YAML پشتیبانی می کنند که خطاهای نحوی را برجسته می کند.
• پیام های خطا را با دقت بخوانید – آنها معمولاً شامل خط و ستون مشکل هستند.
• در صورت وجود با یک مثال یا طرحواره مقایسه کنید.

با پیروی از این دستورالعمل ها و یادگیری از مثال ، می توانید YAML قوی و قابل خواندن را برای هر مورد استفاده بنویسید.