أدوات المطور · JSON المنسق والمدقق
صالح JSON مقابل صالح مقابل المخطط: معنيان لـ "صالح"
· خلفية
json المعايير تصديق
إن أداة التحقق التي تقول إن JSON صالحة تعني فقط أنها تقوم بالتحليل. يشرح هذا المنشور مستويات الصلاحية (بناء الجملة والبنية والدلالات) وسبب وجود المخطط JSON لكل شيء خارج القواعد النحوية.
صالحة، وما زالت مرفوضة
يمكن أن يكون الطلب خاليًا من الأخطاء JSON ولا يزال غير مقبول بالنسبة إلى API. تحتوي `{"username":"nori","plan":"gold"}` على محددات متوازنة وأسماء مقتبسة وقيم قانونية، ومع ذلك قد تتطلب الخدمة بريدًا إلكترونيًا أو ترفض اسم الخطة أو تمنع إنشاء الحساب في الحالة الحالية. يقوم المحلل اللغوي والتطبيق بالإجابة على أسئلة مختلفة، لذلك يمكن أن تكون كلا النتيجتين صحيحتين.
ToolAcre يجيب فقط على السؤال الأول: هل يمكن تحليل هذا النص باعتباره JSON صارمًا ضمن حدود الإدخال الخاصة به؟ لا يقوم بتحميل مخطط أو التحقق من الخصائص المطلوبة أو التحقق من التنسيقات أو الاتصال بقاعدة بيانات أو تقييم قواعد العمل. عندما تقول الأداة "صالح"، اقرأ ذلك على أنه "بناء جملة JSON جيد الصياغة"، وليس كموافقة من النظام الذي سيستهلك القيمة.
المستوى الأول: بناء الجملة بشكل جيد
يتحقق التحقق من صحة بناء الجملة من القواعد النحوية JSON: قيمة واحدة ذات مستوى أعلى، وحاويات مقترنة بشكل صحيح، وأسماء كائنات مقتبسة، وفواصل ونقطتين صالحتين، وسلاسل قانونية، وأرقام قانونية، وأحرف حرفية دقيقة. فهو يرفض `NaN` و`Infinity` والتعليقات والفواصل الزائدة والسلاسل ذات علامات الاقتباس المفردة. وهو يقبل أي شكل صحيح نحويًا، بما في ذلك الرقم الوحيد أو الكائن الذي يحتوي على حقول غير مألوفة.
يحتوي المصدر المشوه على نقطة فشل نصية، لذلك يمكن لـ ToolAcre الإبلاغ عن سطر وعمود للحرف المستحيل الأول. قد تتسبب الفاصلة المفقودة في الإبلاغ عن الاقتباس التالي؛ قد تتسبب الفاصلة الزائدة في الإبلاغ عن محدد الإغلاق. يؤدي إصلاح بناء الجملة إلى إنشاء قيمة قابلة للتحليل، لكنه لا يثبت أن القيمة لها الشكل أو المعنى المتوقع بواسطة برنامج آخر.
المستوى الثاني: الشكل
يسأل التحقق من صحة الشكل ما إذا كانت القيمة التي تم تحليلها تتطابق مع عقد معلن. قد يتطلب مخطط المستخدم `email`، ويقيد `age` بعدد صحيح على الأقل 18، ويحد `tier` إلى `free` أو `pro`، ولا يسمح بالخصائص غير المعروفة. `{"email":false,"tier":"gold"}` هو بناء جملة JSON صالح ولكنه يفشل في تلك القواعد الهيكلية لأن أنواع القيم والاختيارات المسموح بها خاطئة.
JSON يعد المخطط إحدى الطرق للتعبير عن مثل هذه القيود، لكن ToolAcre لا ينفذه. يُبلغ مدقق المخطط عادةً عن مسار مثيل مثل `/tier`، وكلمة أساسية مثل `enum`، ورسالة توضيحية بدلاً من علامة إقحام المحلل اللغوي. احتفظ بإصدار المخطط وعقد API بجانب الحمولة عند تشخيص هذا المستوى؛ لن يؤدي تغيير علامات الترقيم إلى إصلاح القيمة التي تم تحليلها بشكل صحيح للشكل الخاطئ.
المستوى الثالث: المعنى
يعتمد المعنى على حقائق وقواعد تتجاوز الشكل الثابت للوثيقة. يمكن أن يحتوي `accountId` على نمط السلسلة الصحيح أثناء عدم تسمية أي حساب. يمكن أن يتطابق تاريخ البدء مع تنسيق نمط ISO بينما يقع بعد تاريخ الانتهاء. يمكن أن تكون الكمية موجبة ولكنها تتجاوز المخزون الحالي. تتطلب حالات الفشل هذه سياق التطبيق أو الحالة المخزنة أو العلاقات بين الحقول.
يمكن تقريب بعض القيود الدلالية في المخطط، ولكن الكثير منها ينتمي إلى منطق الخدمة حيث تتوفر البيانات الموثوقة وحالة المعاملة. يجب أن تحدد استجابات الأخطاء في هذا المستوى الحقل أو القاعدة ذات الصلة دون التظاهر بأن النص JSON مكتوب بشكل غير صحيح. لا يمكن لـ ToolAcre إعادة إنتاج تلك القرارات لأنه لا يعرف العقد ولا يرسل الإدخال إلى التطبيق الذي يمتلك قاعدة العمل.
مثال عملي: حمولة واحدة من خلال ثلاث عمليات فحص
ابدأ بـ `{"sku":"A-19","quantity":3,"warehouse":"north"}`. ToolAcre يقبلها: تتبع جميع الأسماء والقيم القواعد النحوية JSON. يمكن أن يتطلب المخطط بعد ذلك كائنًا وسلسلة غير فارغة SKU وكمية صحيحة موجبة وأحد رموز المستودع الموثقة. لنفترض أن هذه الحمولة تتجاوز هذه القيود أيضًا. لم يؤكد أي من الشيكتين وجود SKU A-19 أو أن الشمال يحتوي على ثلاث وحدات.
تقوم خدمة المخزون بإجراء الفحص الثالث مقابل السجلات الحالية وقد ترفض الطلب باعتباره غير متوفر. تغيير المسافة البادئة لا يمكن أن يغير تلك النتيجة. إذا تمت كتابة `quantity` بالشكل `03`، فسيفشل بناء الجملة أولاً؛ إذا كان `"3"`، فسيتم تمرير التحليل ولكن سيفشل التحقق من نوع المخطط؛ باستخدام الرقم `3`، تبقى قاعدة المخزون المباشر فقط. ولذلك يمكن أن يفشل نفس الحقل في ثلاث طبقات مختلفة لثلاثة أسباب مختلفة.
حيث ينتمي كل شيك
قم بتشغيل التحقق من صحة بناء الجملة في أقرب وقت ممكن أثناء التحرير، لأن عمليات التحقق اللاحقة لا يمكن أن تعمل بشكل موثوق على النص الذي لا يتم تحليله. قم بفرض الشكل المعلن عند كل حدود تطبيق غير موثوق بها بدلاً من افتراض أن العميل قام بذلك بالفعل. قم بتقييم ثوابت الأعمال في المكون الذي يمتلك الحالة المطلوبة، خاصة عندما يمكن أن تتغير الإجابة بين الطلبات.
تعمل عمليات التحقق من جانب العميل على تحسين الملاحظات ولكنها لا تحل محل التنفيذ من جانب الخادم. وعلى العكس من ذلك، يجب حجز استجابة الخادم التي تقول "JSON غير صالحة" لتحليل الفشل بدلاً من استخدامها لكل طلب مرفوض. يؤدي الفصل الواضح إلى تشخيصات مفيدة: سطر وعمود لبناء الجملة، ومسارات مثيل للقيود الهيكلية، ورموز أو رسائل خاصة بالمجال للتعارضات الدلالية. ToolAcre توفر الفئة الأولى فقط.
ما لا يغطيه هذا
لا يقوم هذا المنسق بتأليف مخطط JSON أو تقييمه، أو تحديد مسودة المخطط، أو تحليل مراجع المخطط، أو إدراج الإعدادات الافتراضية، أو إجبار السلاسل على تحويلها إلى أرقام. كما أنه لا يعرف مستند OpenAPI الخاص بـ API أو اصطلاحات التحقق المخصصة. لن يؤدي توفير مخطط إلى جانب الإدخال إلى تغيير نتيجة ToolAcre لأنه لا توجد خطوة لمعالجة المخطط في هذه الأداة.
التحقق من صحة بناء الجملة أيضًا لا يكشف عن أسماء الكائنات المكررة هنا؛ `JSON.parse` يحتفظ بآخر ظهور قبل التنسيق. كما أنها لا تضمن الدقة الرقمية أو البايتات الأساسية أو العرض الآمن أو التفويض. كل من هذه المخاوف يحتاج إلى عقد خاص به وتنفيذه. وتجنب ضغطها في شارة خضراء واحدة "صالحة"، لأن القيام بذلك يخفي الأدلة التي تم جمعها والأسئلة التي لم يتم طرحها على الإطلاق.
الوجبات الجاهزة: "صالح" يحتاج إلى مؤهل
تأهيل كل مطالبة التحقق من الصحة. "صالح JSON" يعني أن النص يتبع القواعد النحوية. تعني عبارة "صالحة مقابل هذا المخطط" أن القيمة التي تم تحليلها تلبي العقد الهيكلي المحدد. "مقبول من الخدمة" يعني أن قواعد التطبيق الحالية تسمح بالتشغيل. يعد تمرير طبقة واحدة أمرًا ضروريًا للطبقة التالية في العديد من عمليات سير العمل، ولكن لا يعد ذلك دليلاً على مرور جميع الطبقات اللاحقة.
استخدم ToolAcre للتنسيق والتحقق من بناء الجملة الصارم، بما في ذلك رفض الأحرف غير JSON مثل `NaN` و`Infinity`. ثم استخدم المخطط والتطبيق الذي يحكم الحمولة فعليًا. عندما يستمر فشل الطلب، اقرأ الخطأ في الطبقة الخاصة به بدلاً من إعادة التنسيق الصحيح JSON بشكل متكرر. لا تحتوي الأداة على فحوصات للمخطط، وهذا الحد الصريح أكثر فائدة من الوعد العام بالصلاحية.