Ошибка, которая заставила меня построить этот инструмент, была безумно маленькой. Я набивал шаблон электронной почты HTML - несколько сотен строк с цитатами, разрывами строк и нечетной обратной косой чертой - в поле JSON для отправки в API, и запрос продолжал возвращаться как 400. Шаблон был в порядке. JSON был в порядке сам по себе. Но в тот момент, когда они встретились, неэкранированная двойная цитата из трехсот символов молча закрыла строку раньше, и все, что после этого превратилось в мусор, синтаксический анализатор не мог иметь смысла. Я вставил действительный текст в действительный контейнер и создал недействительный документ.
В этом вся проблема, которую решает JSON, и ее стоит понять, а не работать. В этом руководстве рассказывается о том, что на самом деле делает побег, каких персонажей необходимо сбежать и почему, как его обращает вспять бегство и как использовать бесплатное JSON Escape / UNESCAPE инструмент для перемещения произвольного текста в строки JSON и из них без единого сбоя молчания. Он находится рядом с другими утилитами данных, о которых я написал в Полное руководство по инструментам JSON, йо-
TL;DR: Строка JSON не может содержать необработанную двойную кавычку, необработанную обратную косую черту или необработанные управляющие символы, такие как новые строки и вкладки. Escaping заменяет каждый последовательностью обратной косой черты -
"становиться\"становится новая строка\nвкладка становится\tи все остальное ниже U+0020 становится\uXXXX. Unescaping превращает эти последовательности обратно в оригинальные символы. The JSON Escape / UNESCAPE инструмент делает и то, и другое в вашем браузере, с возможностью обернуть результат кавычками, избежать не-ASCII как\uXXXX, или избежать косой черты вперед.
Что значит избежать строки для JSON?
У JSON есть точная опубликованная грамматика - она определяется RFC 8259 и по стандарту ECMA-404 - и правила для того, что может появиться внутри строки строгие. строка JSON - это серия символов, обернутых двойными кавычками. потому что двойная кавычка отмечает начало и конец строки, двойная кавычка внутренняя часть текст закончит его преждевременно. поскольку обратная косая черта начинает escape-последовательность, необработанная обратная косая черта будет неправильно прочитана как начало одной. И поскольку строки JSON предназначены для единой логической строки текста, буквальные управляющие символы - новые строки, вкладки, возвраты каретки - не могут сидеть внутри них незамеченными.
Побег - это процесс замены каждого из этих проблемных символов двухсимвольной последовательностью обратной косой черты, которую понимает JSON. Двойная цитата становится \". Обратная косая черта становится \\. Становится новая строка \n. Результатом является текст, который взгляды немного уродливее, но теперь безопасно опускаться между двумя кавычками, не разбивая окружающий документ. значение идентично - считывание анализатором JSON \n снова создает настоящую новую линию, но теперь представительство законно.
Это принципиально отличается от форматирования документа JSON Форматировщик упорядочивает структуру целого объекта: отступ, порядок ключей, пробелы между элементами.Escaping работает на один уровень ниже, на содержимое одного строкового значения. Вы тянетесь к Форматтер JSON когда у вас есть целый документ, который можно красиво распечатать или проверить, и для JSON Escape / UNESCAPE инструмент, когда у вас есть кусок необработанного текста, который вам нужно поместить в одно поле.
Каким персонажам действительно нужно сбежать?
Спецификация JSON здесь освежающе специфична. Внутри строки ровно два символа должник всегда будьте избежаны, плюс весь диапазон управляющих символов.
Двумя обязательными односимвольными побегами являются двойная цитата (\") и обратная косая черта (\\). Помимо этого, JSON определяет короткие экраны для пяти общих управляющих символов: backspace (обратное пространство)\b), формируют корм (\f), новая линия (\n), возврат каретки (\r) и горизонтальная вкладка (\t). Любой другой управляющий символ - все, что имеет кодовую точку ниже U+0020 и не имеет краткой формы - должно быть записано как \u за экранированием следуют четыре шестнадцатеричные цифры, поэтому становится нулевой байт \u0000 и & quot; unit сепаратор& quot; становится \u001F, йо-
Еще два персонажа опционально чтобы убежать, и вот тут-то и закрадывается путаница. передний слэш может быть записан как \/, но это не обязательно должно быть - просто / является совершенно действительным JSON. И любой символ выше диапазона ASCII, как акцентированный é или смайлик может быть написан буквально в документе UTF-8 или экранирован как \uXXXX; оба законны. The JSON Escape / UNESCAPE инструмент всегда обрабатывает обязательные побеги и предоставляет вам переключатели для двух дополнительных, чтобы вы могли соответствовать всем ожиданиям вашей целевой системы.
Должен ли я избежать символов передней косой черты и не-ASCII?
Эти два необязательных побега существуют по реальным причинам, даже если они вам редко нужны.
Ускорение прямой косой черты имеет значение ровно в одной распространенной ситуации: когда JSON встроен в HTML <script> тег. Браузер и HTML-парсер #39;s ищет буквальную последовательность </ чтобы найти конец блока сценариев, необходимо использовать строку, содержащую </script> в вашем JSON можно преждевременно закрыть тег и разбить страницу. записывая косую черту как <\/script> - все еще действительный JSON, та же строка после анализа - избегает этого. За пределами встроенных сценариев вы можете оставить косые черты в покое, поэтому инструмент по умолчанию оставляет косую черту без экранирования.
Ускользающие символы, отличные от ASCII, как \uXXXX речь идет о переносимости, а не о корректности. если ваш JSON может пройти через систему, которая искажает байты UTF-8 - старый конвейер регистрации, неправильно настроенный прокси-сервер, канал, который принимает ASCII - превращая каждый символ над диапазоном ASCII в чистый ASCII \u побег гарантирует, что он выживет нетронутым. вывод более громоздкий и менее удобочитаемый, поэтому он выключен по умолчанию, но "Escape Unicode" переключение есть на момент, когда вам нужен пуленепробиваемый транспорт. Кодовая точка, как é становиться \u00e9, и анализатор JSON реконструирует исходный символ на выходе.
Как работает бегство и когда оно мне нужно?
Unescaping - это точная обратная сторона: он проходит через экранированную строку и превращает каждую последовательность обратной косой черты обратно в необработанный символ, который она представляет. \n становится настоящей новой линией, \t становится вкладкой, \" становится двойной цитатой, и \uXXXX становится символом в этой кодовой точке. Он нужен вам всякий раз, когда вы находитесь на принимающей стороне - вы скопировали значение строки прямо из файла JSON, строки журнала или ответа API, и вы хотите прочитать исходный текст без экрана с обратными косыми чертами на пути.
Хороший unescaper делает две вещи, которых нет у наивного find-and-replace. во-первых, он удаляет одну пару окружающих двойных кавычек, если цитируется все значение, поэтому вы можете вставить "line one\nline two" прямо из документа JSON и получите чистый текст обратно. Во-вторых, это проверяет как бы то ни было: недопустимая escape-последовательность типа \x, или случайная обратная косая черта в самом конце строки, является настоящей ошибкой, и JSON Escape / UNESCAPE инструмент сообщает о своем положении, а не угадывает и выдает молча неправильный вывод. Получение четкого & quot;недопустимый выход в позиции 14& quot; бьет получение текста, который выглядит почти правильно, но слегка поврежден.
Ключевое свойство доверять заключается в том, что побег и бегство являются точными обратными. Ускользнуть от любого текста, а затем избежать результата, и вы получите обратно именно то, с чего начали, характер за характер. что гарантия туда и обратно это то, что делает безопасным использование инструмента как рутинный шаг в конвейере, а не рискованное преобразование вы должны перепроверить вручную.
Побег от связанных строковых операций
JSON escaping - один из семейства & quot;сделайте этот текст безопасным для этого контекста & quot; трансформируется, и это помогает держать их прямо. Вот как его сравнивают с соседями, с которыми разработчики чаще всего путают.
| Операция | Защищает от | пример | стрелка |
|---|---|---|---|
| JSON побег | Разбивка строки JSON с помощью кавычек, обратных косых черт или управляющих символов | he said "hi" → he said \"hi\" |
JSON Escape / UNESCAPE |
| Кодировка сущности HTML | Разрыв HTML или включение XSS с <, >, & |
<b> → <b> |
HTML-объект |
| процент URL-кода | Разбивка URL-адреса пробелами или зарезервированными символами | a b → a%20b |
-- |
| Формат/проверка JSON | Структурные ошибки во всем документе | минифицированный → красиво напечатанный | Форматтер JSON |
| ДЖСОН → ЯМЛ | Перемещение конфигурации между форматами сериализации | {"a":1} → a: 1 |
json в yaml |
Обратите внимание, что каждый побег нацелен на a необычайный контейнер. сущности HTML не позволяют тексту взламывать HTML; процентное кодирование не позволяет ему взломать URL-адрес; Побег JSON не позволяет ему взломать строку JSON. Использование неправильного - кодирования HTML-кода чего-то, что требует выхода JSON - оставляет реальную проблему нерешенной и добавляет новый уровень шума. Поскольку все это работает с текстом, который вы, возможно, не захотите передавать стороннему серверу, я сохраняю каждый из этих инструментов на стороне клиента, что является аргументом, который я привел полностью в руководство по конфиденциальности данных для онлайн-инструментов, йо-
Какие ошибки часто встречаются при встраивании текста в JSON?
Единственная наиболее распространенная ошибка - та, которая стоила мне дня: вставить многострочный текст с неэкранированными цитатами прямо в поле JSON и предположить, что, поскольку обе части действительны, все действительно. Это не так - контейнер имеет правила, которым должно подчиняться содержимое.
Близкая секунда двойной побег. Если строка уже однажды была экранирована и вы снова избегаете ее, каждый \n становиться \\n и ваши новые строки превращаются в буквальную обратную косую черту-n, которую ни один анализатор не преобразует обратно. Обычно это происходит, когда значение проходит через две системы, каждая из которых помогает избежать его. Если ваш вывод имеет подозрительные пробеги \\ там, где вы ожидали одиночных обратных косых черт, вы, вероятно, дважды сбежали, и однажды, не сбежав, вы исправите это. Третья ловушка - забыть, что путь Windows, как C:\Users\me полон обратных косых черт, каждая из которых должна стать \\ - неэкранированный путь в JSON - классический источник & quot; почему мой JSON недействителен& quot; путаница.
Исправление для всех трех одинаково: пусть инструмент выполняет выход ровно один раз, на границе, где необработанный текст встречается с JSON, и прочитает показанное им резюме подсчета символов, чтобы проверить здравомыслие, что что-то изменилось. Когда вам нужно вручную проверить, убегите с помощью "заверните в кавычки и кавычки; включите и вставьте результат в Форматтер JSON - если он анализируется как допустимая строка, ваш выход правильный.
Рабочий пример: встраивание фрагмента HTML в JSON
Позвольте мне пройти через точную ситуацию, которая начала это, потому что вид трансформации однажды делает правило прилипшим. Скажите, что вы хотите отправить этот фрагмент как body поле запроса API:
<p>Hi "there",</p>
<p>Visit https://example.com/path</p>
Три вещи в этом тексте будут бороться с JSON. Два двойных кавычка вокруг there попытается ли каждый закончить строку. Новая строка между абзацами - это буквальный управляющий символ, который JSON запрещает внутри строки. И </p> последовательности безвредны в обычном файле JSON, но опасны, если этот JSON когда-либо будет напечатан внутри HTML <script> тег. Вставьте фрагмент в JSON Escape / UNESCAPE инструмент, включите & quot;wrap в кавычки, & quot; и вы получите единственную, действительную строку JSON: кавычки становятся \", новая строка становится \n, а с помощью & quot;escape fward slash& quot; включили закрывающие теги становятся <\/p>. Бросьте всю указанную стоимость прямо в свой адрес body поле и запрос проходит.
Обратный путь так же рутинный Когда товарищ по команде отправляет вам лог-линию с JSON-сбежавший message поле, полное \n а \", вставить его в инструмент, переключиться на Unescape, и прочитать исходный многострочный текст с обратными косыми чертами исчез. Поскольку две операции являются точными обратными, вы можете переместить полезную нагрузку, чтобы отредактировать его и обратно в без страха повреждения - сводка подсчета символов подтверждает трансформацию запущена, и любой искаженный побег помечен его положение вместо молча искажения текста. что безопасность туда и обратно - это то, что превращает выход из нервного ручного шага в нечто, что вы можете подключить в рабочий процесс и забыть о.
Часто задаваемые вопросы
Что значит избежать строки для JSON? Строковые значения JSON не могут содержать необработанную двойную кавычку, необработанную обратную косую черту или необработанные управляющие символы, такие как новые строки и вкладки. Escaping заменяет каждый из них последовательностью обратной косой черты - & quot; становится & quot;, новая строка становится \n, вкладка становится \t - так что текст можно поместить внутрь строки JSON, не нарушая окружающую структуру.
Чем это отличается от форматтера JSON? Форматтер JSON красиво печатает или минимизирует целый документ JSON и проверяет его структуру. Этот инструмент работает на один уровень вниз, на содержимом одной строки: он делает произвольный текст безопасным для встраивания в значение JSON или декодирует выделенное значение обратно в необработанный текст. Используйте форматтер для документов и этот инструмент для отдельных строк.
Какие персонажи сбегают? Двойная кавычка (& quot;), обратная косая черта (\), обратное пространство (\b), подача формы (\f), новая строка (\n), возврат каретки (\r) и вкладка (\t) всегда экранируются, наряду с любым другим управляющим символом ниже U+0020 как \uXXXX. Необязательно, прямая косая черта становится /, и каждый символ, не относящийся к ASCII, становится \uXXXX.
Должен ли я избежать слэша вперед? Это необязательно. спецификация JSON допускает как /, так и /, поэтому просто/действительно. Единственное место / имеет значение находится внутри HTML
