ממיר JSON ל-YAML: המר קונפיגים ללא בעיית נורבגיה

בפעם הראשונה YAML שרף אותי כראוי, זה היה קוד מדינה. הייתי העברת תצורה מקומית מתוך פרויקט Laravel 's קבצי JSON לתוך פורמט YAML ידידותי לפריסה, המיר ביד כפי שהלכתי כי "it's רק שינוי סוגרים להזחה." אחד הערכים היה נורבגיה: "country": "NO". ב-YAML, ללא ציטוט, that' אינו מחרוזת - תחת כללי YAML 1.1 ש-PyYAML והרבה מנתחים אחרים עדיין חלים, NO האם הבוליאני false. סקריפט הפריסה, שנכתב ב-Python, העריך בעליזות משתמשים נורבגיים בתור country: false וניתב אותם למקום החזרה לבאג הזה יש שם - הקהילה קוראת לזה בעיית נורבגיה - ואני חייב לגלות את זה בדרך המלאכותית, כרטיס תמיכה מבולבל אחד בכל פעם.

המרת JSON ביד ל-YAML נראית טריוויאלית והיא למעשה שדה מוקשים, מכיוון שלשני הפורמטים יש רעיונות שונים בתכלית לגבי המשמעות של מילה חשופה. ב-JSON, הכל מפורש: למחרוזות יש ציטוטים, מספרים don't, true/false/null הן מילות מפתח, סוף הסיפור ב-YAML, סקלר לא מצוטט מקבל פירשו: no הופך לשקר, 3000 הופך למספר שלם, 1.10 הופך לצוף 1.1 (להתראות, מחרוזת גרסה), 08 חונק חלק מהנתחים כאוקטלי לא חוקי, וערך עם רווח נקודתיים תועה הופך למפה מקוננת כשהכי פחות מצפים לה. כל אחד מאלה הוא השחתת נתונים שקטה - הקובץ מנתח בסדר, הסוגים פשוט שגויים.

א ממיר JSON ל-YAML שמבין את הכללים האלה משיג לך את הקריאות YAML הומצא עבור ללא הסוג רולטה. זה שבניתי עבור Toolz.dev מזהה כל סקלר מעורפל - בוליאני look-alikes, number look-alikes, YAML 1.1 ערכי מורשת, מחרוזות עם תווים מיוחדים - ומצטט בדיוק את אלה, אז מה שהיה מחרוזת ב-JSON שלך הוא עדיין מחרוזת לאחר שהכלי הבא מנתח את YAML. זה "בדיוק אלה" משנה: ציטוט הכל יהיה בטוח גם, אבל הפלט מפסיק להיראות כמו YAML אידיומטי, ואידיומטי זה כל העניין.

מדריך זה מכסה כיצד ההמרה מטפלת ב-YAML' קצוות חדים, מדוע JSON טכנית כבר YAML (ולמה העובדה הזו עוזרת לך ' לא עוזרת לך), ואת זרימות העבודה של Kubernetes, CI ו-Docker Compose שבהן ההמרה הזו מתרחשת מדי שבוע.

TL;DR: הדבק JSON לתוך Toolz.dev JSON ל YAML ממיר, בחר הזחה של 2 או 4 רווחים, וקבל YAML נקי בסגנון בלוק עם ציטוט בטוח - "3000" נשאר חוט, "no" נשאר חוט, "1.10" נשאר גרסה סדר מפתח נשמר, אוספים ריקים יוצאים כמו [] ו {}, והכל פועל בצד הלקוח כך שמגדיר עם סודות לעולם לא עוזב את הדפדפן שלך. הלוך ושוב עם ה מאמת יאמל, ופרמט את המקור תחילה עם פורמט JSON.

האם't JSON כבר תקף YAML?

כן - וזה's "yes&quot הכי חסר תועלת; בניהול תצורה. YAML 1.2 תוכנן במפורש כערכת-על של JSON: כל מסמך JSON חוקי מנתח כ-YAML חוקי. אתה יכול להדביק JSON גולמי במניפסט של Kubernetes ו kubectl היה מקבל את זה.

אף אחד לא עושה את זה, כי הסיבה שקיימת YAML היא ארגונומיה אנושית. מניפסטים של Kubernetes, זרימות עבודה של GitHub Actions, קבצי Docker Compose, ספרי משחק של Ansible, תצורות Home Assistant - אלה הם YAML כי אנשים קוראים ועורכים אותם ביד כל הזמן, ו replicas: 3 תחת בלוק מחורץ סריקות טובות יותר מ {"replicas":3} מקונן בפלטה. When someone says "convert JSON to YAML," they mean בסגנון בלוק YAML: הזחה במקום פלטה, - מקפים במקום מערכים בסוגריים, אין ציטוטים שבהם אין צורך באף אחד.

הסעיף האחרון הזה הוא המקום שבו הקושי חי. מעבר מ-JSON's תחביר מפורש לכל דבר ל-YAML's אמצעי תחביר מינימליים החלטה, עבור כל מחרוזת, אם היא יכולה לאבד בבטחה את הציטוטים שלה- וההחלטה הזו מחייבת להכיר את YAML' כללי הרזולוציה הסקלרית טובים יותר ממה שרוב בני האדם עושים באופן אמין ב-5 בערב ביום שישי. That's העבודה בפועל של ממיר; החלק של הפלטה לכניסה הוא טריוויאלי.

מה נשבר בשקט כשאתה ממיר ביד?

מקרי הכישלון מתחלקים לארבע משפחות, ו-I' פגעו בכל אחת מהן בתצורות אמיתיות:

דומים בוליאניים. 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) האם המשפחה הזו ' הלהיטים הגדולים ביותר.

מספר דומה. "port": "3000" הוסב ל port: 3000 הוא כעת מספר שלם. Kubernetes does ' אכפת בתחומים מסוימים וכשלים קשים באחרים - ערכי env var, למשל, חייבים להיות מחרוזות, ו kubectl apply ידחה שם מספר שלם עם שגיאה ששמה את השדה אך לא את למה. מחרוזות גרסה גרועות יותר כי שום דבר לא נכשל: version: 1.10 מנתח כמו הציפה 1.1, ואת סקריפט הפריסה שלך בשמחה מדווח על הגרסה הלא נכונה לנצח. Leading אפסים - מיקודים, מספרי טלפון, אוקטלי-מראה מזהים כמו 0755- סיים את המשפחה.

דמויות מיוחדות. נקודתיים ואחריו רווח בתוך ערך לא מצוטט מתחיל מיפוי (message: error: not found האם שגיאת ניתוח או מפה מקוננת, מנתח תלוי). א # מתחיל הערה באמצע ערך. מוֹבִיל *, &, ! התנגש עם YAML's עוגן, כינוי ותחביר תג. מחרוזות עם קווים חדשים צריכים לברוח או לחסום סקלרים.

המחרוזת הריקה. ריקנות לא מצוטטת ב-YAML היא null, לא "". כל שדה JSON המחזיק מחרוזת ריקה חייב לצאת מצוטט או שהוא משנה סוג.

ה ממיר בודק כל מחרוזת מול כל ארבע המשפחות ומצטט את אלה שזקוקים לה - ורק את אלה. production יוצא חשוף כי זה 's חד משמעי; "3000", "no", "1.10", ו "" צא מצוטט כי הם 't. There's גם "צטט את כל המחרוזות" החלף כאשר אתה ' מאכילים מנתח שאתה עושה ' לא סומך ורוצה שתתרחש רזולוציה סקלרית אפסית בכלל.

איך ממירים JSON ל-YAML עם הכלי?

שלב 1: הדבק את ה-JSON שלך

כל עבודות JSON חוקיות - אובייקטים, מערכים, קינון עמוק, יוניקוד. כפתור טען מדגם נותן לך תצורת שירות מציאותית שמפעילה את המקרים המעניינים: יציאת מחרוזת מספרית, בוליאנית, מערך ריק, מפות מקוננות. אם לקלט שלך יש בעיות תחביר, הממיר מדווח על ה-parser's שגיאה מדויקת במקום המרת מסמך קטום; לציד איפה השגיאה היא בכתם גדול, ה פורמט JSON הוא המיקרוסקופ הטוב יותר.

שלב 2: בחר הזחה

שני חללים או ארבעה. שניים הם המוסכמה המוחצת - מסמכי Kubernetes, דוגמאות של GitHub Actions, הפניות של Docker Compose וה- yamllint ברירת המחדל של כולם משתמשים בו - אבל חלק מהצוותים מתקנים על ארבע לקריאה בקינון עמוק. מה שתבחר, הממיר עקבי לגביו, כולל המקרה העדין של פריטי רשימה מתחת למפתח, שבו הזחה ידנית לא עקבית היא מקור קלאסי של " ערכי מיפוי אינם מותרים כאן" שגיאות.

שלב 3: המר וסקירה

הפלט מופיע עם ספירת שורות ובייטים. Skim it once - not for correctness (that's the converter's job) but to sanity-check the quoting decisions against your expects.Seeing PORT: "3000" מצוטט בעוד NODE_ENV: production isn't הוא הכלי שאומר לך אילו ערכים היו מסוכנים.

שלב 4: העתק או הורד

העתק ללוח להדבקה במניפסט קיים, או הורד בתור א .yaml קובץ.הפלט משתמש ברווחים בלבד - YAML אוסר על כרטיסיות להזחה, מה שכדאי לדעת מתי אתה עורך מאוחר יותר את הקובץ בעורך המוגדר להזחה של כרטיסיות.

JSON נגד YAML: מתי כל פורמט מנצח?

התבנית מאחורי השולחן: JSON מנצח בכל מקום שמכונה כותבת ומכונה קוראת; YAML מנצח בכל מקום שמכונה קוראת מלבד א אנושי כותב. תצורה יושבת באופן ישיר בקטגוריה השנייה, וזו הסיבה שהכיוון JSON-to-YAML הוא הנפוץ - נתונים מתחילים חיים ב-API או בייצוא מסד נתונים וצריכים להפוך למשהו שצוות מבצעים יכול לשמור. הנסיעה לאחור, YAML חזרה ל-JSON קריא במכונה, היא מה מאמת יאמל ידיות - הדבק YAML, קבל אימות בתוספת JSON המקביל.

מהם זרימות העבודה היומיומיות עבור המרה זו?

Kubernetes מניפסטים מ-API Output

kubectl get deployment my-app -o json נותן לך JSON; המניפסט שאתה בודק ב-Git הוא YAML. המרת תגובות API ל-YAML נקי היא הדרך המהירה ביותר לאתחל מניפסט ממשאב חי - המר, הסר את השרת המאוכלס status ו metadata.managedFields בלוקים, ויש לך נקודת התחלה הצהרתית הציטוט בטוח לסוג מרוויח את השמירה שלו כאן: ערכי env ב-Kubernetes חייב היו מחרוזות, והממיר's מתעקשים לצטט "3000" הוא ההבדל בין kubectl apply מצליח ונכשל.

תצורת צינור CI

GitHub Actions ו-GitLab CI הם YAML בלבד. כאשר I'm יוצר שלבי זרימת עבודה באופן פרוגרמטי - מטריצה של גרסאות PHP ו-Node לבדיקת WP Adminify נגד, נניח - המחולל מייצר באופן טבעי JSON, והשלב האחרון הוא המרה. מחרוזות גרסה במטריצות בדיקה הן בדיוק הערכים שמתעסקים בהמרה נאיבית: מטריצה של ["1.9", "1.10", "1.11"] מומר ביד ללא הצעות מחיר בדיקות מול PHP 1.1 פעמיים. ה איסוף כלי קידוד מכסה יותר מהדפוס הזה של יצירה ואז המרה.

Docker Compose מ- Inspect Output

docker inspect פולט JSON; docker-compose.yml רוצה YAML.הנדסה לאחור של קובץ Compose ממיכל פועל - יציאות, נפחים, env - היא עבודת המרה ושזיפה. מערכים ואובייקטים ריקים מומרים אליהם [] ו {} תחביר זרימה, ש-Compose מקבל ושומר על שלב הגיזום קריא.

הפיכת Config לניתנת לביקורת

זה לא מוערך: JSON configs עם עשרות מפתחות מקוננים אומללים בסקירת קוד, בין השאר בגלל שהם יכולים 't לשאת הערות. המרה ל-YAML מאפשרת לך להעיר למה rateLimit הוא 250 ממש ליד הערך עבור הסקירה עצמה, זיווג ההמרה עם a הבדל מבני של לפני/אחרי JSON שומר את " מה בעצם שינה" שאלה כנה בעוד שגרסת YAML מטפלת ב-"למה."

OpenAPI ומסמכי סכימה

מפרטי OpenAPI נכתבים בדרך כלל ב-YAML אך נוצרים ומשמשים כ-JSON. המרת מפרט שנוצר ל-YAML לעריכה אנושית - ולאחר מכן אימות הנסיעה הלוך ושוב - היא זרימת עבודה סטנדרטית של צוות API, והבטחות הנאמנות (סדר מפתח נשמר, סוגים מצוטטים) אומרות שגרסת YAML נשארת ניתנת לשינוי מול האב הקדמון של JSON.

מדוע שימור הזמנות מפתח משנה?

לפי מפרט JSON, סדר מפתח אובייקט אינו נושא משמעות - {"a":1,"b":2} ו {"b":2,"a":1} האם אותו אובייקט אז ממיר יכול למיין מפתחות בסדר אלפביתי ולהיות נכון מבחינה טכנית זה גם יהיה עוין מעשית, כי קבצי תצורה הם לקרוא לפי הסדר: פריסת Kubernetes נקראת באופן טבעי כ apiVersion, kind, metadata, spec- מיון אלה בסדר אלפביתי מייצר מניפסט המנתח באופן זהה ונקרא כמו שטר כופר.

הממיר פולט מפתחות בסדר מקור המודל המנטלי שלך של המסמך שורד את ההמרה, ה-YAML שונה בצורה נקייה מול המרות קודמות של אותו מקור, וסדר קונבנציונלי (שם לפני ערך, apiVersion ראשית) הישאר קונבנציונלי. אם אתה רוצה סדר קנוני למטרות השוואה, כי ' הוא עניין של כלי הבדל - ה בודק הבדל JSON משווה לפי מפתח ללא קשר לסדר, שהוא השכבה הנכונה לבעיה זו.

האם זה בטוח להמיר תודות המכילות סודות?

תצורה היא הטקסט הצפוף ביותר בסוד שמפתח מטפל בו - כתובות אתרים של מסד נתונים עם סיסמאות משובצות, אסימוני API בבלוקים של env, שמות מארח פנימיים שממפים את התשתית שלך. It' זה גם בדיוק מה שאנשים מדביקים לממירים מקוונים, בדרך כלל באמצע פריסה, בדרך כלל ממהרים.

ה Toolz.dev ממיר פועל כולו בדפדפן שלך: ניתוח, ניתוח סקלרי, סדרה - הכל הוא JavaScript בצד הלקוח, אף בקשת רשת לא נושאת את הנתונים שלך, והכלי ממשיך לעבוד עם חיתוך החיבור שלך. That' היא עובדת ארכיטקטורה, לא הבטחה למדיניות פרטיות. פילוסופיית העיצוב הראשונה של הדפדפן מאחורי כל ארגז הכלים מונחת ב- מדריך ערכת כלים למפתחי אינטרנט; הכלי הזה הוא הפילוסופיה המיושמת על סוג המסמך הרגיש ביותר בזרימת העבודה שלך.

האזהרה הברורה עומדת בעינה: המרה בצד הלקוח מגנה על המרה. המקום שבו אתה מדביק את הפלט לאחר מכן הוא החלטת האבטחה שלו.

שָׁוא

כיצד אוכל להמיר את JSON ל-YAML באינטרנט?

הדבק את ה-JSON שלך לתוך ממיר JSON ל-YAML, בחר הזחה של 2 או 4 רווחים, ולחץ על המר. אתה מקבל YAML בסגנון בלוק עם ציטוט בטוח, מוכן להעתקה או הורדה כקובץ.yaml. ההמרה פועלת כולה בדפדפן שלך - שום דבר לא מועלה.

האם JSON כבר תקף YAML?

טכנית כן - YAML 1.2 הוא superset של JSON, אז כל מסמך JSON תקף מנתח כמו YAML. אבל תחביר JSON מביס YAML's מטרת קריאות. המרה מייצרת YAML בסגנון בלוק עם הזחה במקום סוגרים, וזה מה ש-Kubernetes מבטא, זרימות עבודה של CI וקבצים Compose מצפים מבני אדם לקרוא ולערוך.

מהי בעיית נורבגיה ב-YAML?

לפי הכללים הסקלרים של YAML 1.1, שמנתחים כמו PyYAML עדיין חלים, הערכים הלא מצוטטים לא, כן, הפעלה וכיבוי מנתחים כבוליאנים - כך שקוד המדינה NO הופך בשקט לשקרי. הממיר מונע זאת על ידי ציטוט אוטומטי של כל מחרוזת שמנתח YAML יכול לפרש כבוליאני, מספר או ריק.

האם מחרוזות מספריות יאהבו את "3000" להישאר מחרוזות לאחר ההמרה?

כן. הממיר מזהה מחרוזות שנראות כמו מספרים ומצטט אותן בפלט, אז "3000" נשאר מחרוזת במקום להפוך למספר השלם 3000. זה חשוב ליציאות, מספרי גרסאות כמו "1.10" (שאחרת היה נקטע לצוף 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' הקריאות היא אמיתית, וכך גם הקצוות החדים שלו - הפורמט פותר טיפוסים מהקשר, והקשר הוא בדיוק מה שהמרת יד משתבשת. ממיר שיודע את הכללים הסקלרים נותן לך את התצורה הניתנת לקריאה ללא השחתת הסוג השקט: המר את ה-JSON שלך, רפרף על הציטוט שבחרה, ושלח מניפסט שבו נורבגיה היא עדיין מדינה.