я строю Toolz.devи до этого я потратил годы на доставку плагинов WordPress и API-интерфейсов Laravel. Во всем этом единственное сообщение об ошибке, на которое я потратил больше всего часов, - это некоторая вариация токена & quot;Unexpected в JSON на позиции 428.& quot; Он почти ничего не говорит вам. Нет ни строки, ни столбца, и позиция, которую он называет, часто состоит из нескольких символов за неправильной вещью. В конечном итоге вы вручную подсчитываете символы в минифицированной капле или вставляете всю полезную нагрузку в редактор и щурясь. Я построил JSON-валидатор поэтому мне никогда больше не придется этого делать, и это руководство к тому, что он делает и почему проверка JSON сложнее, чем кажется.
TL;DR: валидатор JSON проверяет текст по грамматике в RFC 8259 и, когда текст сломан, сообщает вам точную строку, столбец и символ первой ошибки, сформулированные с точки зрения того, что он ожидал. Он также улавливает вещи, которые скрывает обычный синтаксический анализатор: дубликаты ключей, которые бесшумно сворачиваются до последнего значения, и сообщает структуру действительного документа (объект, массив и подсчет ключей, глубина вложения и размер байта). Это не форматировщик. Форматировщик предполагает, что вход уже действителен; валидатор - это то, чего вы достигаете именно тогда, когда это не так.
Что значит для JSON быть действительным?
JSON - небольшой формат со строгой грамматикой. Текущий стандарт RFC 8259, который совпадает с ЭКМА-404, и между ними они определяют точно, что может содержать допустимый документ Текст JSON - это единичное значение Это значение - объект, массив, строка, число, true, false, или null. Объекты обернуты скобками и удерживаются разделенными запятыми "key": value пары. массивы обернуты в скобки и содержат значения, разделенные запятыми. Строки обернуты двойными кавычками, а не одиночными кавычками. Числа следуют определенной форме без ведущих нулей и задней десятичной точки. Комментариев нет, а конечных запятых нет.
В этом последнем предложении большинство реальных JSON ошибаются, потому что многие люди JSON пишут от руки, на самом деле это не JSON. Это файл конфигурации // комментарии или объект, скопированный из источника JavaScript, где отдельные кавычки и конечные запятые хороши, или отредактированное вручную приспособление, в котором кто-то добавил поле и оставил висячую запятую. Все это отклоняется строгим синтаксическим анализатором и валидатором 's задача состоит в том, чтобы отклонить их в определенном месте, а не пожимать плечами.
Стоит прояснить один момент, потому что он сбивает с толку людей, которые изучили JSON много лет назад: голая ценность - это полный и действительный документ JSON. 42 сам по себе действителен JSON. Так и есть "hello", и так true. Старый РФК 4627 требовал, чтобы верхний уровень был объектом или массивом, но это ограничение было снято в 2014 году, когда его заменил RFC 7159 (позже 8259). Если инструмент вам скажет 42 это недействительный JSON, этот инструмент соответствует спецификации, которая устарела более десяти лет.
Почему JSON.parse такой плохой репортер ошибок?
Причина, по которой специальный валидатор занимает свое место, заключается в том, что синтаксический анализатор, встроенный в ваш язык, оптимизирован для счастливого пути, а не для объяснения печального. JSON.parse в браузере бросает SyntaxError чье сообщение зависит от движка и обычно дает смещение символа без строки или столбца. V8 говорит & quot;Unexpected token} в JSON в позиции 148.& quot; Firefox говорит & quot;JSON.parse: неожиданный символ в строке 1 столбец 149.& quot; Safari снова говорит что-то другое. никто из них не говорит вам, чего они ожидали, и позиция измеряется с начала строки, что бесполезно в тот момент, когда ваш JSON имеет более пары строк.
Валидатор на Toolz.dev не использует JSON.parse. Он просматривает сам текст с помощью рукописного анализатора рекурсивного нисхождения, отслеживая строку и столбец по ходу движения, поэтому, когда он останавливается, он может передать вам все три координаты: строку, столбец и смещение абсолютного символа. Что еще более важно, он знает правило грамматики, в середине которого оно находится, поэтому сообщение является конкретным. Вместо "неожиданный токен, " вы получаете "Trailing запятая не допускается перед замыкающим скобком, " или "Ключи объекта должны быть строками с двойными цитатами, " или "Ожидает запятую или замыкающий скоб после элемента объекта." Эта разница заключается в разнице между исправлением файла за пять секунд и поиском его.
Он также рисует каретку под точным символом на оскорбительной линии, как это делает компилятор. Когда вы смотрите на строку 34 файла конфигурации, "столбец 12" в порядке, но a ^ сидеть прямо под бродячей цитатой быстрее.
Какие ошибки JSON валидатор улавливает по имени?
Это те сбои, которые я вижу чаще всего, как в своей собственной работе, так и в потоках поддержки для инструментов, подобных этому. валидатор называет каждый из них, а не сообщает об общей ошибке токена.
| Ошибка | Как это выглядит | Почему оно недействительно |
|---|---|---|
| Запятая | {"a": 1,} или [1, 2,] |
В JSON нет конечных запятых; стандартная грамматика 's просто не допускает ее перед закрывающей скобкой или скобкой |
| Одиночные кавычки | {'name': 'Liton'} |
Строки и клавиши должны использовать двойные кавычки; одиночные кавычки - это привычка JavaScript, а не JSON |
| Отсутствует запятая | {"a": 1 "b": 2} |
Каждому участнику после первого должна предшествовать запятая |
| замечания | {"a": 1} // note |
у JSON нет синтаксиса комментариев; // и все после него - неожиданное содержание |
| Нецитируемый ключ | {name: "Liton"} |
Ключи - это строки, которые необходимо цитировать, в отличие от литералов объектов JavaScript |
| Ведущий ноль | {"n": 007} |
Число может не иметь ведущего нуля, так что 007 недействителен; писать 7 |
| Замыкающая десятичная точка | {"n": 5.} |
Дробь после десятичной точки требует хотя бы одной цифры |
| Необработанный управляющий символ | буквальная вкладка или новая строка внутри строки | Управляющие символы внутри строк должны быть удалены как \t, \nи так далее |
| НаН или Бесконечность | {"n": NaN} |
Они действительны в JavaScript, но не являются значениями JSON |
| Непрекращенная строка | {"a": "oops} |
Строка без закрывающей кавычки проходит до конца ввода |
Каждый из них создает сообщение на простом языке и позицию. Случай ведущего нуля является хорошим примером того, почему помогает специально созданный синтаксический анализатор: читает общий синтаксический анализатор 007 как число 0 а затем поездки по 7 как "дополнительный контент, " указывая вам на 7, когда реальная проблема - это два нуля перед ним. сначала валидатор проверяет шаблон "лидер-ноль" и сообщает вам это напрямую.
А дубликаты ключей?
Вот тот, который укусил меня в производстве больше, чем любая синтаксическая ошибка, потому что это вовсе не синтаксическая ошибка Это действительно JSON:
{
"timeout": 30,
"retries": 3,
"timeout": 60
}
RFC 8259 говорит имена внутри объекта & quot; ДОЛЖЕН быть уникальным, & quot; но он не запрещает дубликаты, поэтому синтаксический анализатор обязан принять это. Далее происходит следующее: стандарт гласит, что поведение с дублированными именами непредсказуемо, и на практике почти каждый синтаксический анализатор сохраняет последнее значение и молча отбрасывает более ранние. Итак, этот объект анализирует {"timeout": 60, "retries": 3}, и "timeout": 30 вы тщательно установили в верхней части файла ушел без предупреждения Если два человека редактировали конфигурацию, или слияние пошло не так, или шаблон шаг излучал один и тот же ключ дважды, у вас есть ошибка, которую ни один парсер никогда не пометит для вас.
Валидатор помечает его. обнаружение дубликатов ключей включено по умолчанию, и поскольку дубликат является законным, он сообщается как предупреждение, а не ошибка: документ все еще действителен, но вам сообщается каждый ключ, который появляется более одного раза в одном и том же объекте, с его строкой и a Указатель JSON путь, чтобы вы могли найти его внутри вложенной структуры. Если вы действительно хотите дубликаты, вы можете выключить чек. Большую часть времени, видя предупреждение, вы понимаете, что пошло не так.
Чем валидатор отличается от форматировщика?
Люди используют слова взаимозаменяемо, и инструменты пересекаются, но они отвечают на разные вопросы. а Форматтер JSON берет JSON, который вы уже считаете действительным, и перепечатывает его с последовательным отступом, чтобы человек мог его прочитать. Если вы передаете форматировщик сломанный JSON, лучшее, что он может сделать, это отказаться. валидатор' вся цель - сломанный случай: он сообщает вам, где и почему. валидатор Toolz.dev выполняет обе работы, потому что, как только он подтвердил, что документ действителен, он уже проанализировал его, поэтому он довольно печатает результат в одном проходе. Но особенностью заголовка является диагноз, а не отступ.
Те же отношения существуют и с соседними инструментами. The Минификатор JSON полосы пробелы для уменьшения полезной нагрузки, что имеет смысл только на действительных входных данных. The Сортировщик JSON переупорядочивает ключи для стабильных различий, опять же на действительных входных данных. The Побег JSON и побег инструмент занимается встраиванием JSON внутрь строки. И тестер JSONPath запросы документ, который вы уже подтвердили, хорошо сформирован.Валидация - это шаг, который стоит перед всеми ними, поэтому именно его я запускаю первым всякий раз, когда ответ API или файл конфигурации ведет себя странно. Существует более широкий обзор того, как они сочетаются друг с другом в Полное руководство по инструментам JSON, йо-
О чем говорит вам статистика структуры?
Когда документ проверяет, инструмент сообщает о его форме: сколько объектов и массивов он содержит, сколько клавиш, сколько строк, чисел, логических значений и нулей, насколько глубоко он гнездится, и его размер как в символах, так и в байтах UTF-8. Это не украшение. Когда вам вручают незнакомый ответ API, число глубины с первого взгляда сообщает вам, имеете ли вы дело с плоской записью или глубоко вложенным деревом, а количество клавиш примерно показывает, сколько работы будет анализировать.
Цифра байта имеет большее значение, чем ожидают люди. Ограничения размера запроса, ограничения очереди сообщений и пределы столбцов базы данных почти всегда измеряются байтами, а не символами, и они различаются в тот момент, когда ваш JSON содержит что-либо за пределами ASCII. Смайлик или имя с акцентом - это один символ на экране, но два, три или четыре байта на проводе. Если полезная нагрузка сталкивается с ограничением в 256 КБ, количество символов вводит вас в заблуждение, а количество байтов не будет. Проверяющий вычисляет истинную длину UTF-8 байтов, поэтому число, которое вы видите, является числом, которое считается пределом.
Как я использую его
Мой рабочий процесс скучен и быстр, и в этом суть. Когда интеграция прерывается, я копирую необработанное тело ответа прямо из вкладки сети и вставляю его в валидатор. Если оно действительно, зеленый результат и статистика говорят мне, что проблема где-то еще, в моем коде, а не в их данных, и я исключил целый класс причин за две секунды. Если оно недействительно, я получаю строку и столбец, исправляю его и продолжаю. Когда я вручную редактирую файл конфигурации, я вставляю его перед фиксацией, в основном для того, чтобы поймать конечную запятую, которую я всегда оставляю позади, и случайный дубликат ключа из копипасты. Для любого, кто собирает свой собственный комплект, валидатор сидит рядом с другими предметами первой необходимости в копировальной вставке Набор инструментов для веб-разработчиков, йо-
Угол конфиденциальности также не является второстепенным. Люди JSON больше всего должны проверить именно тот JSON, с которым им следует быть наиболее осторожными: ответы API, содержащие токены, файлы конфигурации с учетными данными, полезные нагрузки с данными клиента. Все, что делает валидатор, происходит в вашем браузере, в JavaScript, на вашем компьютере. Ничего не загружается, не регистрируется и не сохраняется. Вы можете доказать это, открыв вкладку сети во время проверки или отключившись от Интернета и наблюдая, как инструмент продолжает работать.
Часто задаваемые вопросы
Почему мой JSON говорит, что он недействителен, когда выглядит нормально?
Самые распространенные причины - это конечная запятая перед закрывающей скобкой или скобкой, одиночные кавычки, где JSON требует двойные кавычки, отсутствующая запятая между двумя участниками или комментарий, который JSON вообще не разрешает Все четыре легко пропустить на глаз, особенно в большом файле. валидатор называет то, которое он нашел, и дает вам точную строку и столбец, поэтому вместо сканирования всего документа вы переходите прямо к символу, на котором он остановился.
Допустим ли один номер или строка JSON сам по себе?
Да. В соответствии с RFC 8259 любое значение JSON является полным текстом JSON, так что 42, "hello", true, и null все проверяют сами по себе Правило, что верхний уровень должен быть объектом или массивом, пришло из более старого RFC 4627 и было удалено в 2014 г. Инструмент, который отклоняет голое значение, следует устаревшей спецификации.
Изменяет ли валидатор или загружает мои данные?
Нет. Он анализирует текст в вашем браузере и никогда никуда не отправляет. на действительном документе он создает красиво напечатанную копию для удобства, но эта копия генерируется локально, и оригинал никогда не передается, не регистрируется и не сохраняется. Поскольку сервера туда и обратно нет, инструмент также работает с сетью, отключенной после загрузки страницы.
Почему меня должны волновать дубликаты ключей, если JSON все еще действителен?
Потому что дубликат почти всегда означает потерю данных, которую вы не собирались Стандарт разрешает дублировать ключи, но оставляет их обработку неопределенной, и на практике парсеры сохраняют только последнее значение и опускают остальное. Итак, конфигурация где timeout появляется дважды незаметно теряет первую настройку. валидатор предупреждает вас о каждом повторяющемся ключе с его положением, которое обычно является моментом, когда вы обнаруживаете плохое слияние или ошибку копипаста.
Может ли это проверить JSON с комментариями, например файлом настроек tsconfig или VS Code?
Нет, и это преднамеренно. эти файлы являются JSON с комментариями (JSONC) или JSON5, которые являются отдельными форматами, которые ослабляют правила. валидатор нацелен на строгий RFC 8259, поэтому он пометит комментарий как ошибку. Если вам нужны комментарии в файле конфигурации, это сигнал, формат должен быть что-то созданное для него, например YAML или TOML, а не JSON, растянутый выше того, что позволяет стандарт.
В чем разница между проверкой и форматированием JSON?
Проверка проверяет, подчиняется ли текст грамматике JSON, и, если нет, сообщает вам, где именно он разбивается. форматирование предполагает, что текст уже действителен, и только корректирует его пробелы для читаемости. Вы тянетесь к валидатору, когда что-то не так, и вам нужно знать, что; вы тянетесь к форматировщику, когда все в порядке, и вы просто хотите, чтобы он был читабельным. Этот инструмент делает и то, и другое, но причина его существования - диагноз.
Насколько большой файл я могу проверить?
Комфортно в десятки мегабайт, ограничен только вашим браузером и памятью #39;s, потому что весь документ анализируется за один проход на вашем устройстве. нет ограничения размера загрузки, потому что нет загрузки. Для действительно огромного файла в гигабайтах валидатор потоковой командной строки является лучшим инструментом, поскольку браузер хранит весь текст в памяти одновременно.
