JSON Escape وUnescape: تضمين أي نص في JSON دون كسره

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

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

ليرة تركية؛DR: لا يمكن أن تحتوي سلسلة JSON على علامة اقتباس مزدوجة أولية، أو شرطة مائلة عكسية أولية، أو أحرف تحكم أولية مثل الأسطر الجديدة وعلامات التبويب. الهروب يستبدل كل منها بتسلسل شرطة مائلة عكسية - " يصبح \"، يصبح السطر الجديد \n، تصبح علامة التبويب \tوأي شيء آخر أقل من U+0020 يصبح \uXXXX. يؤدي Unescaping إلى تحويل تلك التسلسلات مرة أخرى إلى الأحرف الأصلية. ال هروب من جيسون / نزهة تقوم الأداة بالأمرين معًا في متصفحك، مع خيارات لتغليف النتيجة بين علامتي اقتباس، والهروب من غير ASCII \uXXXX، أو الهروب من الشرطة المائلة إلى الأمام.

ماذا يعني الهروب من سلسلة لـ JSON؟

لدى JSON قواعد نحوية دقيقة ومنشورة - يتم تعريفها بواسطة RFC 8259 وبمعيار ECMA-404 - وقواعد ما قد يظهر داخل السلسلة صارمة. سلسلة JSON عبارة عن سلسلة من الأحرف ملفوفة بعلامات اقتباس مزدوجة. لأن علامة الاقتباس المزدوجة تشير إلى بداية السلسلة ونهايتها، فهي علامة اقتباس مزدوجة داخل سينهي النص قبل الأوان. نظرًا لأن الشرطة المائلة العكسية تبدأ تسلسل الهروب، فسيتم قراءة الشرطة المائلة العكسية الأولية بشكل خاطئ على أنها بداية واحدة. ولأن سلاسل JSON من المفترض أن تكون سطرًا منطقيًا واحدًا من النص، فلا يُسمح لأحرف التحكم الحرفية - الأسطر الجديدة وعلامات التبويب وإرجاع الأحرف - بالجلوس بداخلها دون هروب.

الهروب هو عملية استبدال كل حرف من هذه الأحرف المزعجة بتسلسل مائلة عكسية مكون من حرفين يفهمه JSON. يصبح الاقتباس المزدوج \". تصبح الشرطة المائلة العكسية \\. يصبح السطر الجديد \n. والنتيجة هي النص الذي يبدو أقبح قليلاً ولكن أصبح الآن آمنًا للهبوط بين علامتي اقتباس دون كسر المستند المحيط. المعنى متطابق - قراءة محلل JSON \n ينتج خطًا جديدًا حقيقيًا مرة أخرى - لكن التمثيل أصبح الآن قانونيًا.

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

ما هي الشخصيات التي تحتاج بالفعل إلى الهروب؟

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

الهروب الإلزامي المكون من حرف واحد هو الاقتباس المزدوج (\") والشرطة المائلة العكسية (\\). أبعد من ذلك، يحدد JSON عمليات الهروب القصيرة لخمسة أحرف تحكم شائعة: مسافة للخلف (\b)، شكل تغذية (\f)، سطر جديد (\n)، عودة النقل (\r)، وعلامة التبويب الأفقية (\t). أي آخر يجب كتابة حرف التحكم - أي شيء به نقطة رمز أسفل U+0020 وليس له نموذج قصير - كـ \u الهروب متبوعًا بأربعة أرقام سداسية عشرية، وبالتالي تصبح البايتة فارغة \u0000 و&quot؛ فاصل الوحدة وquot؛ يصبح \u001F.

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

هل يجب أن أهرب من الشرطة المائلة للأمام والأحرف غير ASCII؟

هاتان الهربتان الاختياريتان موجودتان لأسباب حقيقية، حتى لو كنت نادرًا ما تحتاج إليهما.

يعد الهروب من الشرطة المائلة للأمام أمرًا مهمًا في موقف شائع واحد بالضبط: عندما يتم تضمين JSON داخل HTML <script> علامة. يبحث محلل HTML للمتصفح &#39؛ عن التسلسل الحرفي </ للعثور على نهاية كتلة البرنامج النصي، لذلك تحتوي السلسلة على </script> في JSON الخاص بك، يمكنك إغلاق العلامة قبل الأوان وكسر الصفحة. كتابة الشرطة المائلة كما <\/script> - لا يزال JSON صالحًا، ولا يزال نفس السلسلة بمجرد تحليلها - يتجنب ذلك. خارج البرامج النصية المضمنة، يمكنك ترك الشرطة المائلة بمفردها، ولهذا السبب تترك الأداة الشرطة المائلة الأمامية دون الهروب افتراضيًا.

الهروب من الشخصيات غير ASCII مثل \uXXXX يتعلق الأمر بقابلية النقل وليس بالصواب. إذا كان JSON الخاص بك قد يمر عبر نظام يشوه بايتات UTF-8 - خط أنابيب تسجيل قديم، ووكيل تم تكوينه بشكل خاطئ، وقناة تفترض ASCII - مما يحول كل حرف فوق نطاق ASCII إلى ASCII خالص \u يضمن الهروب بقائه سليمًا. يكون الإخراج أكبر حجمًا وأقل قابلية للقراءة من قبل الإنسان، لذا فهو معطل افتراضيًا، ولكن &quot؛الهروب Unicode&quot؛ التبديل موجود في الوقت الحالي الذي تحتاج فيه إلى نقل مضاد للرصاص. نقطة رمز مثل é يصبح \u00e9، ويقوم محلل JSON بإعادة بناء الشخصية الأصلية في طريق الخروج.

كيف يعمل عدم الهروب، ومتى أحتاج إليه؟

Unescaping هو العكس تمامًا: فهو يمر عبر سلسلة تم الهروب منها ويعيد كل تسلسل مائلة عكسية إلى الحرف الخام الذي يمثله. \n يصبح خطًا جديدًا حقيقيًا، \t تصبح علامة تبويب، \" يصبح اقتباسًا مزدوجًا، و \uXXXX يصبح الحرف عند نقطة الرمز تلك. أنت في حاجة إليها عندما تكون على الطرف المتلقي - لقد قمت بنسخ قيمة سلسلة مباشرة من ملف JSON، أو سطر سجل، أو استجابة API، وتريد قراءة النص الأصلي بدون شاشة مليئة بالشرطة المائلة العكسية في الطريق.

يقوم الشخص الجيد بشيئين، أما البحث والاستبدال الساذج فلا يفعل ذلك. أولاً، يقوم بتجريد زوج واحد من علامات الاقتباس المزدوجة المحيطة إذا تم اقتباس القيمة بأكملها، حتى تتمكن من لصقها "line one\nline two" مباشرة من مستند JSON واحصل على نص نظيف مرة أخرى. ثانيا، ذلك يتحقق كما هو الحال: تسلسل هروب غير صالح مثل \x، أو شرطة مائلة عكسية طائشة في نهاية السلسلة، هو خطأ حقيقي، و هروب من جيسون / نزهة تقوم الأداة بالإبلاغ عن موقعها بدلاً من التخمين وإنتاج مخرجات خاطئة بصمت. الحصول على واضح وحاصل؛ الهروب غير صالح في الموضع 14&quot؛ يتفوق على الحصول على نص يبدو صحيحًا تقريبًا ولكنه تالف بمهارة.

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

الهروب مقابل عمليات السلسلة ذات الصلة

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

عملية	يحمي ضد	مثال	أداة
هروب جيسون	كسر سلسلة JSON باستخدام علامات الاقتباس أو الشرطة المائلة العكسية أو أحرف التحكم	he said "hi" → he said \"hi\"	هروب من جيسون / نزهة
ترميز كيان HTML	كسر HTML أو تمكين XSS باستخدام <، >، &	<b> → &lt;b&gt;	كيانات HTML
رمز نسبة URL	كسر عنوان URL بمسافات أو أحرف محجوزة	a b → a%20b	-
تنسيق/تحقق من صحة JSON	الأخطاء الهيكلية عبر المستند بأكمله	مصغرة → مطبوعة بشكل جميل	تنسيق JSON
JSON → YAML	نقل التكوين بين تنسيقات التسلسل	{"a":1} → a: 1	JSON إلى YAML

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

ما هي الأخطاء الشائعة عند تضمين النص في JSON؟

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

الثانية القريبة هي الهروب المزدوج. إذا تم بالفعل الهروب من سلسلة مرة واحدة وهربت منها مرة أخرى، فكل منها \n يصبح \\n وتتحول أسطرك الجديدة إلى شرطة مائلة عكسية حرفية لن يقوم أي محلل بتحويلها مرة أخرى. يحدث هذا عادةً عندما تمر قيمة عبر نظامين يهرب كل منهما منها بشكل مفيد. إذا كان الإخراج الخاص بك لديه عمليات تشغيل مشبوهة \\ عندما تتوقع خطوطًا مائلة عكسية مفردة، فمن المحتمل أن تكون قد هربت مرتين، وسيقوم عدم الهروب مرة واحدة بإصلاحها. المصيدة الثالثة هي نسيان أن مسار Windows مثل C:\Users\me مليئة بالخط المائل العكسي، كل منها يجب أن يصبح \\ - المسار الذي لم يتم الهروب منه في JSON هو مصدر كلاسيكي لـ &quot؛ لماذا JSON الخاص بي غير صالح واقتباس؛ ارتباك.

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

مثال عملي: تضمين مقتطف HTML في JSON

اسمحوا لي أن أتطرق إلى الموقف الدقيق الذي بدأ هذا، لأن رؤية التحول مرة واحدة تجعل القاعدة ثابتة. قل أنك تريد إرسال هذا الجزء باعتباره body حقل طلب API:

<p>Hi "there",</p>
<p>Visit https://example.com/path</p>

ثلاثة أشياء في هذا النص سوف تتقاتل مع JSON. الاقتباسان المزدوجان حولهما there سيحاول كل منهم إنهاء السلسلة. السطر الجديد بين الفقرات هو حرف تحكم حرفي يحظره JSON داخل السلسلة. و ال </p> التسلسلات غير ضارة في ملف JSON عادي ولكنها خطيرة إذا تمت طباعة JSON هذا داخل HTML <script> علامة. لصق الجزء في هروب من جيسون / نزهة أداة، تشغيل &quot؛ التفاف بين علامات الاقتباس، واقتباس؛ وتحصل على سلسلة JSON واحدة صالحة: تصبح علامات الاقتباس \"، يصبح السطر الجديد \nومع &quot؛ الهروب إلى الأمام شرطة مائلة وحاصل؛ تمكين العلامات الختامية تصبح <\/p>. قم بإسقاط هذه القيمة المقتبسة بالكامل مباشرة في حسابك body الحقل ويمر الطلب.

الرحلة العكسية هي مجرد روتين. عندما يرسل لك أحد زملائك في الفريق سطر سجل به JSON-escaped message الحقل مليء \n و \"، الصقها في الأداة، وانتقل إلى Unescape، واقرأ النص الأصلي متعدد الأسطر مع اختفاء الخطوط المائلة العكسية. نظرًا لأن العمليتين عبارة عن معكوسين تمامًا، يمكنك نقل الحمولة للخارج لتحريرها والعودة إليها دون خوف من الفساد - يؤكد ملخص عدد الأحرف أن التحويل قد تم، ويتم وضع علامة على أي هروب مشوه بموضعه بدلاً من تشويه النص بصمت. إن أمان الرحلة ذهابًا وإيابًا هو ما يحول الهروب من خطوة يدوية عصبية إلى شيء يمكنك توصيله بسير العمل ونسيانه.

الأسئلة الشائعة

ماذا يعني الهروب من سلسلة لـ JSON؟ لا يمكن أن تحتوي قيم سلسلة JSON على علامة اقتباس مزدوجة أولية، أو شرطة مائلة عكسية أولية، أو أحرف تحكم أولية مثل الأسطر الجديدة وعلامات التبويب. يستبدل الهروب كل واحد منها بتسلسل شرطة مائلة عكسية - &quot؛ يصبح &quot؛ يصبح السطر الجديد \n، وتصبح علامة التبويب \t - بحيث يمكن وضع النص داخل سلسلة JSON دون كسر البنية المحيطة.

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

ما هي الشخصيات التي هربت؟ يتم دائمًا الهروب من الاقتباس المزدوج (&quot؛)، والشرطة المائلة العكسية (\)، والمسافة الخلفية (\b)، وتغذية النموذج (\f)، والسطر الجديد (\n)، وإرجاع النقل (\r)، وعلامة التبويب (\t)، جنبًا إلى جنب مع أي حرف تحكم آخر أسفل U+0020 كـ \uXXXX. اختياريًا، تصبح الشرطة المائلة للأمام /ويصبح كل حرف غير ASCII \uXXXX.

هل يجب أن أهرب من الشرطة المائلة للأمام؟ إنه اختياري. تسمح مواصفات JSON بكلا من / و/، لذا فإن/plain صالح. المكان الوحيد/الأمور موجود داخل HTML