Инструменты разработчика · JSON форматировщик и валидатор
Объяснение экранирования строк JSON: \n, \uXXXX и управляющие символы
· Как это работает
JSON рабочий процесс разработчика проверка
Необработанная новая строка внутри строки JSON недействительна, как и табуляция. В этом посте рассказывается о восьми escape-последовательностях, о том, как работают escape-последовательности \u и суррогатные пары, а также о том, почему вставленный абзац может сделать недействительным весь файл.
Абзац, который нарушил полезную нагрузку
Абзац, который нарушил полезную нагрузку: вставка видимого разрыва строки в описание в кавычках вставляет управляющий символ непосредственно в строку JSON. Первая строка выглядит завершенной, но открывающая кавычка по-прежнему ожидает строкового содержимого или закрывающей кавычки. Когда анализатор достигает необработанного перевода строки, он останавливается на этом месте, поскольку строки JSON не могут таким образом охватывать физические строки. Текст должен содержать двухсимвольный escape-символ `\n` везде, где для декодированного значения требуется перевод строки.
Табуляции, скопированные из документа или электронной таблицы, вызывают тот же класс сбоев, даже если редактор может представить их как безобидные пробелы. Замените литеральную табуляцию на `\t`, возврат каретки на `\r` и другие запрещенные элементы управления на их именованные символы или escape-символы в Юникоде.
Восемь escape-символов JSON позволяют
Восемь escape-символов JSON позволяют - после обратной косой черты короткие формы: `"`, `\\`, `\/`, `\b`, `\f`, `\n`, `\r` и `\t`. Они представляют собой кавычки, обратную косую черту, косую черту, возврат налево, перевод страницы, перевод строки, возврат каретки и горизонтальную табуляцию. Косая черта также может отображаться неэкранированной; `\/` существует в основном для совместимости с контекстами, которые когда-то обрабатывали последовательность закрывающих сценариев особым образом.
Никакая другая буква не может следовать за обратной косой чертой JSON. Последовательности, знакомые по языкам программирования, такие как `\v`, `\0`, `\x41` или обратная косая черта, за которой следует физический символ новой строки, здесь недопустимы. Используйте `\u`, за которым следуют ровно четыре шестнадцатеричные цифры, если короткого перехода не существует. Этот небольшой фиксированный словарь обеспечивает переносимость строк JSON: потребителю не нужны JavaScript, Python или специальные правила escape для оболочки, чтобы определить символы, представленные допустимым текстом.
Почему буквальная табуляция недопустима, но буквальная é подойдет
Почему литеральная табуляция недействительна, а литеральная é подходит — JSON запрещает неэкранированные кодовые точки от U+0000 до U+001F внутри строк. Этот диапазон содержит вкладки, символы новой строки и другие элементы управления, невидимые эффекты которых могут нарушить кадрирование или отображение. Буква `é` — это U+00E9, что находится далеко за пределами контрольного диапазона, поэтому UTF-8 JSON может включать ее непосредственно в кавычки. То же самое относится и к большинству шрифтов, символов и смайлов.
Таким образом, экранирование обычного Unicode не является обязательным, а не требованием чистоты. `"café"` и `"caf\u00e9"` декодируются в одну и ту же последовательность символов. Прямой текст обычно легче читать людям, а escape-последовательности могут помочь при транспортировке только для ASCII или сделать видимой определенную единицу кода. Управляющие символы разные: их выход обязателен.
Как работают escape-последовательности \uXXXX
Как работает escape-последовательность `\uXXXX`: за `u` должны следовать ровно четыре шестнадцатеричные цифры, используя в любом случае 0–9 или A–F. `\u00E9` представляет собой кодовую единицу UTF-16 для `é`, а `\u000A` представляет собой перевод строки. Меньшее количество цифр, фигурные скобки, такие как `\u{1F600}`, или нешестнадцатеричная буква делают JSON недействительным, даже если другой язык программирования принимает эту запись.
Символы выше U+FFFF представлены в этой escape-форме как суррогатная пара. Эмодзи 😀 можно записать как `\uD83D\uDE00`: старший и младший суррогатные значения после анализа объединяются в одно скалярное значение Юникода. Грамматика JSON может содержать непарный суррогатный escape-код, но последующие кодировщики и приложения могут отклонить или заменить его, поскольку он не идентифицирует полный символ Юникода.
Рабочий пример: экранирование пути Windows и фрагмента HTML
Рабочий пример: экранирование пути Windows и фрагмента HTML — для предполагаемого пути `C:\Temp\report.txt` необходимо, чтобы каждая обратная косая черта была удвоена в источнике JSON: `"C:\\Temp\\report.txt"`. Без удвоения `\T` является недопустимым escape-символом, а такие последовательности, как `\r` или `\t`, могут автоматически стать управляющими символами вместо разделителей пути. Создайте JSON из предполагаемого значения, не угадывая, какие отображаемые косые черты уже принадлежат внешнему языку.
Фрагмент HTML, такой как `<a title="Report">Open</a>`, может сохранять угловые скобки и косую черту буквально, но кавычки атрибута должны стать `\"` внутри строки JSON. Если новая строка разделяет два тега, закодируйте ее как `\n`. Полученный элемент JSON можно проверить и проанализировать обратно в исходный текст HTML.
Где побеги удваиваются
Там, где escape-символы удваиваются, каждая грамматика включающего текста получает свой собственный шанс интерпретировать обратную косую черту. Документ JSON, содержащий декодированную строку `line1\nline2`, должен избегать этой обратной косой черты, создавая `"line1\\nline2"`. Если этот текст JSON сам хранится как строка JSON, его кавычки и обе обратные косые черты нуждаются в еще одном уровне экранирования. Очевидный беспорядок отражает множественные представления, а не специальную расширенную форму JSON.
Оболочки и литералы языка программирования добавляют свои собственные правила кавычек до того, как синтаксический анализатор JSON увидит аргумент. Диагностика изнутри: сначала запишите точное декодированное значение, один раз закодируйте его как JSON, затем закодируйте этот полный текст JSON для окружающей оболочки или исходного языка. На каждой границе проверьте, какие байты или символы действительно получает следующий анализатор.
Что это не распространяется
Что здесь не распространяется — объекты HTML, такие как `"`, и процентное кодирование URL, такое как `%20`, представляют собой отдельные преобразования для отдельных синтаксических контекстов. Анализатор JSON не декодирует ни одну из форм. Строка `"""` после анализа содержит шесть буквальных символов, а не кавычек, а `"%20"` содержит знак процента, за которым следуют две цифры, а не пробел. Применяйте эти кодировки только тогда, когда данные пересекают компонент HTML или URL.
Это обсуждение также не заменяет кодирование вывода. Действительный JSON, полученный из ненадежного источника, может по-прежнему содержать HTML, текст, подобный сценарию, или последовательности управления терминалом как обычные строковые данные. Приложение, которое позже отображает или выполняет команду, должно безопасно обрабатывать этот пункт назначения. Экранирование JSON защищает структуру JSON; это не всеобщая санитария.
Вывод: избегайте того, что запрещает грамматика, не более того.
Вывод: избегайте того, что запрещает грамматика, не более того — двойные кавычки, обратные косые черты и кодовые точки ниже U+0020 требуют внимания внутри строк JSON. Обычный Unicode может оставаться читаемым, тогда как `\uXXXX` предоставляет точную четырехзначную альтернативу, а суррогатные пары представляют символы выше U+FFFF. Диагностика явно пустой позиции часто идентифицирует буквальную новую строку, табуляцию или другой управляющий символ, который необходимо заменить его текстовым escape-символом.
Подсчитайте слои кодирования вместо того, чтобы считать косые черты на глаз. Начните со значения, которое должно получить приложение, закодируйте его один раз для JSON и только затем цитируйте полученный документ для любой внешней оболочки, исходного файла или второй строки JSON. Проверьте текст, представленный анализатору JSON, и, если правильность имеет значение, впоследствии проверьте декодированную строку.