הבאג שגרם לי לבנות את הכלי הזה היה קטן בצורה מטריפה מילאתי תבנית דואל HTML - כמה מאות שורות עם ציטוטים, מעברי שורות והקו נטוי האחורי המוזר - לשדה JSON כדי לשלוח ל-API, והבקשה חזרה כל הזמן כ-400 התבנית הייתה בסדר ה-JSON היה בסדר בפני עצמו אבל ברגע שהשניים נפגשו, ציטוט כפול שלא נמלט שלוש מאות תווים בסגירה שקטה של המחרוזת מוקדם, וכל מה שאחרי זה הפך לזבל המנתח לא הצליח להבין את זה הדבקתי טקסט חוקי לתוך מיכל חוקי והפקתי מסמך לא חוקי.
זו כל הבעיה שבריחה של JSON פותרת, וכדאי להבין במקום לעבוד מסביב. מדריך זה מכסה מה בעצם עושה בריחה, מאילו דמויות יש לברוח ומדוע, כיצד ביטול הבריחה הופך אותה וכיצד להשתמש בחינם JSON Escape / Unescape כלי להזזת טקסט שרירותי פנימה והחוצה ממחרוזות JSON ללא כשל שקט אחד. זה יושב לצד כלי השירות האחרים של הנתונים שכתבתי עליהם ב- מדריך אולטימטיבי לכלי JSON.
TL;DR: מחרוזת JSON אינה יכולה להכיל ציטוט כפול גולמי, קו נטוי אחורי גולמי או תווי בקרה גולמיים כמו שורות חדשות וכרטיסיות. בריחה מחליפה כל אחד ברצף קו נטוי אחורי -
"הופך\", שורה חדשה הופכת\n, כרטיסייה הופכת\t, וכל דבר אחר מתחת ל-U+0020 הופך\uXXXX. Unescaping הופך את הרצפים האלה בחזרה לדמויות המקוריות. ה JSON Escape / Unescape הכלי עושה את שניהם בדפדפן שלך, עם אפשרויות לעטוף את התוצאה במרכאות, לברוח non-ASCII כמו\uXXXX, או לברוח מהקו נטוי קדימה.
מה זה אומר לברוח ממחרוזת עבור JSON?
ל-JSON יש דקדוק מדויק ופורסם - הוא מוגדר על ידי RFC 8259 ולפי תקן ECMA-404 - והכללים למה שעשוי להופיע בתוך מחרוזת הם נוקשים מחרוזת JSON היא רצף של תווים עטופים במירכאות כפולות מכיוון שהמרכאות הכפולות מסמנות את ההתחלה והסוף של המחרוזת, ציטוט כפול בתוך הטקסט היה מסיים את זה בטרם עת. מכיוון שהקו נטוי האחורי מתחיל רצף בריחה, קו נטוי גולמי ייקרא לא נכון כהתחלה של אחד. ומכיוון שמחרוזות JSON נועדו להיות שורת טקסט לוגית אחת, תווי בקרה מילוליים - שורות חדשות, כרטיסיות, החזרות כרכרה - אינם מורשים לשבת בתוכם ללא בריחה.
בריחה היא תהליך של החלפת כל אחת מאותן דמויות מטרידות ברצף של שתי תווים אחורי ש-JSON מבין. ציטוט כפול הופך \". קו נטוי אחורי הופך \\. שורה חדשה הופכת \n. התוצאה היא טקסט ש נראה קצת יותר מכוער אבל עכשיו בטוח לרדת בין שני מרכאות מבלי לשבור את המסמך שמסביב המשמעות זהה - קריאת מנתח JSON \n מייצר שוב קו חדש אמיתי - אבל הייצוג כעת חוקי.
זה שונה מהותית מעיצוב מסמך JSON. מעצב מסדר את המבנה של אובייקט שלם: הזחה, סדר מפתחות, רווח לבן בין אלמנטים. בריחה פועלת רמה אחת למטה, על תוכן של ערך מחרוזת בודדת. אתה מושיט יד אל פורמט JSON כאשר יש לך מסמך שלם להדפיס או לאמת, ועבור JSON Escape / Unescape כלי כאשר יש לך גוש של טקסט גולמי אתה צריך להתאים בתוך שדה אחד.
אילו דמויות בעצם צריכות לברוח?
מפרט JSON הוא מרענן ספציפי כאן. בתוך מחרוזת, בדיוק שני תווים חייב תמיד להיות נמלט, בתוספת כל טווח של דמויות שליטה.
שתי בריחות החובה של תו בודד הן הציטוט הכפול (\") והקו נטוי האחורי (\\). מעבר לאלה, JSON מגדיר בריחות קצרות עבור חמישה תווי בקרה נפוצים: backspace (\b), טופס הזנה (\f), שורה חדשה (\n), החזרת כרכרה (\r), וכרטיסייה אופקית (\t). כל אחר תו בקרה - כל דבר עם נקודת קוד מתחת ל-U+0020 שאין לו צורה קצרה - חייב להיכתב כ-a \u בריחה ואחריה ארבע ספרות הקסדצימליות, כך שבייט ריק הופך \u0000 וה- "מפריד יחידה" הופך \u001F.
שתי דמויות נוספות הן אופציונלי כדי לברוח, וכאן הבלבול מתגנב פנימה האלכסון קדימה עשוי להיכתב כ \/, אבל זה לא חייב להיות - מישור / תקף לחלוטין JSON. וכל תו מעל טווח ASCII, כמו מודגש é או אימוג'י, עשוי להיכתב מילולית במסמך UTF-8 או לברוח כמו \uXXXX; שניהם חוקיים. ה JSON Escape / Unescape הכלי תמיד מטפל בבריחות החובה, ונותן לך מעברים עבור שני האופציונליים כך שתוכל להתאים לכל מה שמערכת היעד שלך מצפה.
האם עלי לברוח מהאלכסון קדימה ומהתווים שאינם ASCII?
שתי בריחות אופציונליות אלו קיימות מסיבות אמיתיות, גם אם לעיתים רחוקות אתה זקוק להן.
הבריחה קדימה חשובה בדיוק במצב נפוץ אחד: כאשר JSON מוטבע בתוך HTML <script> תָג. מנתח HTML של הדפדפן ' מחפש את הרצף המילולי </ כדי למצוא את הסוף של בלוק סקריפט, אז מחרוזת המכילה </script> ב-JSON שלך יכול לסגור בטרם עת את התג ולשבור את הדף. כתיבת האלכסון בתור <\/script> - עדיין תקף JSON, עדיין אותה מחרוזת לאחר ניתוח - נמנע מכך. מחוץ לסקריפטים מוטבעים, אתה יכול להשאיר את ה-slash לבד, וזו הסיבה שהכלי משאיר את ה-slash קדימה ללא בריחה כברירת מחדל.
בריחה מדמויות שאינן ASCII כמו \uXXXX עוסק בניידות ולא בנכונות. אם ה-JSON שלך עשוי לעבור דרך מערכת שמבלבלת בתים של UTF-8 - צינור רישום ישן, פרוקסי שגוי, ערוץ שמניח ASCII - והופך כל תו מעל טווח ASCII ל-ASCII טהור \u בריחה מבטיחה שהוא שורד ללא פגע הפלט מגושם יותר ופחות קריא לאדם, כך שהוא כבוי כברירת מחדל, אבל ה-"Escape Unicode" toggle נמצא שם לרגע שאתה צריך הובלה חסינת כדורים. נקודת קוד כמו é הופך \u00e9, ומנתח JSON משחזר את הדמות המקורית בדרך החוצה.
איך unescaping עובד, ומתי אני צריך את זה?
ביטול הבריחה הוא ההיפוך המדויק: הוא עובר דרך מחרוזת בריחה והופך כל רצף קו נטוי לאחור בחזרה לדמות הגולמית שהוא מייצג. \n הופך לקו חדש אמיתי, \t הופך ללשונית, \" הופך לציטוט כפול, ו \uXXXX הופך לתו בנקודת הקוד הזו. אתה צריך את זה בכל פעם שאתה בקצה המקבל - העתקת ערך מחרוזת היישר מקובץ JSON, שורת יומן או תגובת API, ואתה רוצה לקרוא את הטקסט המקורי ללא מסך מלא של קו נטוי אחורי בדרך.
מסיר בריחה טוב עושה שני דברים שממצא והחלפה נאיבי לא עושה. ראשית, הוא מפשיט זוג בודד של ציטוטים כפולים מסביב אם כל הערך מצוטט, כך שתוכל להדביק "line one\nline two" ישר ממסמך JSON ולקבל טקסט נקי בחזרה. second, זה מאמת כמו שזה הולך: רצף בריחה לא חוקי כמו \x, או קו נטוי לאחור תועה ממש בסוף המחרוזת, היא שגיאה אמיתית, וה- JSON Escape / Unescape כלי מדווח על מיקומו במקום לנחש ולהפיק פלט שגוי בשקט. קבלת " בריחה לא חוקית בעמדה 14" מנצח קבלת טקסט שנראה כמעט נכון אבל פגום בעדינות.
המאפיין המרכזי שיש לסמוך עליו הוא שבריחה וביטול בריחה הם הפוכים מדויקים. לברוח מכל טקסט ואז לברוח מהתוצאה ואתה מקבל בחזרה בדיוק את מה שהתחלת איתו, תו לדמות. ערבות הלוך ושוב היא מה שהופך את השימוש בכלי בטוח כשלב שגרתי בצנרת ולא בטרנספורמציה מסוכנת שאתה צריך לבדוק שוב ביד.
בריחה לעומת פעולות מחרוזת קשורות
בריחה של JSON היא אחת ממשפחה של " הפוך את הטקסט הזה לבטוח עבור ההקשר הזה" משתנה, וזה עוזר לשמור אותם ישרים. הנה איך זה בהשוואה למפתחים השכנים שמבלבלים אותו לרוב.
| מבצע | מגן מפני | דוגמה | כלי |
|---|---|---|---|
| JSON בריחה | שבירת מחרוזת JSON עם ציטוטים, קו נטוי אחורי או תווי בקרה | he said "hi" → he said \"hi\" |
JSON Escape / Unescape |
| קידוד ישות HTML | שבירת HTML או הפעלת XSS עם <, >, & |
<b> → <b> |
ישויות HTML |
| כתובת אתר אחוז-קידוד | שבירת כתובת URL עם רווחים או תווים שמורים | a b → a%20b |
- - |
| פורמט/אימות JSON | שגיאות מבניות על פני מסמך שלם | ממוזער → מודפס יפה | פורמט JSON |
| JSON → YAML | העברת תצורה בין פורמטים של סדרה | {"a":1} → a: 1 |
JSON ל-YAML |
הדפוס שיש לשים לב אליו הוא שכל בריחה מכוונת ל-a שונה מיכל. ישויות HTML שומרות על טקסט מלשבור HTML; קידוד באחוזים מונע ממנו לשבור כתובת URL; בריחה של JSON מונעת ממנו לשבור מחרוזת JSON. השימוש בבעיה הלא נכונה - קידוד HTML משהו שצריך לברוח מ-JSON - משאיר את הבעיה האמיתית לא פתורה ומוסיף שכבה חדשה של רעש. מכיוון שכל זה פועל על טקסט שאולי לא תרצה להעביר לשרת של צד שלישי, אני שומר על כל אחד מהכלים האלה בצד הלקוח, וזה הטיעון שהעליתי במלואו ב- מדריך פרטיות נתונים לכלים מקוונים.
מהן הטעויות הנפוצות בעת הטמעת טקסט ב-JSON?
הטעות היחידה הנפוצה ביותר היא זו שעלתה לי אחר הצהריים: הדבקת טקסט רב שורות עם ציטוטים שלא נמלטו ישירות לשדה JSON ובהנחה שבגלל ששני החלקים תקפים, השלם תקף. זה לא - למיכל יש כללים שהתוכן חייב לציית להם.
שנייה קרובה היא בריחה כפולה. אם מחרוזת כבר נמלטה פעם אחת ואתה בורח ממנה שוב, כל \n הופך \\n והקווים החדשים שלך הופכים ל-backslash-n מילולי שאף מנתח לא ימיר בחזרה. זה קורה בדרך כלל כאשר ערך עובר דרך שתי מערכות שכל אחת מהן בורחת ממנו בצורה מועילה. אם לפלט שלך יש ריצות חשודות של \\ איפה שציפיתם ל-backslashes בודדים, כנראה שברחתם כפול, וביטול הבריחה פעם אחת יתקן את זה. המלכודת השלישית היא לשכוח שנתיב Windows אוהב C:\Users\me מלא בנתחים אחוריים, שכל אחד מהם חייב להפוך \\ - נתיב שלא נמלט ב-JSON הוא מקור קלאסי של "למה ה-JSON שלי לא חוקי" בִּלבּוּל.
התיקון עבור שלושתם זהה: תן לכלי לבצע את הבריחה בדיוק פעם אחת, בגבול שבו טקסט גולמי פוגש JSON, וקרא את סיכום ספירת התווים שהוא מראה לשפיות - בדוק שמשהו השתנה. כאשר אתה צריך לאמת ידנית, לברוח עם " לעטוף במרכאות" מופעל והדבק את התוצאה לתוך פורמט JSON - אם הוא מנתח כמחרוזת חוקית, הבריחה שלך נכונה.
דוגמה עובדת: הטמעת קטע HTML ב-JSON
תן לי לעבור על המצב המדויק שהתחיל את זה, כי לראות את השינוי פעם אחת גורם לכלל להידבק. תגיד שאתה רוצה לשלוח את הפרגמנט הזה בתור body שדה של בקשת API:
<p>Hi "there",</p>
<p>Visit https://example.com/path</p>
שלושה דברים בטקסט הזה ילחמו עם JSON. שני הציטוטים הכפולים מסביב there כל אחד ינסה לסיים את המחרוזת השורה החדשה בין הפסקאות היא תו בקרה מילולי JSON אוסר בתוך מחרוזת. וה </p> רצפים אינם מזיקים בקובץ JSON רגיל אך מסוכנים אם ה-JSON הזה מודפס אי פעם בתוך HTML <script> תָג. הדבק את הפרגמנט לתוך JSON Escape / Unescape כלי, הפעל את " עטוף במרכאות," ואתה מקבל מחרוזת JSON אחת ותקפה: הציטוטים הופכים \", השורה החדשה הופכת \n, ועם " לברוח קדימה slash" אפשר את התגיות הסגירה להפוך <\/p>זרוק את כל הערך המצוטט הזה ישר לתוך שלך body שדה והבקשה עוברת.
הנסיעה לאחור שגרתית באותה מידה. כאשר חבר לצוות שולח לך קו יומן עם נמלט מ-JSON message שדה מלא ב \n ו \", הדבק אותו בכלי, עבור אל Unescape וקרא את הטקסט המקורי מרובה שורות כשהקוים האחוריים נעלמו. מכיוון ששתי הפעולות הן הפוכות מדויקות, אתה יכול להזיז מטען החוצה כדי לערוך אותו ולחזור פנימה ללא חשש משחיתות - סיכום ספירת התווים מאשר שהטרנספורמציה רצה, וכל בריחה שגויה מסומנת במיקומה במקום לשבש בשקט את הטקסט. הבטיחות הלוך ושוב היא מה שהופך את הבריחה משלב ידני עצבני למשהו שאתה יכול לחבר לזרימת עבודה ולשכוח ממנו.
שאלות נפוצות
מה זה אומר לברוח ממחרוזת עבור JSON? ערכי מחרוזת JSON אינם יכולים להכיל ציטוט כפול גולמי, קו נטוי אחורי גולמי או תווי בקרה גולמיים כמו שורות חדשות וכרטיסיות. בריחה מחליפה כל אחד מאלה ברצף קו נטוי אחורי - " הופך ל-", שורה חדשה הופכת ל-\n, לשונית הופכת ל-\t - כך שניתן למקם את הטקסט בתוך מחרוזת JSON מבלי לשבור את המבנה שמסביב.
במה זה שונה מפורמט JSON? פורמט JSON Pretty-Printers או מצמצם מסמך JSON שלם ומאמת את המבנה שלו. כלי זה פועל ברמה אחת למטה, על התוכן של מחרוזת בודדת: הוא הופך טקסט שרירותי לבטוח להטמעה בתוך ערך JSON, או מפענח ערך נמלט בחזרה לטקסט גולמי. השתמש בפורמטטר עבור מסמכים ובכלי זה עבור מחרוזות בודדות.
אילו דמויות בורחות? הציטוט הכפול ("), הקו האחורי (\), הרווח האחורי (\b), הזנת הטופס (\f), השורה החדשה (\n), החזרת הגררה (\r) והכרטיסייה (\t) נמלטים תמיד, יחד עם עם כל תו בקרה אחר מתחת ל-U+0020 בתור \uXXXX. לחלופין, הלוכסן הקדמי הופך ל-/ וכל תו שאינו ASCII הופך ל-\uXXXX.
האם עלי לברוח מהחתך קדימה? זה אופציונלי. מפרט JSON מאפשר גם / וגם /, אז פשוט / תקף. המקום האחד / חשוב נמצא בתוך HTML
