ביליתי אחר צהריים בשנה שעברה בניפוי באגים בקובץ ערכי Helm שקולגה נשבע שהוא נכון כל מפתח נראה נכון השירות סירב להתחיל האשם התברר כארבע דמויות: NO כקוד מדינה, ללא ציטוט, ברשימת אזורים מנתח YAML קרא אותו כבוליאני false, התבנית מעובדת false לתוך כותרת, והבקשה נדחתה במורד הזרם עם הודעת שגיאה שלא הזכירה לא YAML ולא נורבגיה. הבאג הזה מפורסם מספיק כדי שיהיה לו שם - בעיית נורבגיה - והוא רק אחד ממשפחת הפתעות שמחכה בפורמט שרובנו מתייחסים אליו כאל "JSON עם רווח לבן יותר."
TL;DR: ה ממיר YAML ל-JSON מנתח מסמך YAML ומדפיס את ה-JSON המקביל, פותר עוגנים, כינויים, מפתחות מיזוג וסקלרי בלוקים לאורך הדרך. לראות את התצורה שלך כ-JSON מראה לך בדיוק מה המנתח החליט שהערכים שלך מתכוונים - אילו סוגים הוא הסיק, אילו הפניות הוא הרחיב - לפני שהפרשנות הזו מגיעה לאשכול. זה פועל כולו בדפדפן שלך.
המרת YAML ל-JSON היא לא רק שינוי פורמט. זוהי הביקורת הזמינה המהירה ביותר של מה שהתצורה שלך מכילה בפועל. ל-JSON אין הערות, אין עוגנים, אין הקלדה מרומזת מעבר למה שהתחביר קובע באופן מוחלט, כך שתצוגת ה-JSON של מניפסט היא הגרסה הפתורה והחד-משמעית שלו. מדריך זה מכסה כיצד YAML ממפה על JSON, את התנהגויות הסוג וההתייחסות הגורמות לאירועים אמיתיים, וכיצד להשתמש בממיר כאשר אתה מאתר באגים של תצורה, סקריפטים מול מניפסט או כתיבת מתקן בדיקה.
מה בעצם עושה המרת YAML ל-JSON?
הקשר מוגדר, לא מקרי: ה מפרט YAML 1.2 קובע כי YAML הוא superset של JSON, כך כל מסמך JSON כבר תקף YAML.YAML ו JSON מתארים את אותם שלושה דברים: מיפויים של מפתחות לערכים, רצפים מסודרים, וסקלרים המרה הולכת את מסמך YAML ופולטת כל מבנה במקבילה JSON שלה מיפוי בלוק הופך לאובייקט רצף בלוק הופך למערך סקלר הופך למחרוזת, מספר, בוליאני, או null, תלוי איך סכימת הליבה של YAML פותרת את זה.
החלק המבני לא מעניין כי הוא מכני החלק המעניין הוא כל מה ש-YAML יכולה לבטא ש-JSON לא יכולה, כי שם הממיר צריך לקבל החלטה בשמך:
| תכונת YAML | מה JSON מקבל | למה זה משנה |
|---|---|---|
הערות (# ...) |
ירד | ל-JSON אין תחביר הערות; התיעוד בתצורה שלך לא שורד |
עוגנים וכינויים (&base, *base) |
עותקים מורחבים | ל-JSON אין תחביר התייחסות, ולכן בלוקים משותפים משוכפלים |
מיזוג מפתחות (<<: *base) |
משוטח לתוך החפץ | מפתחות מפורשים עוקפים את אלה הממוזגים, לפי מפרט מפתח המיזוג |
| סקלרים בלוקים (` | , >`) |
מחרוזת בודדת עם בריחות |
מסמכים מרובים (---) |
מערך מסמכים | חבילת Kubernetes הופכת למערך JSON, אלמנט אחד לכל משאב |
| הקלדה מרומזת | סוגים פתורים | לא מצוטט 8080 הופך למספר, true בוליאני, null ריק |
השורה האחרונה היא זו ששווה לבהות בה.JSON מאלץ כל ערך להצהיר על הסוג שלו באמצעות תחביר: ציטוטים ממוצע מחרוזת, ספרות חשופות ממוצע מספר.YAML מסיק סוג מצורת הטקסט. המרה ל-JSON הופכת את ההסקה לגלויה. אם ציפית למחרוזת גרסה ו-JSON מראה לך 1.1 איפה YAML אמר 1.10, מצאת באג שאחרת היית שולח.
מדוע YAML'הקלדה מרומזת גורמת להפסקות אמיתיות
סכימת הליבה של YAML 1.2 פותרת סקלר לא מצוטט לפי דפוס. ספרות הופכות למספרים שלמים. ספרות עם נקודה עשרונית או מעריך הופכות לצפות. true ו false הופכים לבוליאנים. null ו ~ הפוך ל-null. כל השאר הוא מחרוזת.
זה נשמע מסודר עד שאתה עומד בערכים שנראים כמו סוג אחד ונועדו כאחר:
- יציאות ומזהים.
port: 08080אינו המספר 8080 אפס מוביל הופך אותו למספר שלם לא חוקי תחת סכימת הליבה, כך שרוב המנתחים מחזירים את המחרוזת, וכמה ישנים יותר מפרשים אותה כאוקטלית. מיקודים, מספרי טלפון ומזהי חשבון עם אפסים מובילים יש את אותה בעיה. - גרסאות.
version: 1.10הוא המצוף1.1. האפס הנגרר נעלם, ואף מנתח לא מזהיר אותך. השווה את זה מול תג מיכל והחיפוש נכשל. - קודי מדינה ושפה. תחת YAML 1.1 - ש-PyYAML עדיין עוקב אחריו כברירת מחדל, יחד עם הרבה כלי רובי וכלי Java ישנים יותר -
y,n,yes,no,on, וoffהם בוליאנים.NO,ON, וNAהם קודים רגילים לחלוטין של שתי אותיות בעולם האמיתי. - זמנים וסקסגסימלים. גם YAML 1.1 מנתח
12:30כמספר בסיס-60, שהוא 750. מחרוזות דמויות קרון או משך יכולות להיעלם למספרים שלמים.
כל אחד מאלה הוא השחתת נתונים שקטה, לא שגיאת ניתוח המסמך תקף, הצינור ירוק והערך שגוי. הממיר's שמור על מיתרים קיימת אפשרות בדיוק לסוג החקירה הזה: הפעל אותה וכל סקלר רגיל חוזר כמחרוזת, כך שתוכל להשוות את שתי ההמרות זו לצד זו ולראות בדיוק אילו ערכים המנתח פירש מחדש. מה שה-JSON מראה ללא אפשרות זו הוא מה שמנתח הייצור שלך עושה היום.
התיקון במקור YAML שלך הוא תמיד זהה: ציטוט כל דבר שמשמעותו טקסטואלית. port: "8080", version: "1.10", region: "NO". ציטוטים לא עולים כלום ומסירים את כל הקטגוריה של באג. אם אתה מייצר YAML מ-JSON במקום לכתוב אותו, ה ממיר JSON ל-YAML מחיל את הציטוט הזה באופן אוטומטי עבור ערכים מעורפלים.
כיצד עוגנים, כינויים ומפתחות מיזוג ממירים
עוגנים הם YAML's תשובה לחזרה. you mark a node with &name, ואז התייחס לזה מאוחר יותר עם *name:
defaults: &defaults
restartPolicy: Always
terminationGracePeriodSeconds: 30
web:
<<: *defaults
replicas: 3
worker:
<<: *defaults
terminationGracePeriodSeconds: 120
ל-JSON אין דרך לומר " אותו ערך כמו שם." אז הממיר מרחיב כל הפניה לעותק מלא. הפלט שלמעלה הופך לשלושה אובייקטים, שכל אחד נושא את שלו restartPolicy, וה-JSON ארוך יותר מה-YAML שיצר אותו. זה לא פגם בהמרה - זה מה שה-YAML אומר, כתוב.
מפתח המיזוג << ראוי להערה משלו מכיוון שקל לקבל את כלל הבכורה שלו לאחור מפתחות שנכתבו במפורש במיפוי הילד מנצחים מפתחות שנמשכו על ידי המיזוג בדוגמה, worker מסתיים עם תקופת חסד של 120, לא 30, ללא קשר אם קו המיזוג מופיע מעל או מתחת למפתח המפורש הממיר מיישם את הכלל הזה, כך שה-JSON מראה לך את התצורה האפקטיבית שלאחר המיזוג - שהיא בדרך כלל הדבר שבאמת רצית לבדוק.
שני שימושים מעשיים נובעים מכך. ראשית, כאשר תצורה משתמשת בעיגון כבד, המרה ל-JSON היא הדרך המהירה ביותר לענות על " למה הסביבה הזו בעצם פותרת?" מבלי להפעיל את הפריסה. שנית, אם לכינוי אין עוגן תואם - תוצאה נפוצה של פיצול קובץ אחד גדול לכמה - הממיר מדווח על כך כשגיאה במספר השורה, במקום לייצר בשקט אפס.
כיצד סקלרים בלוק ממירים
ל-YAML יש שתי דרכים להטמיע טקסט רב-שורות, והן מתנהגות אחרת:
- מילולי (
|) שומר על כל הפסקת שורה בדיוק כפי שנכתב השתמש בו עבור סקריפטים של מעטפת, אישורי PEM, SQL וכל דבר רגיש לרווח לבן. - מקופל (
>) מצטרף לשורות עוקבות ברווח בודד ומתייחס לשורה ריקה כאל הפסקת פסקה השתמש בה לפרוזה שאתה רוצה לעטוף בקובץ המקור אך להצטרף לערך.
שניהם מקבלים מחוון chomping השולט על קווים חדשים נגררים ברירת המחדל, הנקראת גזירה, שומרת בדיוק על קו חדש נגרר אחד. מינוס (|-) מפשיט את כל הקווים החדשים הנגררים. פלוס (|+) שומר על כל אחד מהם.
ב-JSON, כל זה קורס למחרוזת אחת עם \n בריחות זו סיבה נוספת שתצוגת JSON שימושית: היא חד משמעית. א | בלוק שהשורה האחרונה שלו הוחתמה בטעות, או א > חסום את שני הקווים המחוברים בקיפול שהתכוונת להפריד, ברור ב-JSON וכמעט בלתי נראה ב-YAML. הממיר מטפל גם במקרה שתופס יישומים תמימים - א # תו בתוך בלוק מילולי הוא תוכן, לא הערה, מה שחשוב ברגע שאתה מטמיע סקריפט מעטפת שמתחיל בשבאנג.
כיצד להשתמש בממיר YAML ל-JSON
שלב 1: הדבק את המסמך
הדבק כל YAML בלוח הקלט: מניפסט Kubernetes, א docker-compose.yml, זרימת עבודה של GitHub Actions, ספר משחק של Ansible, א .gitlab-ci.yml, או תצורת יישום. קבצי ריבוי מסמכים עם --- מפרידים זה בסדר - כל מסמך מנותח באופן עצמאי לחץ טען מדגם להתחיל מפריסה מציאותית שמפעילה מפות מקוננות, רצפים, אוסף ריק וסקלר בלוק מילולי.
הדבר היחיד שלא ינתח הוא הזחה עם תווי כרטיסיות. YAML אוסר על כרטיסיות על הסף, והממיר אומר זאת עם מספר השורה הפוגע במקום לנחש. עורכים שמכניסים לשונית ב-Enter הם המקור הרגיל; לרובם יש " המר הזחה לרווחים" פקודה שמתקנת את כל הקובץ בבת אחת.
שלב 2: בחר את צורת הפלט
פיק 2 חללים, 4 חללים, או ממוזער. ממוזער זה מה שאתה רוצה כשאתה עומד להדביק את התוצאה לתוך א curl גוף או משתנה סביבה פלט מחורץ זה מה שאתה רוצה כאשר אדם צריך לקרוא אותו.
מיין מפתחות משכתב את מקשי האובייקט בסדר אלפביתי בכל רמה. זה לא יסולא בפז כאשר משווים שתי גרסאות של תצורה: שני קבצים הנבדלים רק בסדר המפתחות מייצרים JSON ממוין זהה, כך שהבדל מראה רק שינויים אמיתיים. הזן את שתי הפלטים לתוך JSON Diff כלי ואתה מקבל השוואה מבנית מדויקת במקום שורה אחר שורה.
שמור על מיתרים משבית כפייה סקלרית, כפי שתואר לעיל השתמש בו כאשר אתה רוצה לראות את הטקסט הגולמי של כל ערך, או כאשר צרכן במורד הזרם מתייחס לכל דבר כמחרוזת בכל מקרה.
שלב 3: המר וקרא את השגיאות
קליק לְהַ. אם המסמך מעוצב היטב, ה-JSON מופיע למטה יחד עם ספירת השורות, ספירת המפתחות, גודל הבתים, ועבור זרמים מרובי מסמכים - כמה מסמכים נמצאו.
אם הוא לא מעוצב היטב, השגיאה נותנת שמות לשורה ההודעות מכסות את הכשלים שקורים בפועל בפועל: כרטיסיות המשמשות להזחה, שורה מחורצת שלא בקנה אחד עם אחיה, מחרוזת מצוטטת ללא סיום, כינוי ללא עוגן, מפתח מיזוג המצביע על משהו שאינו מיפוי מספר שורה הופך ציד של חמש דקות לתיקון של חמש שניות.
שלב 4: העתק, הורד או המשך
העתק את ה-JSON ללוח שלך או הורד אותו בתור א .json קובץ. משם, השלבים הבאים הנפוצים הם הדפסה יפה ואימות עם פורמט JSON, יצירת סוגים עבור מטעין תצורה עם json ל-Typescript, או גזירת חוזה לאימות CI עם מחולל סכמת JSON.
זרימות עבודה אמיתיות זה מתאים
איתור באגים במניפסט ש-"נראה בסדר"
כאשר פריסה מתנהגת באופן בלתי צפוי וה-YAML קורא נכון, המר אותה תשע פעמים מתוך עשר ה-JSON מראה את הבעיה באופן מיידי: ערך שהפך לבוליאני, מפתח מקונן ברמה אחת רדודה מהמתוכנן בגלל חלל תועה, עוגן שהתרחב למשהו מעופש תצוגת JSON מסירה את עמימות הרווח הלבן שהפכה את הבאג לבלתי נראה.
סקריפטים נגד תצורה
סקריפטים של מעטפת וצומת מטפלים ב-JSON באופן מקורי; YAML זקוקה לתלות. כשאני צריך לשלוף כל תג תמונה מתוך צרור של מניפסטים, להמיר תחילה ל-JSON ולעבור דרך jq מהיר יותר מהוספת ספריית YAML לסקריפט לזרוק. הממיר' תמיכה מרובת מסמכים חשובה כאן - חבילת Kubernetes של שישה משאבים הופכת למערך JSON שאתה יכול לחזור עליו.
בניית מתקני בדיקה
בדיקות אינטגרציה זקוקות לרוב לאובייקט תצורה ולא לקובץ תצורה המרת המניפסט האמיתי ל-JSON נותנת לך מתקן שמובטח שיתאים לצורת הייצור, שהיא נקודת התחלה טובה בהרבה מאובייקט שהקלדת מהזיכרון. חבר אותו עם json ל-Typescript והמתקן שלך מגיע עם סוגים.
סקירת תצורה בבקשת משיכה
קשה לקרוא הבדלים של YAML מעוגן בכבדות מכיוון ששינוי בשורה אחת לעוגן משנה בשקט כל צרכן. המרת שתי הגרסאות עם מיין מפתחות מופעל ומבדל ה-JSON מציג את רדיוס הפיצוץ האמיתי: כל ערך שנפתר שהשתנה, לא רק הקו שנערך.
מעבר בין כלים
שפע של פלטפורמות לקבל JSON אבל לא YAML, או להיפך.המרה היא בדרך כלל כל ההגירה.When אתה צריך לחזור לכיוון השני - JSON ביד, נדרש YAML - ה ממיר JSON ל-YAML סוגר את הלולאה, וה מאמת יאמל מאשר את ניתוחי התוצאה לפני שאתה מבצע אותה.
YAML ו-JSON השוו
| מימד | ימל | JSON |
|---|---|---|
| תגובות | כן | לא |
| עריכת אדם | מבוסס הזחה, קל לרפרף | כבד פיסוק, מילולי |
| ניתוח מכונה | מנתחים איטיים יותר, גדולים יותר, יותר מארזי קצה | מנתחים מהירים, זעירים בכל מקום |
| הסקת סוג | מרומז, תלוי סכימה | מפורש מתחביר |
| הפניות | עוגנים, כינויים, מפתחות מיזוג | אף אחד |
| מספר מסמכים לכל קובץ | כן, ויה --- |
לא |
| בית טיפוסי | קבצי תצורה, צינורות CI, מניפסטים | ממשקי API, החלפת נתונים, אחסון |
YAML 1.2 הוא רשמית ערכת-על של JSON, כך שכל מסמך JSON כבר תקף YAML. ההיפך אינו נכון, וזו הסיבה שהמרת YAML ל-JSON היא פעולה אובדת בדיוק בכיוון אחד: הערות ומבנה התייחסות נמחקים, בעוד הנתונים נשמרים. אם ל-YAML שלך יש הערות שאכפת לך מהן, שמור את ה-YAML כמקור האמת והתייחס ל-JSON כאל חפץ נגזר.
פרטיות: מדוע זה פועל בדפדפן שלך
קבצי תצורה הם בין החפצים הרגישים ביותר בטקסט רגיל שיש לצוות. הם נושאים שמות מארחים פנימיים, שמות אשכולות, נתיבי רישום, חשבונות שירות, מזהי מסד נתונים, ולמרות כולם ' הכוונות הטובות ביותר - אישור מדי פעם שעדיין לא הפך למנהל סודי.
הממיר הוא JavaScript בצד הלקוח המסמך שלך מנותח בדף, ה-JSON מופק בדף, ואף בקשה לא נושאת את הנתונים שלך לשום מקום טען את הכלי פעם אחת והוא ממשיך לעבוד עם הרשת כבוי, וזה הרגל סביר לכל דבר שאתה מדביק בו מניפסט זהו אותו עיקרון מאחורי כל כלי באתר, והנימוק מפורט במדריך על פרטיות נתונים בכלים מקוונים. אם אתה מרכיב ערכת כלים לדפדפן למטרות כלליות, ה ערכת כלים למפתחי אינטרנט מדריך מכסה את מה ששייך לו עוד.
מגבלות שכדאי לדעת
אף ממיר שמתאים לכרטיסיית דפדפן לא מיישם כל פינה במפרט YAML, וזה שימושי יותר להיות ספציפי לגבי הקצוות מאשר לרמוז שאין כאלה.
מפתחות מיפוי מורכבים - המפורש ? key טופס שבו המפתח הוא עצמו רצף או מיפוי - אינם נתמכים, כי מפתחות אובייקט JSON חייב להיות מחרוזות.Type תגיות כגון !!binary או מותאם אישית !MyType הנחיות אינן מתפרשות; הערך מגיע כטקסט. ערכי הציפה המיוחדים .inf, -.inf, ו .nan נשמרים כמחרוזות, מכיוון של-JSON אין מילולי עבורם וממיר בשקט ל null יאבד יותר מידע ממה שהוא חוסך. הנחיות כגון %YAML 1.2 מתעלמים ולא פועלים לפיהם.
אף אחד מאלה לא מופיע בקבצים רגילים של Kubernetes, Compose, Actions או Ansible. אם אתה מכה אחד, אתה עובד עם מסמך שנכתב עבור שפה ספציפית 's ספריית YAML, והספרייה הזו 's dumper משלו הוא הכלי הנכון.
שָׁוא
כיצד אוכל להמיר את YAML ל-JSON באינטרנט?
הדבק את ה-YAML שלך בחלונית הקלט ולחץ על המר. המנתח קורא את המסמך, פותר עוגנים וחוסם סקלרים, ומדפיס JSON בפורמט שאתה יכול להעתיק או להוריד. הכל קורה בדפדפן שלך, כך שלא מועלה קובץ.
האם JSON הוא תת-קבוצה של YAML?
כן. YAML 1.2 הוגדר מחדש כסופר-סט קפדני של JSON, כך שכל מסמך JSON חוקי הוא גם תקף YAML. ההיפך אינו נכון: YAML מוסיף הערות, עוגנים, סקלרי חסימה, מספר מסמכים לכל קובץ ומפתחות שאינם מחרוזים, שאף אחד מהם לא יכול לבטא ישירות.
כיצד מומרים עוגנים וכינויים של YAML ל-JSON?
ל-JSON אין תחביר התייחסות, ולכן כל כינוי מורחב לעותק מלא של הערך שהעוגן שלו מגדיר. config שעושה שימוש חוזר בבלוק ברירת מחדל שלוש פעמים מייצר שלושה אובייקטי JSON זהים. לכן הפלט גדול יותר ממקור YAML אך זהה מבחינה סמנטית.
מה קורה למזג מפתחות כמו סוגר הזווית הכפולה?
המיפוי שאליו מתייחסים מתמזג לאובייקט הנוכחי. מפתחות שנכתבו במפורש במיפוי הילד מנצח על מפתחות ממוזגים, התואם את ההתנהגות של מפרט מפתח המיזוג של YAML ושל Kubernetes ו-Ansible Tooling.
מדוע ה-YAML שלי נכשל עם שגיאת כרטיסיות?
YAML אוסר על תווי כרטיסיות להזחה - המפרט מאפשר רק רווחים עורכים שמכניסים כרטיסיות ב-Enter הם הסיבה הרגילה. המר את הכרטיסיות המובילות לרווחים, מה שרוב העורכים יכולים לעשות עבור קובץ שלם בבת אחת, והמסמך ינתח.
האם אוכל להמיר קובץ YAML מרובה מסמכים עם מפרידי מסמכים?
כן כל מסמך בין סמני המפריד מנותח באופן עצמאי והתוצאה היא מערך JSON עם אלמנט אחד לכל מסמך, בסדר מקור קובץ מסמך בודד מחזיר את האובייקט עצמו, לא מערך של אלמנט אחד.
האם מספרי יציאות ומחרוזות גרסה ישמרו על הסוג שלהם?
סקלרים רגילים נפתרים על ידי סכימת הליבה של YAML, כך ש-8080 לא מצוטט הופך למספר 8080 ו-1.10 לא מצוטט הופך ל-1.1. ציין את הערך ב-YAML שלך כדי לשמור עליו מחרוזת, או הפעל את האפשרות שמור מחרוזות כדי לכבות את כל הכפייה הסקלרית.
כיצד ממירים סקלרים מילוליים ומקופלים של בלוקים?
בלוק מילולי שומר כל שורה חדשה, כך שהוא הופך למחרוזת JSON עם מעברי שורות שנמלטו בלוק מקופל מצטרף לשורות עוקבות עם רווח ומתייחס לשורות ריקות כאל הפסקות פסקה. מכבדים אינדיקטורים של Chomping: מינוס מוריד את השורה החדשה הנגררת ופלוס שומר על כל שורה ריקה נגררת.
