Восстановление сломанного JSON: типичные ошибки и способы автоматического исправления

JSON строг по своей природе. В отличие от JavaScript, здесь нет снисхождения к отсутствующим кавычкам, висячим запятым или случайным комментариям. Когда JSON ломается, парсеры выбрасывают непонятные ошибки и приложение перестаёт работать. В этом руководстве рассматриваются причины поломок JSON, наиболее распространённые паттерны ошибок и способы их исправления — вручную или автоматически.

Почему ломается JSON

Повреждение JSON редко происходит в данных, сгенерированных продакшн-системами. Почти всегда причиной является взаимодействие с человеком.

Ручное редактирование

Разработчики часто вручную редактируют конфигурационные JSON-файлы, мок-данные или API-пейлоады. Одной пропущенной кавычки или лишней запятой достаточно, чтобы сделать весь документ невалидным. Текстовые редакторы без JSON-aware линтинга не предоставляют никакой защиты.

Неполное копирование и вставка

Копирование фрагмента JSON из консоли браузера, лог-файла или сообщения в чате часто захватывает лишь часть структуры. В результате получаются незакрытые скобки, отсутствующие ключи или осиротевшие значения.

Усечённые логи

Системы агрегации логов накладывают ограничения на длину строки или размер данных. JSON-объект, превышающий лимит, обрезается на середине, оставляя структурно невалидный фрагмент, который необходимо восстановить перед парсингом.

Путаница форматов

Разработчики иногда пишут JSON, используя синтаксис JavaScript — одинарные кавычки, неквотированные ключи, комментарии — а затем пытаются разобрать это строгим JSON-парсером. Результат всегда — ошибка парсинга.

Распространённые паттерны ошибок

Висячие запятые

Самая частая ошибка в JSON. JSON не допускает запятую после последнего элемента в объекте или массиве.

// Неверно
{
  "name": "Alice",
  "age": 30,
}

// Верно
{
  "name": "Alice",
  "age": 30
}

Для массивов действует то же правило:

// Неверно
["red", "green", "blue",]

// Верно
["red", "green", "blue"]

Одинарные кавычки

JSON-строки требуют двойных кавычек. Одинарные кавычки — это соглашение JavaScript, а не стандарт JSON.

// Неверно
{ 'host': 'localhost', 'port': 5432 }

// Верно
{ "host": "localhost", "port": 5432 }

Комментарии

В JSON нет синтаксиса для комментариев. Ни //, ни /* */ не входят в спецификацию.

// Неверно
{
  // Подключение к базе данных
  "host": "localhost",
  "port": 5432 /* порт по умолчанию */
}

// Верно
{
  "host": "localhost",
  "port": 5432
}

Если вам нужны комментарии в конфигурационных файлах, рассмотрите JSONC (JSON with Comments) или YAML, и конвертируйте в обычный JSON перед передачей парсерам.

Неквотированные ключи

Ключи объектов всегда должны быть строками в кавычках. Голые идентификаторы не допускаются.

// Неверно
{ host: "localhost", port: 5432 }

// Верно
{ "host": "localhost", "port": 5432 }

Отсутствующие или лишние скобки

Неполное копирование и вставка часто оставляет незакрытые квадратные или фигурные скобки.

// Неверно — массив не закрыт
[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob"

// Верно
[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob" }
]

Экранированные символы

Специальные символы внутри строк должны быть корректно экранированы. Неэкранированные управляющие символы, необработанные переводы строк или невалидные Unicode-последовательности вызовут ошибки парсинга.

// Неверно — необработанный символ табуляции в строке
{ "query": "SELECT *	FROM users" }

// Верно — экранированная табуляция
{ "query": "SELECT *\tFROM users" }

Стратегии ручного исправления

Для небольших JSON-документов ручное исправление несложно:

1. Внимательно прочитайте сообщение об ошибке. Большинство парсеров указывают номер строки и столбца. Перейдите прямо к этой позиции.
2. Проверьте баланс скобок. Подсчитайте открывающие { и [ относительно закрывающих } и ]. Они должны совпадать.
3. Ищите висячие запятые. Проверьте последний элемент перед каждым } и ].
4. Замените одинарные кавычки. Глобальная замена ' на " решит большинство проблем с кавычками, но будьте осторожны, чтобы не заменить апострофы внутри строковых значений.
5. Удалите комментарии. Уберите все строки // и блоки /* */ перед парсингом.

Для более крупных документов ручное исправление становится трудоёмким и чреватым ошибками.

Автоматическое восстановление

Инструменты автоматического восстановления применяют эвристические правила для реконструкции валидного JSON из повреждённых входных данных. Они надёжно справляются с наиболее распространёнными паттернами:

Когда автовосстановление работает

Автовосстановление надёжно, когда структура документа в основном сохранена и нужно исправить только синтаксические проблемы. Идеальные случаи:

• Конфигурационный файл, случайно сохранённый с висячими запятыми
• Фрагмент лога, вставленный из консоли JavaScript (которая использует одинарные кавычки в выводе)
• JSON-объект, написанный разработчиком, забывшим заквотировать ключи
• Документ с комментариями разработчика, который нужно привести к валидному JSON

В этих сценариях инструменты восстановления могут реконструировать идеально валидный JSON без потери данных.

Когда автовосстановление не работает

Инструменты восстановления не могут восстановить семантическое намерение. Они дадут сбой или выдадут некорректный результат в следующих случаях:

• Серьёзное усечение. Если половина документа отсутствует, инструмент может закрыть открытые скобки, но полученный JSON будет неполным и может не соответствовать намерению автора.
• Неоднозначная структура. Голое значение вроде hello без окружающего контекста не может быть надёжно классифицировано как ключ, строковое значение или идентификатор.
• Повреждение кодировки. Бинарные данные, внедрённые в JSON-поток, или несоответствия кодировки символов требуют совершенно другого класса исправлений.
• Конфликты вложенных кавычек. Строковое значение, содержащее неэкранированные двойные кавычки, создаёт неоднозначность, которую эвристическое восстановление не может разрешить безопасно.

Всегда проверяйте автоматически восстановленный вывод перед использованием в продакшне.

Использование инструмента восстановления JSONKit

Инструмент Repair на JSONKit применяет многоуровневый пайплайн восстановления к повреждённым входным данным JSON:

1. Вставьте или загрузите сломанный JSON
2. Инструмент определяет паттерны ошибок и применяет соответствующие исправления
3. Просмотрите исправленный вывод в представлении diff, чтобы увидеть, что именно изменилось
4. Скопируйте исправленный JSON или загрузите его как файл

Представление diff особенно полезно — оно позволяет убедиться, что восстановление изменило только синтаксис и не затронуло значения данных.

Заключение

Ошибки JSON неизбежны, когда в процесс вовлечён человек. Понимание типичных причин — висячие запятые, одинарные кавычки, неквотированные ключи, комментарии и усечение — даёт чёткую ментальную модель для быстрой диагностики проблем. Для простых синтаксических ошибок инструменты автовосстановления справляются за секунды. Для серьёзно повреждённых данных понимание базовой структуры — единственный надёжный путь к восстановлению.