لماذا JSON الخاص بي غير صالح؟ الأخطاء والإصلاحات الشائعة

أنا أبني تولز.ديف، وقبل ذلك قضيت سنوات في شحن مكونات WordPress الإضافية وواجهات برمجة تطبيقات Laravel. في كل ذلك، رسالة الخطأ الوحيدة التي أهدرت معظم الساعات عليها هي بعض الاختلافات في &quot؛ رمز غير متوقع في JSON في الموضع 428.&quot؛ لا يخبرك بأي شيء تقريبًا. لا يوجد سطر ولا عمود، والموضع الذي يسميه غالبًا ما يكون بضعة أحرف بعد الشيء الخطأ. ينتهي بك الأمر إلى حساب الأحرف في نقطة مصغرة يدويًا، أو لصق الحمولة بأكملها في المحرر والتحديق. لقد بنيت مدقق JSON لذلك لا يتعين علي فعل ذلك مرة أخرى أبدًا، وهذا هو الدليل لما يفعله ولماذا يكون التحقق من صحة JSON أكثر صعوبة مما يبدو.

ليرة تركية؛DR: يقوم مدقق JSON بفحص النص مقابل القواعد النحوية في RFC 8259، وعندما ينقطع النص، يخبرك بالسطر والعمود والحرف الدقيق للخطأ الأول، والذي تمت صياغته من حيث ما كان متوقعًا. كما أنه يلتقط الأشياء التي يخفيها المحلل اللغوي العادي: المفاتيح المكررة، والتي يتم طيها بصمت إلى القيمة الأخيرة، ويقوم بالإبلاغ عن بنية مستند صالح (الكائن والمصفوفة وعدد المفاتيح وعمق التداخل وحجم البايت). إنه ليس منسقًا. يفترض المنسق أن الإدخال صالح بالفعل؛ المدقق هو الشيء الذي تصل إليه على وجه التحديد عندما لا يكون كذلك.

ماذا يعني أن تكون JSON صالحة؟

JSON هو تنسيق صغير ذو قواعد نحوية صارمة. المعيار الحالي هو RFC 8259الذي يصطف مع ECMA-404، وفيما بينها يحدد بالضبط ما قد يحتوي عليه المستند الصالح. نص JSON هو قيمة واحدة. هذه القيمة هي كائن، مصفوفة، سلسلة، رقم، true، false، أو null. يتم لف الكائنات بين قوسين مع فصل الفاصلة "key": value أزواج. يتم تغليف المصفوفات بين قوسين وتحمل قيمًا مفصولة بفواصل. يتم تغليف السلاسل بعلامات اقتباس مزدوجة، ولا علامات اقتباس مفردة أبدًا. تتبع الأرقام شكلاً محددًا بدون أصفار بادئة ولا توجد علامة عشرية زائدة. لا توجد تعليقات، ولا توجد فواصل زائدة.

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

هناك نقطة واحدة تستحق التوضيح، لأنها تعثر الأشخاص الذين تعلموا JSON منذ سنوات: القيمة المجردة هي وثيقة JSON كاملة وصالحة. 42 في حد ذاته JSON صالح. هكذا هو "hello"و هكذا هو true. القديم RFC 4627 يتطلب أن يكون المستوى الأعلى كائنًا أو مصفوفة، ولكن تم إسقاط هذا القيد في عام 2014 عندما حل محله RFC 7159 (لاحقًا 8259). إذا أخبرتك الأداة 42 غير صالحة JSON، تتبع هذه الأداة مواصفات عفا عليها الزمن لأكثر من عقد من الزمن.

لماذا يقوم JSON.parse بتحليل مراسل الأخطاء السيئة؟

السبب وراء حصول المدقق المخصص على مكانه هو أن المحلل اللغوي المدمج في لغتك تم تحسينه للمسار السعيد، وليس لشرح المسار الحزين. JSON.parse في المتصفح يلقي أ SyntaxError رسالتها خاصة بالمحرك وعادةً ما تمنحك إزاحة حرف بدون سطر أو عمود. يقول V8 &quot؛ رمز غير متوقع } في JSON في الموضع 148.&quot؛ يقول فايرفوكس &quot؛ JSON.parse: حرف غير متوقع في السطر 1 العمود 149.&quot؛ يقول سفاري شيئًا مختلفًا مرة أخرى. لا أحد منهم يخبرك بما توقعه، ويتم قياس الموضع من بداية السلسلة، وهو أمر عديم الفائدة في اللحظة التي يكون فيها JSON الخاص بك يحتوي على أكثر من سطرين.

لا يستخدم المدقق الموجود على Toolz.dev JSON.parse. يقوم بتمرير النص نفسه باستخدام محلل نسب متكرر مكتوب بخط اليد، ويتتبع السطر والعمود أثناء سيره، لذلك عندما يتوقف يمكنه تسليم الإحداثيات الثلاثة: السطر والعمود وإزاحة الأحرف المطلقة. والأهم من ذلك، أنه يعرف القاعدة النحوية التي كانت في منتصفها، لذا فإن الرسالة محددة. بدلاً من &quot؛ رمز مميز غير متوقع، &quot؛ تحصل على &quot؛ لا يُسمح بفاصلة التتبع قبل دعامة الإغلاق، &quot؛ أو &quot؛ يجب أن تكون مفاتيح الكائنات عبارة عن سلاسل مقتبسة مزدوجة، &quot؛ أو &quot؛ من المتوقع وجود فاصلة أو دعامة إغلاق بعد عضو الكائن.&quot؛ هذا الفرق هو الفرق بين إصلاح الملف في خمس ثوانٍ والبحث عنه.

كما أنه يرسم علامة الإقحام أسفل الحرف الدقيق في السطر المخالف، بالطريقة التي يفعلها المترجم. عندما تنظر إلى السطر 34 من ملف التكوين، &quot؛ العمود 12&quot؛ لا بأس، ولكن أ ^ الجلوس مباشرة تحت الاقتباس الضال هو أسرع.

ما هي أخطاء JSON التي يخطئ فيها المدقق بالاسم؟

هذه هي حالات الفشل التي أراها في أغلب الأحيان، سواء في عملي أو في سلاسل الدعم لأدوات مثل هذه. يقوم المدقق بتسمية كل واحد بدلاً من الإبلاغ عن خطأ رمزي عام.

خطأ	كيف يبدو	لماذا هو غير صالح
فاصلة زائدة	{"a": 1,} أو [1, 2,]	ليس لدى JSON فواصل زائدة؛ القواعد النحوية القياسية &#39؛s ببساطة لا تسمح بواحدة قبل قوس الإغلاق أو القوس
اقتباسات مفردة	{'name': 'Liton'}	يجب أن تستخدم السلاسل والمفاتيح علامات اقتباس مزدوجة؛ علامات الاقتباس المفردة هي عادة جافا سكريبت، وليست JSON
فاصلة مفقودة	{"a": 1 "b": 2}	يجب أن يسبق كل عضو بعد الأول فاصلة
تعليقات	{"a": 1} // note	JSON ليس لديه بناء جملة التعليق؛ ال // وكل شيء بعد ذلك هو محتوى غير متوقع
مفتاح غير مقتبس	{name: "Liton"}	المفاتيح عبارة عن سلاسل ويجب اقتباسها، على عكس الكائنات الحرفية لـ JavaScript
الصفر الرائد	{"n": 007}	قد لا يحتوي الرقم على صفر بادئ، لذا 007 غير صالح؛ يكتب 7
زائدة العلامة العشرية	{"n": 5.}	يحتاج الكسر بعد العلامة العشرية إلى رقم واحد على الأقل
حرف التحكم الخام	علامة تبويب حرفية أو سطر جديد داخل سلسلة	يجب الهروب من أحرف التحكم داخل السلاسل \t، \nوما إلى ذلك
نان أو إنفينيتي	{"n": NaN}	هذه صالحة في JavaScript ولكنها ليست قيم JSON
سلسلة غير منتهية	{"a": "oops}	يتم تشغيل سلسلة بدون اقتباس إغلاق حتى نهاية الإدخال

كل واحد من هذه ينتج رسالة بلغة عادية وموضعًا. تعد حالة "الصفر البادئة" مثالًا رائعًا لسبب مساعدة المحلل اللغوي المصمم لهذا الغرض: يقرأ المحلل اللغوي العام 007 كما الرقم 0 ثم رحلات فوق 7 as &quot؛ محتوى إضافي، واقتباس؛ مشيرا لك في 7، عندما تكون المشكلة الحقيقية هي الصفرين الموجودين أمامه. يتحقق المدقق من نمط الصفر البادئ أولاً ويخبرك بذلك مباشرة.

ماذا عن المفاتيح المكررة؟

هذا هو الذي عضني في الإنتاج أكثر من أي خطأ في بناء الجملة، لأنه ليس خطأ في بناء الجملة على الإطلاق. هذا صحيح JSON:

{
  "timeout": 30,
  "retries": 3,
  "timeout": 60
}

يقول RFC 8259 الأسماء الموجودة داخل الكائن &quot؛ يجب أن يكون فريدًا، &quot؛ لكنه لا يمنع التكرارات، لذلك يتعين على المحلل اللغوي قبول ذلك. ما يحدث بعد ذلك هو المكان الذي تبدأ فيه المشكلة: يقول المعيار أن السلوك مع الأسماء المكررة لا يمكن التنبؤ به، ومن الناحية العملية يحتفظ كل محلل تقريبًا بالقيمة الأخيرة ويتجاهل القيم السابقة بصمت. لذلك يتم تحليل هذا الكائن إلى {"timeout": 60, "retries": 3}و ال "timeout": 30 لقد تم ضبطه بعناية في الجزء العلوي من الملف دون سابق إنذار. إذا قام شخصان بتحرير التكوين، أو حدث خطأ في عملية الدمج، أو أصدرت خطوة القالب نفس المفتاح مرتين، فسيكون لديك خطأ لن يقوم أي محلل بالإبلاغ عنه على الإطلاق.

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

كيف يختلف المدقق عن المنسق؟

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

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

ماذا تخبرك إحصائيات الهيكل؟

عندما يتم التحقق من صحة مستند، تقوم الأداة بالإبلاغ عن شكلها: عدد الكائنات والمصفوفات التي تحتوي عليها، وعدد المفاتيح، وعدد السلاسل، والأرقام، والقيم المنطقية، والأصفار، ومدى عمق تداخلها، وحجمها في كل من الأحرف وUTF-8 بايت. هذه ليست زخرفة. عندما يتم تسليمك استجابة API غير مألوفة، يخبرك رقم العمق في لمحة عما إذا كنت تتعامل مع سجل مسطح أو شجرة متداخلة بعمق، ويخبرك عدد المفاتيح تقريبًا بحجم العمل الذي سيتم تحليله.

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

كيف أستخدمه

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

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

الأسئلة المتداولة

لماذا يقول JSON الخاص بي أنه غير صالح عندما يبدو جيدًا؟

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

هل الرقم أو السلسلة الواحدة صالحة JSON بمفردها؟

نعم. بموجب RFC 8259، أي قيمة JSON هي نص JSON كامل، لذا 42، "hello"، true، و null يتم التحقق من صحة كل ذلك بأنفسهم. القاعدة التي تنص على أن المستوى الأعلى يجب أن يكون كائنًا أو مصفوفة جاءت من RFC 4627 الأقدم وتمت إزالتها في عام 2014. الأداة التي ترفض القيمة المجردة تتبع مواصفات قديمة.

هل يقوم المدقق بتغيير بياناتي أو تحميلها؟

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

لماذا يجب أن أهتم بالمفاتيح المكررة إذا كان JSON لا يزال صالحًا؟

لأن التكرار يعني دائمًا فقدان البيانات الذي لم تكن تقصده. يسمح المعيار بالمفاتيح المكررة ولكنه يترك التعامل معها غير محدد، وعمليًا يحتفظ المحللون بالقيمة الأخيرة فقط ويسقطون الباقي. إذن التكوين حيث timeout يظهر مرتين بهدوء يفقد الإعداد الأول. يحذرك المدقق من كل مفتاح متكرر بموضعه، وهي عادةً اللحظة التي تكتشف فيها دمجًا سيئًا أو خطأ في النسخ واللصق.

هل يمكن لهذا التحقق من صحة JSON من خلال التعليقات، مثل ملف إعدادات tsconfig أو VS Code؟

لا، وهذا متعمد. هذه الملفات هي JSON مع التعليقات (JSONC) أو JSON5، وهي تنسيقات منفصلة تخفف القواعد. يستهدف المدقق RFC 8259 الصارم، لذلك سيضع علامة على التعليق على أنه خطأ. إذا كنت بحاجة إلى تعليقات في ملف تكوين، فهذه إشارة إلى أن التنسيق يجب أن يكون شيئًا مصممًا له، مثل YAML أو TOML، بدلاً من أن يتجاوز JSON ما يسمح به المعيار.

ما الفرق بين التحقق من صحة وتنسيق JSON؟

يتحقق التحقق من صحة النص مما إذا كان النص يخضع لقواعد JSON، وإذا لم يكن كذلك، يخبرك بالضبط بمكان انقطاعه. يفترض التنسيق أن النص صالح بالفعل ويقوم فقط بضبط المسافة البيضاء الخاصة به لسهولة القراءة. تصل إلى أداة التحقق عندما يكون هناك خطأ ما وتحتاج إلى معرفة ما هو؛ يمكنك الوصول إلى المنسق عندما يكون كل شيء على ما يرام وتريد فقط أن يكون قابلاً للقراءة. تقوم هذه الأداة بالأمرين معًا، ولكن سبب وجودها هو التشخيص.

ما حجم الملف الذي يمكنني التحقق من صحته؟

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