Выбор инструмента JSON diff: текстовый diff, структурный diff и визуализация

Коротко: текстовый diff обнаруживает изменение (сначала сортируйте ключи через jq -S), структурный diff решает эквивалентность (выравнивайте массивы по первичному ключу), а визуализация лишь объясняет или помогает ревью; в CI держите эти три слоя раздельно.

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

1. Три вида «diff» — не одно и то же

Многие команды воспринимают «сравнить JSON» как одно действие, а затем натыкаются на одни и те же проблемы в разных сценариях. Полезно разделить три слоя:

Текстовый diff не имеет зависимостей, быстр и естественно интегрируется с Git. Его слабость в том, что он ничего не знает о семантике JSON. Два полностью эквивалентных документа засветятся красным и зелёным, если у них различается порядок ключей или отступы. Структурный diff — наоборот: сначала разбирает, потом сравнивает, поэтому распознаёт, что значение всего лишь переместилось. Но ему нужна правильная стратегия выравнивания массивов, иначе одна вставка прочитается как полная перезапись.

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

2. Текстовый diff: сначала очистите порядок ключей через jq -S

Для быстрого взгляда на два файла самая дешёвая комбинация — jq -S плюс diff -u. Флаг -S рекурсивно сортирует ключи объектов, нормализуя документы, содержимое которых идентично, но порядок ключей различается:

复制jq -S . a.json > a.sorted.json
jq -S . b.json > b.sorted.json
diff -u a.sorted.json b.sorted.json

Это устраняет самое частое ложное срабатывание. RFC 8259 определяет объекты как неупорядоченные коллекции, поэтому {"a":1,"b":2} и {"b":2,"a":1} — одно и то же значение. Текстовый diff, однако, помечает каждую строку как изменённую. Сортировка заранее делает красные блоки гораздо ближе к реальным проблемам.

Учтите, что jq -S сортирует только ключи и не сортирует массивы. Порядок массива в JSON значим, и [1,2] — не то же значение, что [2,1], поэтому инструмент не примет это решение за вас. Если массив по смыслу является неупорядоченным множеством, сортируйте его по первичному ключу самостоятельно до сравнения.

Есть ещё одна деталь, которую стоит запомнить: diff завершается с кодом 1, когда находит различия, но отсутствующий файл или ошибка прав доступа тоже дают ненулевой код. В CI не считайте любой ненулевой код «содержимое изменилось», иначе опечатка в пути будет отчитана как изменение данных. Более безопасный шаблон сначала проверяет файлы, а затем обрабатывает различие:

复制if ! diff -u a.sorted.json b.sorted.json; then
  echo "JSON content differs" >&2
  exit 1
fi

delta делает текстовый diff читаемым

Сырой вывод diff -u работает, но длинные строки и глубоко вложенный JSON утомительно читать. delta — это фильтр diff, добавляющий подсветку синтаксиса, номера строк и более ясные цвета фона:

复制diff -u a.sorted.json b.sorted.json | delta

Он начинал жизнь как пейджер Git, поэтому может также перехватить git diff. Для людей, которые читают десять конфигурационных diff'ов в день, такие инструменты повышают скорость чтения, а не алгоритмическую точность. Другой частый выбор — git diff --no-index --word-diff, который сравнивает на уровне слов и хорошо работает для сжатого JSON, хранящегося в очень длинных строках.

Одно предупреждение: украшение не устраняет ложные различия. Если порядок ключей не нормализован, delta просто делает шум красивее. Правильный порядок всегда такой: сначала нормализация, потом украшение.

3. Структурный diff: jsondiffpatch понимает семантику

Когда вопрос в том, эквивалентны ли семантически два фрагмента данных, используйте структурный diff. Самый частый вариант в экосистеме JavaScript — jsondiffpatch, который возвращает объект delta, описывающий изменения, а не текстовые строки с маркерами + и -:

复制import { create } from 'jsondiffpatch';

const instance = create();
const delta = instance.diff(
  { id: 1, tags: ['a', 'b'], enabled: true },
  { id: 1, tags: ['a', 'c'], enabled: false },
);

console.log(JSON.stringify(delta, null, 2));

Delta различает добавленные ключи, удалённые ключи, заменённые значения и перемещённые элементы массивов. Это значит, что delta можно напрямую обходить в утверждениях: undefined, когда различий нет, или описание путь за путём, когда они есть. В отличие от текстового diff, его не смущают отступы, порядок ключей или запись чисел вроде 1e3 против 1000.

Не менее важно, что вывод структурного diff может питать рабочий процесс патчей. jsondiffpatch предоставляет patch и reverse, поэтому delta можно применить к исходному объекту и позже отменить. Одна оговорка: автоматически сгенерированная delta не совпадает по формату с рукописным JSON Patch, и на преобразование между ними требуется работа. О более широком подходе к сравнению читайте в статье JSON diff и сравнение.

4. Как устранить ложные различия из-за порядка ключей

Порядок ключей не просто раздражает; он может приводить к неверным выводам. При расследовании следуйте трём шагам:

1. До сравнения рекурсивно нормализуйте порядок ключей через jq -S или аналогичный инструмент.
2. Удалите поля, которые меняются при каждом запуске, например timestamp, requestId и traceId.
3. Убедитесь, что нет повторяющихся ключей. Повторяющиеся ключи при разборе разрешаются по принципу «побеждает последний», поэтому текстовый diff их видит, а структурный — нет.

复制jq -S 'del(.meta.timestamp, .meta.requestId)' a.json > /tmp/a.json
jq -S 'del(.meta.timestamp, .meta.requestId)' b.json > /tmp/b.json
diff -u /tmp/a.json /tmp/b.json

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

5. Массивы: выравнивать по индексу или по id?

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

jsondiffpatch использует objectHash, чтобы объявить первичный ключ, индексируя элементы массива перед сравнением:

复制const instance = create({
  objectHash: (item: { id?: string; sku?: string }) => item.id ?? item.sku,
});

С обычным jq можно сначала отсортировать, а затем использовать текстовый diff:

复制jq -S 'sort_by(.id)' items.json > items.sorted.json

Компромисс выравнивания по id в том, что позиционные изменения больше не считаются различиями. Если бизнесу нужно знать, что запись переместилась с позиции 2 на позицию 5, сравнивайте ещё и явное поле порядка; не полагайтесь только на содержимое множества.

6. Визуальный diff: слой, созданный для людей

Вывод структурного diff предназначен для машин, а не для совещаний. Когда нужно объяснить изменение другому человеку, визуализация эффективнее:

• Редактор diff в VS Code хорош для пофайлового ревью с панелями бок о бок и встроенными подсветками.
• Древовидные просмотрщики вроде JSON Crack и JSON Hero показывают, к какому уровню относится изменение.
• jsondiffpatch включает HTML-форматтер, который отрисовывает delta как сворачиваемый богатый вид.

Ценность визуализации — контекст. Текстовый diff говорит, что изменилась строка 88; древовидный вид говорит, что строка 88 относится к data.items[3].price. Но визуализация обычно загружает весь документ в браузер или десктопное приложение. Прежде чем открывать продакшен-нагрузку, подтвердите, вычисляет ли инструмент локально или отправляет на сервер.

7. Три практики для внедрения diff в CI

Во-первых, нормализуйте до сравнения. Закрепите отступы, рекурсивно сортируйте ключи и фильтруйте изменчивые поля до запуска diff. Иначе CI будет раз за разом падать на шуме.

Во-вторых, выбирайте выравнивание по семантике. Если массив — множество, выравнивайте по первичному ключу. Если это последовательность, сохраняйте выравнивание по индексу. Не применяйте одно правило ко всем API.

В-третьих, утверждайте значения, а не текст. Сравнение разобранных объектов в тестах гораздо стабильнее, чем сравнение вывода JSON.stringify. Когда проверка падает, печатайте путь различия и значения до/после, а не вываливайте всю нагрузку в лог.

复制# Print only the differing paths and values, not the entire document
jq -S 'del(.timestamp)' actual.json > /tmp/actual.json
jq -S 'del(.timestamp)' expected.json > /tmp/expected.json
diff -u /tmp/expected.json /tmp/actual.json | head -n 80

Если различие нужно отслеживать долго, коммитьте скрипт нормализации и ожидаемый файл вместе. Если это разовое расследование, удалите временный скрипт после использования, чтобы он не стал тихо второй реализацией бизнес-логики.

8. Таблица выбора инструмента

Единого лучшего инструмента JSON diff нет; есть правильный инструмент для текущего слоя. Текстовый diff обнаруживает изменение, структурный diff судит об эквивалентности, визуализация объясняет изменение. Разделение трёх слоёв гораздо надёжнее, чем поиск одного инструмента, который делает всё. О разрешении конфликтов между ветками читайте далее в статье JSON и слияние в Git.

Вопросы и ответы

jq -S тоже меняет порядок массивов?

Нет. -S сортирует только ключи объектов и оставляет массивы в исходном порядке. Массивы в JSON упорядочены, поэтому инструмент не превратит [1,2] в [2,1]. Если массив по смыслу является неупорядоченным множеством, отсортируйте его явно через sort_by.

1 и 1.0 — одно и то же значение в структурном diff?

Большинство парсеров превращают оба в одно число, поэтому структурный diff обычно считает их равными, тогда как текстовый diff помечает их как разные. Используйте структурный diff, чтобы решить эквивалентность, а текстовый — чтобы решить, идентичны ли файлы побайтово.

Можно ли использовать вывод diff напрямую как JSON Patch?

Не напрямую. Инструмент diff сообщает, что различается, а JSON Patch описывает упорядоченный список операций; форматы и семантика различаются. Автоматически сгенерированные патчи также обычно ссылаются на индексы массивов, которые устаревают при параллельных изменениях. Добавьте операцию test перед применением.

Как сравнивать JSON-файлы размером в десятки мегабайт?

Сначала извлеките интересующее поддерево, например через jq '.data.items', затем сортируйте по первичному ключу и сравнивайте. Не загружайте всё дерево в память для рекурсивного diff. Очень большие файлы лучше обрабатывать потоково или по частям, а стоимость памяти требует отдельной оценки.

Могут ли онлайн-инструменты diff утечь мои данные?

Зависит от реализации. Чисто фронтенд-инструменты вычисляют в браузере и не отправляют данные; серверные инструменты отправляют содержимое на бэкенд, где оно может попасть в логи. Прежде чем сравнивать продакшен-конфигурацию или клиентские нагрузки, подтвердите, что страница вычисляет локально, и при необходимости проверьте один раз с отключённой сетью.

Как решить между текстовым и структурным diff?

Для быстрого взгляда, где различаются два файла, сортируйте ключи через jq -S и запустите diff -u. Чтобы решить, эквивалентны ли два документа семантически, используйте структурный diff вроде jsondiffpatch и выравнивайте массивы по первичному ключу. Текстовый diff не имеет зависимостей и интегрируется с Git, а структурный не смущается отступами, порядком ключей и записью чисел.

Почему CI не должен считать любой ненулевой код выхода diff различием?

diff завершается с кодом 1, когда находит различия, но отсутствующий файл или ошибка прав доступа тоже возвращают ненулевой код. Если считать любой ненулевой код «содержимое изменилось», опечатка в пути будет отчитана как изменение данных. Более безопасный шаблон сначала проверяет файлы, а затем обрабатывает различие отдельно.

Стоит ли делать diff файлов в десятки мегабайт в браузере?

Нет. Сначала извлеките интересующее поддерево через jq, затем сортируйте по первичному ключу и сравнивайте. Загрузка всего дерева в память для рекурсивного diff стоит гораздо больше памяти и времени. Очень большие файлы лучше обрабатывать потоково или по частям.