محوّل YAML إلى JSON

ما هو JSON؟

// Convert YAML to JSON in Node.js using the eemeli/yaml library
import { parseAllDocuments } from 'yaml';

const yamlString = `apiVersion: apps/v1
kind: Deployment`;

// parseAllDocuments handles multi-document YAML (--- separator)
// version: '1.2' ensures yes/no are strings, not booleans
// merge: true expands anchor/alias merge keys (<<: *anchor)
const docs = parseAllDocuments(yamlString, { version: '1.2', merge: true });

// Take the first document (skip additional --- blocks)
const json = JSON.stringify(docs[0].toJSON(), null, 2);

console.log(json);
// {
//   "apiVersion": "apps/v1",
//   "kind": "Deployment"
// }

الميزات الرئيسية

أمثلة

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
  labels:
    app: my-app
    version: 1.0.0
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080
          resources:
            requests:
              memory: 64Mi
              cpu: 250m
            limits:
              memory: 128Mi
              cpu: 500m

version: '3.9'
services:
  web:
    image: nginx:1.25-alpine
    ports:
      - '80:80'
      - '443:443'
    environment:
      NGINX_HOST: example.com
      NGINX_PORT: '80'
    depends_on:
      - db
    restart: unless-stopped
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata: {}

name: CI
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: pnpm
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Run tests
        run: pnpm test

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
  description: Manage application users
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      summary: Get user
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

replicaCount: 3
image:
  repository: my-app
  tag: 1.0.0
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: my-app.example.com
      paths:
        - path: /
          pathType: Prefix
resources:
  requests:
    memory: 64Mi
    cpu: 250m
  limits:
    memory: 128Mi
    cpu: 500m
autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

- name: Configure web servers
  hosts: webservers
  become: true
  vars:
    http_port: 80
    max_clients: 200
  tasks:
    - name: Ensure nginx is installed
      ansible.builtin.package:
        name: nginx
        state: present
    - name: Start nginx service
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true
    - name: Copy nginx config
      ansible.builtin.template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
        owner: root
        group: root
        mode: '0644'
      notify:
        - Restart nginx
  handlers:
    - name: Restart nginx
      ansible.builtin.service:
        name: nginx
        state: restarted

كيفية الاستخدام

1. 1

   الصق بيانات YAML

   أدخل أو الصق بيانات YAML في حقل الإدخال أعلاه. يمكنك أيضاً النقر على «تحميل مثال» لتجربة عينة كبيان نشر Kubernetes أو ملف Docker Compose أو Helm values.yaml.

2. 2

   شاهد إخراج JSON مباشرة

   يظهر JSON فوراً في لوحة الإخراج. اضبط الخيارات (المسافة البادئة مسافتان أو 4 مسافات) لتتطابق مع متطلبات الأداة المستهدفة.

3. 3

   انسخ أو حمّل

   انقر على «انسخ» لنقل JSON إلى الحافظة، أو «تحميل» لحفظه كملف .json جاهز لاستخدامه مع jq أو استدعاءات API أو أي أداة لاحقة.

أخطاء YAML الشائعة

services:
	web:
		image: nginx:1.25-alpine

services:
  web:
    image: nginx:1.25-alpine

metadata:
  name: my-app
   namespace: production

metadata:
  name: my-app
  namespace: production

url: http://example.com:8080/api
tag: #latest

url: 'http://example.com:8080/api'
tag: '#latest'

# Circular anchor (rare but possible)
base: &base
  parent: *base

# Use explicit fields instead of circular references
base:
  parent: null

# Only the first document is converted
apiVersion: v1
kind: ConfigMap
---
apiVersion: v1
kind: Secret

# Convert each document separately
apiVersion: v1
kind: ConfigMap

# This comment will be lost
replicas: 3 # scale this up for production

replicas: 3
_comment: scale this up for production

حالات الاستخدام الشائعة

تحليل بيانات Kubernetes

تحويل بيانات Kubernetes YAML إلى JSON للاستعلام باستخدام jq، أو الإرسال إلى Kubernetes REST API، أو المعالجة في مصادر بيانات Terraform، أو التغذية في خطوط CI/CD التي تتوقع JSON.

تحويل Docker Compose لأدوات JavaScript

تحليل Docker Compose YAML إلى JSON لاستخراج تعريفات الخدمات وأسماء الصور وتعيينات المنافذ ومتغيرات البيئة للاستخدام في سكريبتات الأتمتة أو رسوم التبعيات أو أدوات Node.js.

تكامل GitHub Actions API

تحويل ملفات YAML لسير عمل GitHub Actions إلى JSON للتحقق من البنية برمجياً أو استخراج تعريفات المهام والخطوات أو التكامل مع واجهات برمجية لـ CI/CD تقبل مواصفات سير العمل بصيغة JSON.

تحويل OpenAPI لتوليد كود العميل

تقبل كثير من مولّدات الكود (openapi-generator، swagger-codegen) مواصفات OpenAPI بأي صيغة. حوّل مواصفة YAML إلى JSON عندما تتطلب أداة ما صراحةً مدخل JSON.

تحليل قيم Helm

تحويل ملف Helm chart values.yaml إلى JSON لتوليد التقارير أو مقارنة القيم عبر بيئات مختلفة أو تغذيتها في أدوات إنفاذ السياسات أو معالجتها بأتمتة تتوقع إعداداً بصيغة JSON.

ترحيل الإعدادات إلى أدوات قائمة على JSON

ترحيل إعداد التطبيق من YAML (شائع في أدوات البنية التحتية) إلى JSON للاستخدام في بيئات JavaScript أو واجهات REST API أو AWS AppConfig أو Azure App Configuration أو أي نظام يخزن الإعدادات بصيغة JSON.

تفاصيل تقنية

مواصفة YAML 1.2 عبر parseAllDocuments مع merge:true

يُحلَّل YAML باستخدام مكتبة eemeli/yaml (الإصدار v2.8+، آمن من الثغرات) عبر parseAllDocuments مع { version: '1.2', merge: true }. يضمن مخطط YAML 1.2 معاملة السلاسل النصية المجردة مثل yes وno كسلاسل نصية (وليس كقيم منطقية). يُوسِّع الخيار merge: true مفاتيح دمج المراسي/المراجع (<<: *anchor) بالكامل. يُعيد YAML متعدد الوثائق (مفصول بـ ---) الوثيقة الأولى.

توسيع المراسي والمراجع عبر المكتبة

تتعامل مكتبة eemeli/yaml مع توسيع المراسي (&name) والمراجع (*name) بأمان، بما في ذلك اكتشاف المراجع الدائرية. جميع كتل البيانات المُستعار إليها — بما في ذلك توسيعات مفتاح الدمج — مُضمَّنة بالكامل في إخراج JSON. هذا التحويل الصحيح إذ لا يمتلك JSON مفهوم المرسي أو المرجع. يمنع التوسيع الآمن للمكتبة الحلقات اللانهائية من YAML المشوَّه.

قائم على المتصفح — بدون رفع ملفات أو خادم

تتم جميع المعالجة كلياً في محرك JavaScript بمتصفحك. لا تُرسَل أي بيانات عبر الشبكة في أي وقت. تتحول المدخلات الأكبر من 200 كيلوبايت تلقائياً من الوضع المباشر إلى الوضع اليدوي (مطلوب نقر «تحويل» صريح) للحفاظ على استجابة المتصفح ومنع تعطّل مسار التنفيذ الرئيسي أثناء التسلسل الثقيل.

أفضل الممارسات

استخدم صياغة YAML 1.2 المتوافقة للتحويل النظيف

اكتب YAML باستخدام اتفاقيات YAML 1.2 — اقتبس قيم السلاسل النصية yes وno وon وoff وy وn صراحةً (مثلاً: enabled: 'yes') لتفادي الغموض. تُحلِّل هذه الأداة بمخطط YAML 1.2 (لذا هي سلاسل نصية)، لكن الأدوات الأقدم في خط أنابيبك قد تستخدم YAML 1.1 (حيث تصبح قيماً منطقية). الاقتباس الصريح في مصدر YAML هو الممارسة الأأمن عبر جميع المحللات.

اقتبس الأرقام الكبيرة في YAML للحفاظ على الدقة

لا يستطيع JavaScript تمثيل الأعداد الصحيحة الأكبر من 2^53 - 1 (9007199254740991) بدقة. يمكن أن تتجاوز حقول Kubernetes مثل resourceVersion وuid هذا الحد. اقتبس هذه القيم في مصدر YAML (resourceVersion: '9007199254740993') حتى يُعاملها المحلل كسلاسل نصية تُحفَظ بدقة في إخراج JSON.

تحقق من إخراج JSON قبل استخدامه في الواجهات البرمجية

بعد تحويل YAML إلى JSON، تحقق من النتيجة قبل إرسالها إلى واجهة برمجية أو تخزينها أو معالجتها برمجياً. استخدم منسّق JSON لتأكيد صحة البنية. هذا مهم بشكل خاص لاستدعاءات Kubernetes API ومواصفات OpenAPI وأي حمولة مُتحقَّق منها بـ JSON Schema.

افصل YAML متعدد الوثائق قبل التحويل

إذا احتوى ملف YAML على وثائق متعددة مفصولة بـ --- وأردت تحويلها جميعاً إلى JSON، قسّم الملف أولاً على --- وحوّل كل وثيقة بشكل منفصل. تأخذ هذه الأداة الوثيقة الأولى فقط. طريقة بسيطة: قسّم على '\n---\n' في محررك أو باستخدام awk، ثم الصق كل قسم بشكل منفصل.

استخدم jq لمعالجة JSON اللاحقة

بمجرد حصولك على JSON من YAML، يُعدّ jq الطريقة الأسرع للاستعلام وتحويله من سطر الأوامر. انسخ JSON المُحوَّل، ثم استخدم jq '.spec.replicas' أو jq '.services | keys' لاستخراج ما تحتاجه بالضبط. لمعالجة دُفعية لكثير من الملفات، استخدم واجهة yq CLI مع علم -o json مباشرة.

الأسئلة الشائعة