أدوات المطور · JSON المنسق والمدقق
قم بإصلاح package.json المكسور قبل أن يقوم CI: قراءة موضع الخطأ
· لماذا يهم
json سير عمل المطور تصديق
يفشل package.json أو composer.json أو launch.json الذي تم تحريره يدويًا بعد فترة طويلة من حفظه، عادةً في CI. يوضح هذا المنشور كيفية التحقق من الصحة قبل الالتزام وقراءة موضع الخطأ بسرعة.
اثنتا عشرة دقيقة من خط الأنابيب للتعرف على فاصلة واحدة
اثنتا عشرة دقيقة من المسار للتعرف على فاصلة واحدة - يتم حل تعارض الدمج يدويًا، ومحرر أخضر وبنية حمراء. يمكن أن يبدو تسجيل الخروج من المستودع طبيعيًا لأن Git يسجل البايتات، وليس ما إذا كان البيان يوزع أم لا. يقوم CI بعد ذلك بتثبيت التبعيات، ويصل إلى الملف التالف ويتوقف قبل أن توفر الاختبارات أي إشارة مفيدة.
تتحقق الأداة من بناء الجملة JSON الصارم فقط وتقبل المستندات التي يصل عددها إلى 8,000,000 JavaScript حرفًا. package.json وcomposer.json هما مثالان صارمان مناسبان. قد تستخدم ملفات مثل tsconfig.json محللًا متسامحًا مع التعليقات، لذا فإن رفض تعليقاتها كـ JSON لا يثبت أن الأداة المالكة سترفضها. التحقق من صحة القواعد النحوية التي يعلنها برنامج الاستهلاك بالفعل.
ما هي ملفات التكوين JSON التي تنكسر في أغلب الأحيان
أي ملفات التكوين JSON تنكسر في أغلب الأحيان - package.json، composer.json، launch.json وقفل الملفات، ولماذا tsconfig.json، الذي يسمح بالتعليقات، يحتاج إلى رعاية منفصلة. تميل البيانات التي يحررها الإنسان إلى الفشل حول كتل التبعية والبرامج النصية وإعدادات الأدوات المتداخلة. تفشل ملفات القفل التي تم إنشاؤها بشكل مختلف: يمكن أن يؤدي حل التعارض اليدوي إلى إتلاف المحددات أو تكرار الأقسام الهيكلية.
لا تفترض أن كل ملف له امتداد يشبه JSON يستخدم JSON بشكل صارم. تسمح إعدادات VS Code وتكوين TypeScript عادةً بالتعليقات أو الفواصل اللاحقة من خلال محللين متخصصين، في حين أن بيانات الحزم لا تسمح بذلك بشكل عام. تحقق من صحة ملف القفل الذي تم إنشاؤه باستخدام مدير الحزم الخاص به عندما يكون ذلك ممكنًا، لأن بناء الجملة الصحيح وحده لا يمكنه استعادة التجزئة أو ترتيب القواعد أو الاتساق الداخلي المتوقع بواسطة هذا المولد.
لماذا تفشل الأدوات في وقت متأخر - يقوم مديرو الحزم والمترجمون بتحليلها عند الطلب، لذلك يظهر خطأ في بناء الجملة عند التثبيت أو وقت الإنشاء بدلاً من الحفظ
لماذا تفشل الأدوات في وقت متأخر - يقوم مديرو الحزم والمترجمون بتحليلها عند الطلب، لذلك يظهر خطأ في بناء الجملة عند التثبيت أو وقت الإنشاء بدلاً من الحفظ. قد يقوم محرر النصوص بتلوين الأقواس دون تشغيل المحلل اللغوي المعتمد، وقد لا تتم قراءة البيان الذي تم تغييره أثناء مهمة محلية ضيقة. يبدأ CI من بيئة نظيفة ويمارس مسارات الإعداد التي تتخطاها محطات العمل المخزنة مؤقتًا.
يتضمن التأخير الناتج وقت الانتظار، والخروج، وإعداد التبعية، والمهام الأولية غير ذات الصلة. والأسوأ من ذلك، أن الرسالة النهائية قد تقوم فقط بتسمية ملف حزمة غير صالح أثناء إخفاء السطر الأصلي خلف إخراج الأمر. يؤدي التحليل المحلي مباشرة بعد التحرير إلى انهيار حلقة التعليقات هذه. كما أنه يفصل الفشل النحوي عن أخطاء تحليل التبعية أو أخطاء المخطط اللاحقة التي تتطلب تحقيقًا مختلفًا.
قراءة موضع الخطأ تحت الضغط
قراءة موضع الخطأ تحت الضغط - السطر والعمود، والرمز المميز السابق، وأنماط تعارض الدمج الثلاثة التي تنتج JSON غير صالح. الشخصية المميزة هي حيث يصبح الاستمرار مستحيلا، وليس دائما حيث بدأ الخطأ. قد يكشف الاقتباس الختامي عن الاقتباس السابق الذي لم يتم تجاوزه؛ قد تكشف القوستين عن فاصلة مفقودة مباشرة قبل الخاصية التالية.
بعد عمليات الدمج، ابحث عن علامات التعارض التي تركت كنص عادي، وكتل الأعضاء المكررة التي تم ضمها بدون فاصلة، والمحددات المحذوفة أثناء اختيار جانب واحد. افحص الرمز المميز قبل الموقع المُبلغ عنه واحسب حدود الحاوية المحيطة. قم بإجراء إصلاح واحد، وأعد تشغيل التحقق من الصحة واحتفظ بالفرق الأصلي، لأن المحلل اللغوي عادةً ما يبلغ عن العائق الأول فقط وقد يظل التعارض المستقل الثاني بعيدًا.
مثال عملي: package.json بعد عملية دمج سيئة
مثال عملي: package.json بعد عملية دمج سيئة - كتلة تبعيات مكررة، وفاصلة مفقودة، وتقرير المدقق والإصلاح. تخيل `"scripts":{"test":"vitest"}` متبوعًا مباشرة بـ `"dependencies":{"vite":"7.3.6"}`. اسم الخاصية الثاني هو المكان الذي يكتشف فيه المحلل اللغوي أن الكائن يفتقر إلى فاصل، على الرغم من أن الفاصلة التصحيحية تنتمي إلى كائن البرامج النصية.
أدخل تلك الفاصلة وتحقق من صحتها مرة أخرى قبل التنسيق. إذا أدى الدمج أيضًا إلى إنتاج مفتاحين `dependencies`، فقد ينجح التحليل الصارم لأن الأسماء المكررة مسموح بها من الناحية النحوية، ومع ذلك فإن تحليل JavaScript يحتفظ فقط بالقيمة الأحدث. قارن كلا الفرعين واجمع الأعضاء المقصودين بدلاً من حذف الكتلة ميكانيكيًا. يعد إصلاح بناء الجملة ودقة الدمج الدلالي من المهام المتتابعة والمتميزة.
جعل التحقق من الصحة عادة
جعل التحقق عادة — الصق قبل الالتزام، أو تحقق من صحة أي JSON قمت بتحريره خارج IDE، دون الحاجة إلى حساب أو مكون إضافي. أفضل محفز هو سلوكي: كلما تم حل علامات التعارض، تم نقل كتلة كبيرة أو كتابة علامات الترقيم يدويًا، قم بتشغيل فحص الأداة المالكة أو محلل صارم قبل تنظيم الملف.
يمكن للمستودعات أتمتة نفس القاعدة من خلال فحص ما قبل الالتزام ووظيفة CI المخصصة للبيانات، ولكن يجب أن تكمل الأتمتة التعليقات الفورية بدلاً من أن تصبح المحلل اللغوي الأول. احتفظ بالتنسيق منفصلاً عن الإصلاح حتى يظهر الفرق الحرف ذي المعنى. بالنسبة للملفات التي تم إنشاؤها، قم بإعادة الإنشاء من بيان المصدر بدلاً من تطبيع الإخراج الذي تم تحريره يدويًا، ثم اسمح للمولد بإثبات ثوابته.
ما لا يغطيه هذا
ما لا يغطيه هذا هو الأخطاء الدلالية مثل نطاق إصدار خاطئ أو حقل غير معروف، والتي لا يمكن لـ JSON الصالح حمايتك منها. يمكن تحليل بيان الحزمة أثناء تسمية برنامج نصي غير موجود، أو وضع تبعية في القسم الخطأ أو استخدام تعبير إصدار يتم حله بشكل غير متوقع. يمكن للمفاتيح المكررة أيضًا اجتياز عمليات التدقيق النحوي أثناء استبدال القيم السابقة بصمت.
استخدم التحقق من صحة مدير الحزم والمخططات وتثبيت الاختبارات ومراجعة تلك الطبقات. لا يثبت هذا الفحص أيضًا أن ملف القفل يطابق البيان الخاص به أو أن تكوين التشغيل يسمي مصحح أخطاء مثبتًا. إذا كان التنسيق الفعلي هو JSONC أو لهجة أخرى، فاستخدم المحلل اللغوي الخاص به بدلاً من إزالة بناء الجملة المدعوم فقط لتلبية JSON الصارم. القواعد هي البوابة الأولى، وليس عقد التكوين الكامل.
الوجبات الجاهزة: يستغرق التحقق من بناء الجملة ثوانٍ، بينما يكلف خط الأنابيب الفاشل دقائق
الخلاصة: يكلف فحص بناء الجملة ثوانٍ، ويكلف خط الأنابيب الفاشل دقائق - ويؤدي التقرير الدقيق للمدقق إلى تقصير عملية الإصلاح. قم بتشغيله على وحدات البايت النهائية التي تم تحريرها، وابدأ من السطر والعمود المُبلغ عنهما، ثم افحص الرمز المميز السابق بحثًا عن فاصل أو محدد مفقود. قم بإعادة التحقق بعد كل تصحيح لأنه يمكن إخفاء الأخطاء اللاحقة في البداية.
بمجرد اجتياز صياغة صارمة، ارجع إلى المستهلك: قم بتشغيل مدير الحزم أو المترجم أو التحقق الخاص بالمحرر الذي يفهم الحقول والقيم المسموح بها. اجعل فروق الإصلاح ضيقة، خاصة بعد عمليات الدمج، حتى يتمكن المراجعون من التمييز بين علامات الترقيم وقرارات التبعية. يلتقط هذا التسلسل الفشل الأرخص محليًا ويحتفظ بوقت باهظ الثمن للسلوك الذي لا يمكن تقييمه إلا للبيئة الكاملة.