אני בונה Toolz.dev, ולפני כן ביליתי שנים משלוח תוספי וורדפרס ו - APIs Laravel.בכל זה, הודעת השגיאה הבודדת שבזבזתי עליה הכי הרבה שעות היא וריאציה כלשהי של "Unexpected token ב - JSON בעמדה 428." זה אומר לך כמעט כלום אין שורה, אין עמודה, והמיקום שהוא שם הוא לעתים קרובות כמה תווים מעבר לדבר שהוא לא בסדר, בסופו של דבר אתה סופר תווים בכתם ממוזער ביד, או מדביק את כל המטען לתוך עורך ופוזל בניתי את מאמת JSON אז אני אף פעם לא צריך לעשות את זה שוב, וזה המדריך למה זה עושה ולמה אימות JSON הוא מסובך יותר ממה שהוא נראה.
TL;DR: מאמת JSON בודק טקסט מול הדקדוק ב-RFC 8259, וכאשר הטקסט נשבר, אומר לך את השורה, העמודה והתו המדויקים של השגיאה הראשונה, מנוסחים במונחים של מה שהוא ציפה. זה גם תופס דברים שמנתח רגיל מסתיר: מקשים כפולים, שמתמוטטים בשקט לערך האחרון, והוא מדווח על המבנה של מסמך חוקי (ספירת אובייקטים, מערך ומפתחות, עומק קינון וגודל בתים). זה לא מעצב. מעצב מניח שהקלט כבר תקף; מאמת הוא הדבר שאליו אתה מגיע בדיוק כשהוא לא.
מה זה אומר ש-JSON יהיה תקף?
JSON הוא פורמט קטן עם דקדוק קפדני התקן הנוכחי הוא RFC 8259, אשר מתיישר עם ECMA-404, וביניהם הם מגדירים בדיוק מה מסמך חוקי עשוי להכיל טקסט JSON הוא ערך יחיד ערך זה הוא אובייקט, מערך, מחרוזת, מספר, true, false, או null. חפצים עטופים בפלטה ומחזיקים מופרדים בפסיקים "key": value זוגות מערכים עטופים בסוגריים ומחזיקים ערכים מופרדים בפסיקים מחרוזות עטופות במירכאות כפולות, לעולם לא במירכאות בודדות מספרים עוקבים אחר צורה ספציפית ללא אפסים מובילים וללא נקודה עשרונית נגררת אין הערות, ואין פסיקים נגררים.
המשפט האחרון הוא המקום שבו רוב ה-JSON בעולם האמיתי משתבש, כי הרבה מאנשי ה-JSON כותבים ביד זה לא באמת JSON. זה קובץ תצורה עם // הערות, או אובייקט שהועתק ממקור JavaScript שבו ציטוטים בודדים ופסיקים נגררים בסדר, או מתקן בעריכה ידנית שבו מישהו הוסיף שדה והשאיר פסיק משתלשל. כל אלה נדחים על ידי מנתח קפדני, ומאמת ' התפקיד הוא לדחות אותם במקום מסוים ולא במשיכת כתפיים.
נקודה אחת שכדאי להבהיר, כי היא מכשילה אנשים שלמדו JSON לפני שנים: ערך חשוף הוא מסמך JSON שלם ותקף. 42 בפני עצמו תקף JSON. כך גם "hello", וכך גם true. הישן RFC 4627 דרש שהרמה העליונה תהיה אובייקט או מערך, אבל ההגבלה הזו בוטלה ב-2014 כאשר RFC 7159 (לימים 8259) החליף אותה. אם כלי אומר לך 42 אינו תקף JSON, הכלי הזה עוקב אחר מפרט שהיה מיושן כבר למעלה מעשור.
למה JSON.parse כתב שגיאה כל כך גרוע?
הסיבה שמאמת ייעודי מרוויח את מקומו היא שהמנתח המובנה בשפה שלך מותאם לנתיב המאושר, לא להסבר העצוב. JSON.parse בדפדפן זורק א SyntaxError שההודעה שלו היא ספציפית למנוע ובדרך כלל נותנת לך היסט תו ללא שורה או עמודה. V8 אומר "Unexpected token } ב-JSON בעמדה 148." Firefox אומר "JSON.parse: תו בלתי צפוי בשורה 1 עמודה 149." Safari אומר שוב משהו אחר. אף אחד מהם לא אומר לך למה הם ציפו, והמיקום נמדד מתחילת המחרוזת, וזה חסר תועלת ברגע של-JSON שלך יש יותר מכמה שורות.
המאמת ב-Toolz.dev אינו משתמש JSON.parse. הוא הולך על הטקסט עצמו עם מנתח רקורסיבי-ירידה בכתב יד, עוקב אחר השורה והעמודה תוך כדי, כך שכאשר הוא נעצר הוא יכול למסור לך את כל שלוש הקואורדינטות: השורה, העמודה והיסט התווים המוחלט. חשוב מכך, הוא יודע את כלל הדקדוק שהוא היה באמצע, אז ההודעה היא ספציפית. במקום " אסימון בלתי צפוי," אתה מקבל " פסיק מעקב אסור לפני הסד הסגירה," או " מקשי אובייקט חייבים להיות מחרוזות עם ציטוט כפול," או " צפוי פסיק או סד סגירה אחרי חבר אובייקט." ההבדל הזה הוא ההבדל בין תיקון הקובץ בחמש שניות לבין ציד אחריו.
זה גם מצייר caret מתחת לתו המדויק בשורה הפוגעת, כמו מהדר. כאשר אתה מסתכל על שורה 34 של קובץ תצורה, "עמודה 12" זה בסדר, אבל א ^ לשבת ישירות מתחת לציטוט התועה זה מהיר יותר.
אילו טעויות JSON תופס המאמת בשמו?
אלו הכשלים שאני רואה לרוב, הן בעבודה שלי והן בשרשורי התמיכה של כלים כמו זה. המאמת שם כל אחד מהם במקום לדווח על שגיאת אסימון גנרית.
| טעות | איך זה נראה | למה זה לא חוקי |
|---|---|---|
| פסיק נגרר | {"a": 1,} או [1, 2,] |
ל-JSON אין פסיקים נגררים; הדקדוק הסטנדרטי' פשוט לא מאפשר אחד לפני סד או סוגר סגירה |
| ציטוטים בודדים | {'name': 'Liton'} |
מחרוזות ומקשים חייבים להשתמש במירכאות כפולות; מרכאות בודדות הן הרגל של JavaScript, לא JSON |
| חסר פסיק | {"a": 1 "b": 2} |
לכל איבר אחרי הראשון יש להקדים פסיק |
| תגובות | {"a": 1} // note |
ל-JSON אין תחביר הערות; ה // והכל אחריו הוא תוכן בלתי צפוי |
| מפתח לא מצוטט | {name: "Liton"} |
מפתחות הם מחרוזות ויש לצטט אותם, בניגוד למילולי אובייקט JavaScript |
| אפס מוביל | {"n": 007} |
ייתכן שלמספר אין אפס מוביל, אז 007 אינו חוקי; לכתוב 7 |
| נקודה עשרונית נגררת | {"n": 5.} |
השבר שאחרי נקודה עשרונית צריך לפחות ספרה אחת |
| תו שליטה גולמי | כרטיסייה מילולית או שורה חדשה בתוך מחרוזת | יש לברוח מתווי בקרה בתוך מחרוזות \t, \n, וכן הלאה |
| NaN או Infinity | {"n": NaN} |
אלה תקפים ב-JavaScript אך אינם ערכי JSON |
| מחרוזת ללא סיום | {"a": "oops} |
מחרוזת ללא ציטוט סגירה פועלת עד סוף הקלט |
כל אחד מאלה מייצר מסר בשפה פשוטה ועמדה. מקרה האפס המוביל הוא דוגמה נחמדה מדוע מנתח ייעודי עוזר: מנתח גנרי קורא 007 כמספר 0 ואז טיולים מעל ה 7 כמו "תוכן נוסף," מצביע עליך על 7, כאשר הבעיה האמיתית היא שני האפסים שלפניו המאמת בודק קודם את תבנית האפס המוביל ואומר לך את זה ישירות.
מה לגבי מפתחות כפולים?
הנה זה שנשך אותי בהפקה יותר מכל שגיאת תחביר, כי זו בכלל לא שגיאת תחביר. זה חוקי JSON:
{
"timeout": 30,
"retries": 3,
"timeout": 60
}
RFC 8259 אומר שהשמות בתוך אובייקט "SHOULD להיות ייחודיים," אבל זה לא אוסר על כפילויות, אז מנתח נדרש לקבל את זה. מה שקורה אחר כך הוא המקום שבו מתחילות הצרות: התקן אומר שההתנהגות עם שמות כפולים היא בלתי צפויה, ובפועל כמעט כל מנתח שומר על הערך האחרון ומשליך בשקט את הקודמים. אז האובייקט הזה מנתח {"timeout": 60, "retries": 3}, וה "timeout": 30 הגדרת בקפידה בחלק העליון של הקובץ נעלם ללא אזהרה אם שני אנשים ערכו את התצורה, או מיזוג השתבש, או שלב תבנית פלט את אותו מפתח פעמיים, יש לך באג שאף מנתח לעולם לא יסמן עבורך.
המאמת מסמן אותו זיהוי מקשים כפולים פועל כברירת מחדל, ומכיוון שכפיל הוא חוקי, הוא מדווח כאזהרה ולא כשגיאה: המסמך עדיין תקף, אך נאמר לך כל מקש שמופיע יותר מפעם אחת באותו אובייקט, עם השורה שלו ו-a מצביע JSON נתיב כדי שתוכל למצוא אותו בתוך מבנה מקונן אם אתה באמת רוצה כפילויות, אתה יכול לכבות את הסימון. רוב הזמן, לראות את האזהרה זה הרגע שבו אתה מבין מה השתבש.
במה שונה מאמת ממעצב?
אנשים משתמשים במילים לסירוגין, והכלים חופפים, אבל הם עונים על שאלות שונות. א פורמט JSON לוקח JSON אתה כבר מאמין תקף ומדפיס אותו מחדש עם הזחה עקבית כך אדם יכול לקרוא אותו אם אתה מוסר מעצב שבור JSON, הטוב ביותר שהוא יכול לעשות הוא לסרב. a validator' כל המטרה היא המקרה השבור: זה אומר לך איפה ולמה. Toolz.dev validator עושה את שתי העבודות, כי ברגע שהוא אישר שמסמך תקף הוא כבר ניתח אותו, אז הוא די-מדפיס את התוצאה באותו מעבר. אבל תכונת הכותרת היא האבחנה, לא ההזחה.
אותו קשר מתקיים עם הכלים השכנים. ה מיניפר JSON מפשיט רווח לבן כדי לכווץ מטען, וזה הגיוני רק בקלט חוקי. ה סדרן JSON מסדר מחדש מפתחות עבור הבדלים יציבים, שוב בקלט חוקי. ה JSON לברוח ולהימלט כלי עוסק בהטמעת JSON בתוך מחרוזת. וה בודק JSONPath שאילתות מסמך שכבר אישרתם הוא מעוצב היטב אימות הוא השלב שמגיע לפני כולם, וזו הסיבה שהוא זה שאני מריץ ראשון בכל פעם שתגובת API או קובץ תצורה מתנהגים בצורה מוזרה יש סיור רחב יותר של איך אלה משתלבים יחד ב מדריך אולטימטיבי לכלי JSON.
מה הסטטיסטיקה של המבנה אומרת לך?
כאשר מסמך מאמת, הכלי מדווח על צורתו: כמה אובייקטים ומערכים הוא מכיל, כמה מפתחות, כמה מחרוזות, מספרים, בוליאנים ואפסים, כמה עמוק הוא מקנן וגודלו בתווים וגם ב-UTF-8 בתים זה לא קישוט כאשר נמסרת לך תגובת API לא מוכרת, מספר העומק אומר לך במבט חטוף אם יש לך עסק עם רשומה שטוחה או עץ מקונן עמוק, וספירת המפתחות אומרת לך בערך כמה עבודה לנתח זה יהיה.
דמות הבתים חשובה יותר ממה שאנשים מצפים. מגבלות גודל הבקשה, מגבלות תור ההודעות ומגבלות עמודות מסד הנתונים נמדדות כמעט תמיד בבתים, לא בתווים, והשניים נבדלים ברגע שה-JSON שלך מכיל משהו מחוץ ל-ASCII. אימוג'י או שם מודגש הם תו אחד על המסך אבל שניים, שלושה או ארבעה בתים על החוט. אם מטען נתקל במגבלה של 256 KB, ספירת התווים תטעה אותך וספירת הבתים לא תעשה זאת. המאמת מחשב את אורך הבתים האמיתי של UTF-8 כך שהמספר שאתה רואה הוא המספר שהמגבלה סופרת.
איך אני משתמש בו
זרימת העבודה שלי משעממת ומהירה, וזו הנקודה כאשר אינטגרציה נשברת, אני מעתיק את גוף התגובה הגולמי ישר מתוך לשונית הרשת ומדביק אותו לתוך המאמת אם הוא תקף, התוצאה הירוקה והסטטיסטיקות אומרות לי שהבעיה היא במקום אחר, בקוד שלי ולא בנתונים שלהם, ושללתי מחלקה שלמה של סיבות תוך שתי שניות אם זה לא חוקי, אני מקבל את השורה והעמודה, מתקן את זה וממשיך הלאה כשאני עורך ביד קובץ תצורה, אני מדביק אותו לפני ביצוע, בעיקר כדי לתפוס את הפסיק הנגרר אני תמיד נראה להשאיר מאחור ומדי פעם מפתח משוכפל מהדבק העתקה לכל מי שמרכיב ערכה משלו, המאמת יושב לצד שאר הדברים החיוניים ב ערכת כלים למפתחי אינטרנט.
זווית הפרטיות היא גם לא מחשבה שלאחר מכן אנשי JSON הכי צריכים לאמת הוא בדיוק ה-JSON שהם צריכים להיות הכי זהירים איתו: תגובות API הנושאות אסימונים, קבצי תצורה עם אישורים, מטענים עם נתוני לקוחות כל מה שהמאמת עושה קורה בדפדפן שלך, ב-JavaScript, במחשב שלך שום דבר לא מועלה, נרשם או מאוחסן אתה יכול להוכיח את זה על ידי פתיחת לשונית הרשת בזמן שאתה מאמת, או על ידי ניתוק מהאינטרנט וצפייה בכלי להמשיך לעבוד.
שאלות נפוצות
למה JSON שלי אומר שזה לא חוקי כאשר זה נראה בסדר?
הסיבות הנפוצות ביותר הן פסיק נגרר לפני סד או סוגר סגירה, מרכאות בודדות שבהן JSON דורש מרכאות כפולות, פסיק חסר בין שני איברים, או הערה, ש-JSON לא מאפשר כלל. קל לפספס את כל הארבעה בעין, במיוחד בקובץ גדול המאמת שם איזה מהם הוא מצא ונותן לך את השורה והעמודה המדויקים, כך שבמקום לסרוק את כל המסמך אתה קופץ ישר לתו שהוא עצר עליו.
האם מספר בודד או מחרוזת חוקיים JSON בפני עצמו?
כן. תחת RFC 8259, כל ערך JSON הוא טקסט JSON שלם, אז 42, "hello", true, ו null כולם לאמת בעצמם הכלל שהרמה העליונה הייתה צריכה להיות אובייקט או מערך הגיע מה-RFC 4627 הישן יותר והוסר ב-2014 כלי שדוחה ערך חשוף עוקב אחר מפרט מיושן.
האם המאמת משנה או מעלה את הנתונים שלי?
מס 'זה מנתח את הטקסט בדפדפן שלך ולעולם לא שולח אותו לשום מקום על מסמך חוקי הוא מייצר עותק מודפס יפה לנוחות, אבל עותק זה נוצר באופן מקומי ואת המקור הוא אף פעם לא מועבר, נרשם, או מאוחסן כי אין שרת הלוך ושוב, הכלי עובד גם עם הרשת מנותקת פעם הדף נטען.
למה שיהיה אכפת לי ממפתחות כפולים אם ה-JSON עדיין בתוקף?
כי שכפול כמעט תמיד אומר אובדן נתונים שלא התכוונת התקן מאפשר מפתחות כפולים אך משאיר את הטיפול בהם לא מוגדר, ובפועל מנתחים שומרים רק על הערך האחרון ומפילים את השאר אז תצורה שבה timeout מופיע פעמיים בשקט מאבד את ההגדרה הראשונה המאמת מזהיר אותך על כל מפתח חוזר עם המיקום שלו, וזה בדרך כלל הרגע שבו אתה מזהה מיזוג רע או טעות העתק-הדבק.
האם זה יכול לאמת JSON עם הערות, כמו קובץ הגדרות tsconfig או VS Code?
לא, וזה מכוון הקבצים האלה הם JSON עם Comments (JSONC) או JSON5, שהם פורמטים נפרדים שמרפים את הכללים המאמת מכוון ל-RFC 8259 קפדני, אז הוא יסמן הערה כשגיאה אם אתה צריך הערות בקובץ תצורה, זה אות שהפורמט צריך להיות משהו בנוי עבורו, כגון YAML או TOML, במקום JSON שנמתח מעבר למה שהתקן מאפשר.
מה ההבדל בין אימות ועיצוב JSON?
אימות בודק אם הטקסט מציית לדקדוק JSON ואם לא, אומר לך בדיוק היכן הוא נשבר. עיצוב מניח שהטקסט כבר תקף ומתאים רק את הרווח הלבן שלו לקריאה. אתה מושיט יד למאמת כשמשהו לא בסדר ואתה צריך לדעת מה; אתה מושיט יד למעצב כשהכל בסדר ואתה רק רוצה שהוא יהיה קריא הכלי הזה עושה את שניהם, אבל הסיבה שלו להתקיים היא האבחנה.
כמה גדול קובץ אני יכול לאמת?
בנוחות לתוך עשרות מגה-בייט, מוגבל רק על ידי הדפדפן שלך's זיכרון, מכיוון שכל המסמך מנותח במעבר אחד במכשיר שלך. אין מכסה גודל העלאה כי אין העלאה. עבור קובץ ענק באמת, בג'יגה-בייט, מאמת שורת פקודה זורמת הוא המכשיר הטוב יותר, מכיוון שהדפדפן מחזיק את הטקסט כולו בזיכרון בבת אחת.
