محول JSON إلى YAML: تحويل التكوينات دون مشكلة النرويج

في المرة الأولى التي أحرقتني فيها YAML بشكل صحيح، كان رمز البلد. كنت أقوم بنقل تكوين محلي من مشروع Laravel &#39؛s ملفات JSON إلى تنسيق YAML سهل النشر، وتحويله يدويًا أثناء تقدمي بسبب &quot؛it&#39؛s مجرد تغيير الأقواس إلى مسافة بادئة.&quot؛ أحد الإدخالات كان النرويج: "country": "NO". في YAML، غير مقتبس، that&#39؛s ليست سلسلة - بموجب قواعد YAML 1.1 التي لا يزال PyYAML والعديد من المحللين الآخرين يطبقونها NO هو المنطقي false. قام البرنامج النصي للنشر، المكتوب بلغة بايثون، بتقييم المستخدمين النرويجيين بمرح على أنهم country: false ووجههم إلى المنطقة الاحتياطية. هذا الخطأ له اسم - يسميه المجتمع مشكلة النرويج - ويجب أن أكتشفه بالطريقة الحرفية، تذكرة دعم مشوشة واحدة في كل مرة.

يبدو تحويل JSON يدويًا إلى YAML أمرًا تافهًا وهو في الواقع حقل ألغام، لأن التنسيقين لهما أفكار مختلفة تمامًا حول معنى الكلمة المجردة. في JSON، كل شيء واضح: السلاسل لها اقتباسات، والأرقام لا &#39؛ر، true/false/null هي الكلمات الرئيسية، نهاية القصة. في YAML، يتم الحصول على عدد قياسي غير مقتبس مفسرة: no يصبح كاذبا، 3000 يصبح عددا صحيحا، 1.10 يصبح تعويم 1.1 (وداعا، سلسلة الإصدار)، 08 يخنق بعض المحللين باعتبارهم ثمانيًا غير صالح، وتصبح القيمة ذات مسافة النقطتين الضالة خريطة متداخلة عندما لا تتوقعها على الإطلاق. كل واحد من هذه العناصر عبارة عن تلف صامت للبيانات - يتم توزيع الملف بشكل جيد، والأنواع خاطئة تمامًا.

أ محول JSON إلى YAML هذا الفهم لهذه القواعد يمنحك سهولة القراءة التي تم اختراع YAML من أجلها بدون نوع الروليت. يكتشف الجهاز الذي قمت بإنشائه لـ Toolz.dev كل عدد قياسي غامض - أشكال متشابهة منطقية، وأشكال متشابهة للأرقام، وقيم YAML 1.1 القديمة، والسلاسل ذات الأحرف الخاصة - ويقتبس تلك بالضبط، لذا فإن ما كان عبارة عن سلسلة في JSON الخاص بك لا يزال عبارة عن سلسلة بعد أن تقوم الأداة التالية بتحليل YAML. هذا & اقتباس؛ بالضبط تلك & اقتباس؛ الأمور: الاقتباس كل شئ سيكون آمنًا أيضًا، لكن الإخراج يتوقف عن الظهور مثل YAML الاصطلاحي، والاصطلاحي هو بيت القصيد.

يغطي هذا الدليل كيفية تعامل التحويل مع الحواف الحادة لـ YAML&#39؛s، ولماذا JSON هي من الناحية الفنية بالفعل YAML (ولماذا تساعدك هذه الحقيقة &#39؛t)، وسير عمل Kubernetes وCI وDocker Compose حيث يحدث هذا التحويل أسبوعيًا.

ليرة تركية؛DR: لصق JSON في Toolz.dev JSON إلى محول YAML، اختر مسافة بادئة مكونة من 2 أو 4 مسافات، واحصل على YAML نظيفًا على شكل كتلة مع اقتباس آمن للنوع - "3000" يبقى سلسلة، "no" يبقى سلسلة، "1.10" يبقى نسخة. يتم الحفاظ على ترتيب المفاتيح، وتظهر المجموعات الفارغة كـ [] و {}، وكل شيء يعمل من جانب العميل، لذا لا تترك أسرار متصفحك أبدًا. رحلة ذهابًا وإيابًا مع مدقق يمل، وقم بتنسيق المصدر أولاً باستخدام تنسيق JSON.

Isn&#39؛t JSON صالح بالفعل YAML؟

نعم - وit&#39؛s الأكثر عديمة الفائدة &quot؛ نعم وquot؛ في إدارة التكوين. تم تصميم YAML 1.2 بشكل صريح كمجموعة شاملة من JSON: يتم تحليل كل مستند JSON صالح على أنه YAML صالح. يمكنك لصق JSON الخام في بيان Kubernetes و kubectl سوف أقبل ذلك.

لا أحد يفعل هذا، لأن سبب وجود YAML هو بيئة العمل البشرية. بيانات Kubernetes، وسير عمل GitHub Actions، وملفات Docker Compose، وكتب تشغيل Ansible، وتكوينات Home Assistant - هذه هي YAML لأن الأشخاص يقرؤونها ويحررونها يدويًا باستمرار، و replicas: 3 ضمن كتلة ذات مسافة بادئة، يتم المسح بشكل أفضل من {"replicas":3} متداخلة بين قوسين. عندما يقول شخص ما &quot؛ تحويل JSON إلى YAML، &quot؛ يقصدون نمط الكتلة YAML: المسافة البادئة بدلاً من الأقواس، - الشرطات بدلاً من المصفوفات بين قوسين، لا توجد علامات اقتباس حيث لا حاجة لأي علامات اقتباس.

هذه الجملة الأخيرة هي المكان الذي تعيش فيه الصعوبة. الانتقال من بناء الجملة الصريح لـ JSON&#39؛ إلى الحد الأدنى من بناء الجملة لـ YAML&#39؛s تحديد، لكل سلسلة، ما إذا كان يمكنها فقدان علامات الاقتباس الخاصة بها بأمان- ويتطلب هذا القرار معرفة قواعد الدقة العددية لـ YAML&#39؛s بشكل أفضل مما يفعله معظم البشر بشكل موثوق في الساعة 5 مساءً يوم الجمعة. تلك &#39؛s الوظيفة الفعلية للمحول؛ الجزء من الأقواس إلى المسافة البادئة تافه.

ما الذي ينكسر بصمت عندما تقوم بالتحويل يدويًا؟

تنقسم حالات الفشل إلى أربع عائلات، وI&#39؛ لقد ضرب كل واحد منهم في التكوينات الحقيقية:

تبدو منطقية متشابهة. YAML 1.1 يحل yes، no، on، off، y، n (في أغلفة مختلفة) كأشكال منطقية، ويحتفظ YAML 1.2 true/false. PyYAML - لا تزال مكتبة YAML الافتراضية في معظم قواعد بيانات Python - تنفذ 1.1. لذا "debug": "no" تم تحويلها يدويا إلى debug: no يصبح debug: false في أدوات نشر Python الخاصة بك. مشكلة النرويج (NO → false) وابن عمها مشكلة أونتاريو (ON → true) هل هذه العائلة &#39؛ أعظم الزيارات.

عدد يشبه. "port": "3000" تحولت إلى port: 3000 أصبح الآن عددًا صحيحًا. Kubernetes لا &#39؛ الرعاية في بعض المجالات والإخفاقات الشديدة في مجالات أخرى - على سبيل المثال، يجب أن تكون قيم env var عبارة عن سلاسل، و kubectl apply سيتم رفض عدد صحيح هناك مع وجود خطأ يسمي الحقل ولكن ليس لماذا. سلاسل الإصدار أسوأ لأنه لا شيء يفشل: version: 1.10 يوزع كما تعويم 1.1، وسيقوم البرنامج النصي للنشر الخاص بك بالإبلاغ عن الإصدار الخاطئ إلى الأبد. الأصفار البادئة - الرموز البريدية، وأرقام الهواتف، والمعرفات ذات المظهر الثماني مثل 0755- تقريب الأسرة.

شخصيات خاصة. تبدأ النقطتين المتبوعتين بمسافة داخل قيمة غير مسعرة في التعيين (message: error: not found هو خطأ تحليل أو خريطة متداخلة، يعتمد المحلل اللغوي). أ # يبدأ التعليق بقيمة متوسطة. القيادة *، &، ! تصطدم بمرساة YAML&#39؛ والاسم المستعار وبناء جملة العلامة. تحتاج السلاسل ذات الأسطر الجديدة إلى الهروب أو حظر الكميات القياسية.

السلسلة الفارغة. الفراغ غير المقتبس في YAML هو nullلا "". يجب أن يخرج أي حقل JSON يحتوي على سلسلة فارغة مقتبسًا وإلا فإنه يتغير نوعه.

ال محول يتحقق من كل سلسلة مقابل العائلات الأربع ويقتبس تلك التي تحتاج إليها - وتلك فقط. production يخرج عاريًا لأنه &#39؛s لا لبس فيه؛ "3000"، "no"، "1.10"، و "" اخرج مقتبسة لأنها &#39؛t. هناك&#39؛s أيضًا &quot؛ اقتبس جميع السلاسل والاقتباس؛ قم بالتبديل عندما تقوم أنت و#39؛ بإعادة تغذية المحلل اللغوي الذي لا تفعله &#39؛ الثقة وتريد حدوث دقة عددية صفرية على الإطلاق.

كيف يمكنك تحويل JSON إلى YAML باستخدام الأداة؟

الخطوة 1: الصق JSON الخاص بك

أي أعمال JSON صالحة - كائنات، مصفوفات، تداخل عميق، يونيكود. يمنحك زر تحميل العينة تكوين خدمة واقعيًا يمارس الحالات المثيرة للاهتمام: منفذ سلسلة رقمية، ومنطقي، ومصفوفة فارغة، وخرائط متداخلة. إذا كان إدخالك به مشكلات في بناء الجملة، فسيقوم المحول بالإبلاغ عن الخطأ الدقيق للمحلل &#39؛ بدلاً من تحويل مستند مقطوع؛ للصيد أين الخطأ في نقطة كبيرة، تنسيق JSON هو المجهر الأفضل.

الخطوة 2: اختر المسافة البادئة

مسافتان أو أربعة. اثنان هو التقليد الساحق - مستندات Kubernetes، وأمثلة GitHub Actions، ومراجع Docker Compose، و yamllint تستخدمه جميع الإعدادات الافتراضية - لكن بعض الفرق تقوم بتوحيد أربعة منها لسهولة القراءة في التداخل العميق. أيًا كان اختيارك، فإن المحول متسق بشأنه، بما في ذلك الحالة الدقيقة لعناصر القائمة أسفل المفتاح، حيث تكون المسافة البادئة غير المتسقة لليد مصدرًا كلاسيكيًا لـ &quot؛ لا يُسمح بتعيين القيم هنا والاقتباس؛ أخطاء.

الخطوة 3: التحويل والمراجعة

يظهر الإخراج مع عدد الأسطر والبايت. قم بتصفحه مرة واحدة - ليس من أجل الصحة (that&#39؛s وظيفة المحول&#39؛s) ولكن للتحقق من سلامة قرارات الاقتباس مقابل توقعاتك. يرى PORT: "3000" نقلت بينما NODE_ENV: production isn&#39؛t هي الأداة التي تخبرك بالقيم التي كانت خطيرة.

الخطوة 4: النسخ أو التنزيل

انسخ إلى الحافظة للصقها في بيان موجود، أو قم بتنزيلها كـ .yaml ملف. يستخدم الإخراج مسافات فقط - يحظر YAML علامات التبويب للمسافة البادئة، وهو أمر يستحق المعرفة عند تحرير الملف لاحقًا في محرر تم تكوينه للمسافة البادئة لعلامة التبويب.

JSON vs YAML: متى يفوز كل تنسيق؟

النمط الموجود خلف الطاولة: يفوز JSON أينما تكتب الآلة وتقرأ الآلة؛ يفوز YAML أينما تقرأ الآلة ولكن أ إنسان يكتب. يقع التكوين بشكل مباشر في الفئة الثانية، ولهذا السبب يعد اتجاه JSON-to-YAML هو الاتجاه الشائع - تبدأ البيانات في واجهة برمجة التطبيقات أو تصدير قاعدة البيانات وتحتاج إلى أن تصبح شيئًا يمكن لفريق العمليات الحفاظ عليه. الرحلة العكسية، YAML العودة إلى JSON المقروء آليًا، هي ما مدقق يمل المقابض - لصق YAML، واحصل على التحقق بالإضافة إلى JSON المكافئ.

ما هي سير العمل اليومي لهذا التحويل؟

يظهر Kubernetes من إخراج API

kubectl get deployment my-app -o json يعطيك JSON؛ البيان الذي قمت بالتحقق منه في Git هو YAML. يعد تحويل استجابات واجهة برمجة التطبيقات إلى YAML نظيف أسرع طريقة لتشغيل بيان من مورد مباشر - التحويل، وتجريد الخادم من البيانات المأهولة status و metadata.managedFields الكتل، ولديك نقطة بداية تعريفية. الاقتباس الآمن للنوع يكسب الاحتفاظ به هنا: قيم env في Kubernetes يجب be سلاسل، والمحول &#39؛s الإصرار على الاقتباس "3000" هو الفرق بين kubectl apply النجاح والفشل.

تكوين خط أنابيب CI

إجراءات GitHub وGitLab CI هي YAML فقط. عندما I&#39؛ إنشاء خطوات سير العمل برمجيًا - مصفوفة من إصدارات PHP وNode لاختبار WP Adminify مقابل، على سبيل المثال - ينتج المولد JSON بشكل طبيعي، والخطوة الأخيرة هي التحويل. سلاسل الإصدارات في مصفوفات الاختبار هي بالضبط القيم التي يتم تشويهها عن طريق التحويل الساذج: مصفوفة من ["1.9", "1.10", "1.11"] تم تحويله يدويًا بدون اختبارات الاقتباس ضد PHP 1.1 مرتين. ال جمع أدوات الترميز يغطي المزيد من نمط الإنشاء ثم التحويل هذا.

عامل الإرساء يؤلف من فحص الإخراج

docker inspect ينبعث JSON؛ docker-compose.yml يريد YAML. الهندسة العكسية لملف Compose من حاوية قيد التشغيل - المنافذ، ووحدات التخزين، وenv - هي مهمة التحويل والتقليم. تحويل المصفوفات والكائنات الفارغة إلى [] و {} بناء جملة التدفق، الذي يقبله Compose والذي يبقي مرحلة التقليم قابلة للقراءة.

جعل التكوين قابلاً للمراجعة

تم الاستهانة بهذا: تكوينات JSON التي تحتوي على العشرات من المفاتيح المتداخلة بائسة في مراجعة التعليمات البرمجية، ويرجع ذلك جزئيًا إلى أنها يمكن أن تحمل تعليقات &#39؛t. يتيح لك التحويل إلى YAML إضافة تعليقات توضيحية لماذا rateLimit هو 250 بجوار القيمة مباشرة. بالنسبة للمراجعة نفسها، قم بإقران التحويل بـ الفرق الهيكلي قبل/بعد JSON يحتفظ بـ &quot؛ ما الذي تغير بالفعل واقتباس؛ سؤال صادق بينما يتعامل إصدار YAML مع &quot؛ لماذا.&quot؛

OpenAPI ووثائق المخطط

يتم تأليف مواصفات OpenAPI بشكل شائع في YAML ولكن يتم إنشاؤها واستخدامها كـ JSON. يعد تحويل المواصفات التي تم إنشاؤها إلى YAML للتحرير البشري - ثم التحقق من صحة الرحلة ذهابًا وإيابًا - هو سير عمل قياسي لفريق API، وضمانات الدقة (تم الحفاظ على ترتيب المفاتيح، والأنواع المقتبسة) تعني أن إصدار YAML يظل قابلاً للاختلاف مقابل سلف JSON الخاص به.

لماذا يهم الحفاظ على الطلب الرئيسي؟

وفقًا لمواصفات JSON، لا يحمل ترتيب مفتاح الكائن أي معنى - {"a":1,"b":2} و {"b":2,"a":1} هي نفس الكائن. لذلك يمكن للمحول فرز المفاتيح أبجديًا ويكون صحيحًا من الناحية الفنية. سيكون أيضًا عدائيًا عمليًا، لأن ملفات التكوين كذلك يقرأ بالترتيب: يُقرأ نشر Kubernetes بشكل طبيعي على النحو التالي apiVersion، kind، metadata، spec- يؤدي فرزها أبجديًا إلى ظهور بيان يتم تحليله بشكل متطابق ويقرأ مثل مذكرة الفدية.

يقوم المحول بإصدار المفاتيح بترتيب المصدر. ينجو النموذج العقلي الخاص بك للمستند من التحويل، ويختلف YAML بشكل واضح عن التحويلات السابقة لنفس المصدر، والترتيبات التقليدية (الاسم قبل القيمة، apiVersion أولا) البقاء التقليدية. إذا كنت يريد الترتيب الأساسي لأغراض المقارنة، that&#39؛s هو اهتمام مختلف بالأداة - مدقق فرق JSON تتم المقارنة حسب المفتاح بغض النظر عن الترتيب، وهي الطبقة المناسبة لهذه المشكلة.

هل من الآمن تحويل التكوينات التي تحتوي على أسرار؟

التكوين هو النص الأكثر سرية الذي يتعامل معه المطور - عناوين URL لقاعدة البيانات مع كلمات المرور المضمنة، ورموز API المميزة في كتل env، وأسماء المضيفين الداخلية التي تحدد البنية التحتية الخاصة بك. It&#39؛s أيضًا بالضبط ما يلصقه الأشخاص في المحولات عبر الإنترنت، عادةً في منتصف النشر، وعادةً ما يكون ذلك على عجل.

ال محول Toolz.dev يعمل بالكامل في متصفحك: التحليل والتحليل العددي والتسلسل - كل ذلك من جانب العميل JavaScript، ولا يحمل أي طلب شبكة بياناتك، وتستمر الأداة في العمل مع قطع الاتصال الخاص بك. That&#39؛s حقيقة معمارية، وليست وعدًا بسياسة الخصوصية. تم وضع فلسفة تصميم المتصفح أولاً وراء صندوق الأدوات بأكمله في دليل مجموعة أدوات مطور الويب؛ هذه الأداة هي تلك الفلسفة المطبقة على نوع المستند الأكثر حساسية في سير عملك.

التحذير الواضح يقف: التحويل من جانب العميل يحمي تحويل. المكان الذي تقوم فيه بلصق المخرجات بعد ذلك هو قرار أمني خاص به.

أسئلة وأجوبة

كيف يمكنني تحويل JSON إلى YAML عبر الإنترنت؟

لصق JSON الخاص بك في محول JSON إلى YAML، اختر مسافة بادئة مكونة من 2 أو 4 مسافات، ثم انقر فوق تحويل. تحصل على YAML على شكل كتلة مع اقتباس آمن للكتابة، وجاهز للنسخ أو التنزيل كملف. يتم تشغيل التحويل بالكامل في متصفحك - ولا يتم تحميل أي شيء.

هل JSON صالح بالفعل لـ YAML؟

من الناحية الفنية نعم - YAML 1.2 عبارة عن مجموعة شاملة من JSON، لذا فإن أي مستند JSON صالح يتم تحليله كـ YAML. لكن بناء جملة JSON يهزم غرض سهولة القراءة في YAML&#39؛s. يؤدي التحويل إلى إنتاج YAML على شكل كتلة مع مسافة بادئة بدلاً من الأقواس، وهو ما يظهره Kubernetes وسير عمل CI وملفات Compose التي يتوقع البشر قراءتها وتحريرها.

ما هي مشكلة النرويج في YAML؟

بموجب قواعد YAML 1.1 العددية، والتي لا يزال المحللون مثل PyYAML يطبقونها، يتم تحليل القيم غير المقتبسة لا، نعم، تشغيل، وإيقاف كمنطقيات - لذلك يصبح رمز البلد NO خاطئًا بصمت. يمنع المحول ذلك عن طريق اقتباس أي سلسلة يمكن لمحلل YAML تفسيرها تلقائيًا على أنها منطقية أو رقم أو فارغة.

هل السلاسل الرقمية مثل &quot؛3000&quot؛ البقاء سلاسل بعد التحويل؟

نعم. يكتشف المحول السلاسل التي تشبه الأرقام ويقتبسها في الإخراج، so &quot؛3000&quot؛ تظل سلسلة بدلاً من أن تصبح العدد الصحيح 3000. وهذا مهم بالنسبة للمنافذ وأرقام الإصدارات مثل &quot؛1.10&quot؛ (والتي قد يتم اقتطاعها إلى float 1.1)، والرموز البريدية، والمعرفات ذات الأصفار البادئة.

هل يحافظ المحول على ترتيب مفاتيح json الخاصة بي؟

نعم. يتم إصدار المفاتيح بالترتيب الذي تظهر به في المصدر JSON. سيكون فرز المفاتيح صالحًا من الناحية الفنية - ترتيب كائن JSON لا يحمل أي معنى لكل منها RFC 8259- لكن ترتيب المصدر يبقي التكوينات قابلة للقراءة في بنيتها التقليدية ويحافظ على YAML قابلاً للتغيير مقابل مصدر JSON الخاص به.

هل يمكنني استخدام الإخراج مباشرة في Kubernetes أو Docker Compose؟

نعم. الإخراج عبارة عن YAML بنمط الكتلة القياسي مع مسافة بادئة بمسافات (لا توجد علامات تبويب أبدًا)، والتي يقبلها كل من kubectl وDocker Compose وGitHub Actions وGitLab CI. القيم التي يجب أن تكون سلاسل - مثل قيم Kubernetes env var - يتم اقتباسها، مع تجنب أخطاء الكتابة التي يثيرها kubectl على الأرقام غير المقتبسة.

كيف يمكنني تحويل YAML مرة أخرى إلى JSON؟

استخدم مدقق يمل على Toolz.dev - يقوم بتحليل YAML الخاص بك، والإبلاغ عن أي أخطاء في بناء الجملة، وإخراج JSON المكافئ. جنبًا إلى جنب مع محول JSON إلى YAML، فإنه يمنحك رحلة ذهابًا وإيابًا كاملة بين التنسيقين.

هل من الآمن تحويل ملفات التكوين التي تحتوي على أسرار؟

نعم. يتم تشغيل التحويل بالكامل بلغة JavaScript في متصفحك - لا يوجد طلب شبكة يحمل بياناتك، ولا يتم تخزين أي شيء أو تسجيله، وتعمل الأداة دون اتصال بالإنترنت. التكوينات باستخدام بيانات اعتماد قاعدة البيانات أو رموز API المميزة أو أسماء المضيفين الداخلية لا تترك جهازك أبدًا.

تعد سهولة القراءة في YAML&#39؛s حقيقية، وكذلك حوافها الحادة - فالتنسيق يحل الأنواع من السياق، والسياق هو بالضبط ما يحدث من خطأ في تحويل اليد. يمنحك المحول الذي يعرف القواعد العددية التكوين القابل للقراءة دون تلف النوع الصامت تحويل JSON الخاص بك، قم بتصفح الاقتباس الذي اختارته، وقم بشحن بيان حيث لا تزال النرويج دولة.