Ошибка, которая научила меня перестать распространять JSON как текст, стоила мне большей части выходных Платежный веб-крюк на Laravel SaaS, который я запускаю, начал бесшумно выходить из строя после того, как провайдер & quot;non-breaking& quot; Обновление API - их слова, из журнала изменений. Я вытащил полезную нагрузку из наших журналов до обновления, схватил свежий и бросил оба в обычный текстовый diff. Каждая строка загорелась. провайдер переключил свой сериализатор, который переупорядочил каждую клавишу в алфавитном порядке и изменил отступ с четырех пробелов на две. Шестьсот измененных строк, а где-то там - одну реальную разницу. Я прочитал этот размах сверху вниз дважды, прежде чем нашел: amount поменял с номера 1099 в струну "1099", йо- Те же персонажи на экране. Разный тип. Наше строгое сравнение отвергало его, очередь повторила его в землю, а текстовая разница похоронила одно значимое изменение под косметикой 599.
Это 's фундаментальная проблема: JSON - это формат данных, но текстовый разлад рассматривает его как прозу. Порядок ключей, пробелы, отступы, конечные новые строки - ни одна из них ничего не значит для анализатора JSON, и все это проявляется как изменения в сравнении на основе строк. Пер RFC 8259, объект JSON является неупорядоченный Коллекция пар имени/значения. Два документа могут быть разными байтами и семантически идентичными. Инструмент, который сравнивает JSON построчно, отвечает на неправильный вопрос.
равняется json diff tool отвечает правильный. Он анализирует оба документа на деревья и сравнивает ценности: этот ключ был добавлен, этот ключ был удален, это значение изменилось с X на Y, и - тот, который сохранил мои выходные, если бы он существовал тогда на моей вкладке браузера - это значение изменилось тип, йо- Когда я построил проверку diff для Toolz.dev, обнаружение изменений типа было первой особенностью в списке, потому что это класс изменений, что текстовые дифференциы структурно неспособны к наплавке и чаще всего ломают реальные системы.
В этом руководстве рассказывается о том, как работает структурное сравнение, когда порядок массивов должен и должен иметь значение 't, а также о рабочих процессах отладки - регрессии API, дрейф конфигурации, аудит манифеста пакетов - где JSON diff окупается еженедельно.
TL;DR: Вставьте два документа JSON в Toolz.dev JSON Diff Checker и получить структурное сравнение: добавлены, удалены и изменены ключи с точными путями, такими как
features.rateLimitилиusers[3].email- плюс отдельное пометку при изменении значения тип (то3000→"3000"ошибка). Порядок ключевых и форматирование никогда не производят ложных срабатываний. Все работает в вашем браузере, ничего не загружается. Соедините его с Форматтер JSON сначала очистить документы и Инструмент текстового дифференциала Для контента, где строки действительно имеют значение.
Что значит структурно diff json?
Структурный разлом анализирует оба документа в их фактические деревья данных и соединяет их вместе, ключ за ключом, элемент за элементом. В каждом узле он спрашивает: существует ли этот ключ с обеих сторон? Являются ли значения одного типа? равны ли они? выход 't "строка 14 изменена & quot; - it's список фактов о ваших данных:
versionизмененный с"1.4.0"на"1.5.0"features.metricsбыло добавлено с ценностьюtrueportИзменен тип с номера на строкуtags[2]было добавлено с ценностью"monitored"
Каждое различие несет свой полный путь JSON, поэтому в глубоко вложенном документе вы точно знаете, где искать. users[12].address.postalCode Сообщает вам, какой пользователь, в каком поле, прокрутку не требуется.
Контраст с текстовым разницей наиболее ощутим на документах в реальном мире. брать package.json регенерируется другой версией npm, ответом API после обновления серверной командой своего сериализатора или файлом конфигурации, запускаемым через форматировщик.Text diff: сотни изменённых строк. Структурный diff: три изменения, которые действительно произошли, или честный ответ, что их нет - & quot; структурно идентичный& quot; - что само по себе ценно.Подтверждая, что производил рискованный рефактор нуль Изменение данных — это половина причин, по которой я достигаю этого инструмента.
Там's место для линейных различий, чтобы быть ясным. Проза, код, HTML, все, что несет в себе физический макет, - это's текст разница территория. Но макет JSON не имеет смысла по спецификации, и сравнение, которое делает вид, что иначе создает шум, который вам нужно фильтровать глазами.
Почему изменения типов заслуживают своей категории?
Потому что они невидимы при любом другом взгляде на данные, и они ломают вещи способами, которые можно отладить.
1099 а "1099" рендеринг идентично в файле журнала, терминале и большинстве текстовых различий - кавычки легко пропустить в 2 часа ночи. Но для любого типизированного потребителя это разные значения. JavaScript's === Отвергает сравнение. схема JSON, объявляющая "type": "integer" Не проверка. служба Go, не являющаяся маршалами, в int64 возвращает ошибку; строгий десериализатор Джексона в Java бросает. PHP, как известно, прощает с помощью свободного сравнения, но в тот момент, когда вы включаете строгие типы - которые должна делать каждая современная кодовая база Laravel "1099" Перестает быть деньгами и начинает быть исключением.
Самая неприятная часть где эти изменения происходят из. Почти никогда от разработчика намеренно редактировать значение. Они поставляются из смены сериализаторов, обновлений ORM, столбца базы данных, мигрирующих из INT на VARCHAR, кэширующий слой, который строит числа, или полезный шлюз API " Нормализующие полезные нагрузки. Никто не пишет для них запись в журнале изменений, потому что никто не знает, что они произошли.
Итак, json diff чеккер отчеты меняют тип как свою собственную категорию - ! в копируемом отчете, отличном от обычных изменений стоимости - с прописанными старым и новым типами. Когда вы ' смотрите на сводку, в которой говорится 0 added, 0 removed, 0 changed, 1 type changed, вы точно знаете, на какой жук вы охотитесь, прежде чем прочитали один путь.
Как вы сравниваете два файла JSON с инструментом?
Шаг 1: Вставьте оба документа
Оригинальный (или известный) JSON выходит на левую панель, обновляет (или подозреваю) JSON в правом. Конвенция имеет значение только для чтения вывода: «Добавлено» означает, что справа, но не слева, «удалено» означает обратное. Если вы сравниваете рабочую среду с сломанной, поставьте работу слева, а дифференциал читается как «Что сломалось, изменилось».
Там 's кнопка "Загрузить образец", которая заполняет обе панели небольшим сервисом, настраивающим каждый тип разницы - изменение значения, сложение, изменение типа, рост массива - что является самым быстрым способом узнать, как читается вывод.
Шаг 2: Решите, имеет ли значение порядок массива
Это единственный вариант, о котором вам нужно подумать, и правильный ответ зависит от того, какие ваши массивы невзрач- подробнее об этом ниже. По умолчанию порядок зависит от порядка, что соответствует спецификации JSON. Отметьте & quot;Игнорируйте порядок и количество массивов; когда ваши массивы семантически установлены.
Шаг 3: Сравните
Оба документа проверяются перед сравнением. Если у любой из сторон есть синтаксическая ошибка - конечная запятая, отдельные кавычки, некотируемый ключ, обычные подозреваемые - вы получаете синтаксический анализатор's точное сообщение и, что особенно важно какая сторона оно пришло из. Ни молчаливого сбоя, не сравнивая полуразборчивый мусор. Если вы не уверены, что ваш JSON даже действителен, запустите его через Форматтер JSON Во-первых, он проверяет и печатает в один шаг.
Шаг 4: Прочитайте резюме, затем таблицу
Сводная строка дает вам подсчеты по категориям - добавлено, удалено, изменено, тип изменен - что часто все, что вам нужно. "47 добавлено, 0 удалено, 0 изменено иquot; после того, как удар по версии API означает только новые поля: безопасно. "0 добавлено, 3 удалено " означает поля, от которых ваши потребители могут зависеть только что исчезнувшие: небезопасно. В таблице ниже перечислены все различия с его путем, старым значением и новым значением, усеченным для читаемости по длинным значениям.
Шаг 5: Скопируйте отчет
Кнопка «Копировать отчет» создает сводку с абстрактным текстом с + / - / ~ / ! маркеры и полные пути - предназначены для вставки непосредственно в комментарий запроса на извлечение, поток инцидента Slack или билет. "Here's именно то, что изменилось между постановкой и производственной конфигурацией и квотой; с квитанциями, в один клик.
Когда следует игнорировать порядок массива?
Массивы JSON упорядочены по спецификации - [1, 2] а [2, 1] являются разными документами, и сравнение по умолчанию соответствует этому. Но спецификация описывает контейнер, а не ваш намерение, и на практике массивы используются двумя разными способами:
Массивы как последовательности, где позиция означает: цепочки промежуточного программного обеспечения, которые выполняются по порядку, списки миграции, отсортированные таблицы лидеров, результаты с разбивкой по страницам. Изменение порядка - это настоящее изменение - стека промежуточного программного обеспечения, который работает auth после handle это другое (и, вероятно, сломанное) приложение. Сохраняйте чувствительность к заказу.
Массивы в качестве множеств, где позиция - авария: списки тегов, назначение ролей, флаги признаков, идентификаторы, возвращаемые запросом базы данных без ORDER BY. Postgres полностью в своих правах возвращать одни и те же строки в другом порядке на разных прогонах, и если из-за этого загорается ваш дифф, то 's нойз. это то, что порядок & quot;Ignore array & quot; опция для - элементы совпадают независимо от позиции, так что ["admin", "editor"] равный ["editor", "admin"], йо-
Мое правило, издаваемые по сравнению с полезными нагрузками API: если бэкенд применяет явную сортировку, то рассматривайте массив как последовательность; если он не 39; это набор, поняли ли авторы это или нет, а сравнение по порядку говорит вам правду о данных.
Структурный дифференциал и текст diff и ручное осмотр
| Структурный json diff | Текст/линия diff | пристально глядя на это | |
|---|---|---|---|
| Переупорядоченные ключи | Разницы не сообщалось | Каждая движущаяся линия отмечена | Легко пропустить изменения |
| Переформатированное пробел | Разницы не сообщалось | Все отмечено | недействительный |
изменить тип (1 → "1")) |
Помечено как изменение типа | Два персонажа в море линий | почти невидимый |
| Вложенное местоположение изменения | Точный путь: a.b[2].c |
Номер строки в форматированный писать | ручной обход |
| Переупорядочение массива (преднамеренное) | помечен (или проигнорирован, ваш выбор) | флагманский | Зависит от размера массива |
| лучше для | JSON, полезные нагрузки API, конфиги | Код, проза, разметка | Двухстрочные документы |
| Режим сбоя | Нет на действующем JSON | Ложные положительные результаты хоронят реальные изменения | усталость человека |
Честное резюме: text diffs aren't irf, they're re revanting another quest - & quot;did the bytes mange?& quot; For JSON вы почти всегда хотели & quot;did the данные Изменившись?, и эти вопросы на удивление часто имеют разные ответы.
Каковы реальные рабочие процессы для JSON diff?
Отладка регрессий API
Рабочий процесс из моей истории вебхука, теперь систематизированный: захватить полезную нагрузку от до изменения (журналы, записанное приспособление, ваш тестовый набор's снимок) и один от после. Левая панель, правая панель, Сравнить. Диф говорит вам за секунды, что провайдер's changelog did't - какие поля перемещались, которые меняли тип, которые тихо исчезали. я делаю это каждый раз, когда сторонний API объявляет об ударе по версии, перед Старая версия загорается и подает отчет в тикет обновления.
ловлю конфиг
Постановка работ, производство does't, и оба были "развернуты из одного и того же config." были ли они? Экспорт обоих - среда JSON, a docker inspect Выход, kubernetes configmap, сброшенный с -o json- и различать их. Config drift почти всегда представляет собой одну или две клавиши, и столбец пути приведет вас прямо туда. Это бьется diff <(jq -S . a.json) <(jq -S . b.json) в терминале, потому что он также ловит изменения типа, которые jq- Нормализованные текстовые различия почти незаметно отображаются.
Просмотр изменений файла блокировки и манифеста
равняется package.json или composer.json это искажается конфликтующими слияниями или сгенерированной спецификацией OpenAPI после обновления платформы: структурный разряд показывает изменения зависимости без шума регенерированного форматирования. Для работы плагина WordPress - WP Adminify отправляет настройки как JSON - я различаю схему экспортированных настроек между выпусками, чтобы убедиться, что рефактор не удалил 't уронил ключ, от которого зависят тысячи установок. Случайное удаление отображается как случайное удаление - строка; в текстовом разном виде экспорта 4000-строчных настроек он отображается вообще ничем.
Проверка миграции данных
Перед: Экспорт репрезентативной записи как JSON. После миграции: снова экспортируйте его. Разница должна показывать точно, какие изменения в планах миграции и ничего другого, йо- «Структурно идентичен» на записи, которая не должна была быть тронута, — это самый дешевый регрессионный тест, который вы когда-либо запускаете. Это хорошо сочетается с преобразованием табличных экспортов через CSV в JSON Когда данные выходят из базы данных как CSV.
Сравнение реакций окружающей среды
Попадайте в одну конечную точку в двух средах, дифференциайте ответы. Поля, присутствующие в Dev, но отсутствующие в производстве, обычно означают флаг объекта, устаревший развертывание или переменную среды, которая так и не была установлена. Сводка только подсчитывает часто диагностику.
Почему для этого инструмента обработка на стороне клиента имеет большее значение, чем большинство?
Подумайте о том, что вы вставляете в JSON diff: ответы API с электронными письмами клиентов, файлы конфигурации с внутренними именами хостов, полезные данные веб-крюков с метаданными платежей, экспорт базы данных. Это именно те данные, которые не должны утекать, вставленные именно в тот момент - в середине инцидента - когда никто не проверяет, какой онлайн-инструмент только что получил их.
выше Toolz.dev diff checker анализирует и сравнивает полностью в вашем браузере. ни один запрос не несет ваши документы где угодно; инструмент работает в автономном режиме после загрузки страницы, что вы можете проверить, разрезая сеть и снова сравнивая.Это 't премиум-функция или обещание политики, которое может измениться - it's архитектура. логика сравнения - это чистый JavaScript, работающий на двух проанализированных деревьях в памяти. нет серверного компонента, чтобы отправить данные в.
Один и тот же аргумент конфиденциальности применим ко всему набору инструментов - it's причина Набор инструментов разработчика на Toolz.dev построен браузером прежде всего, но инструменты различий - это то, где он и #39;s наиболее острый, потому что сравнение двоих Производственные документы удваивают экспозицию приклеивания.
Насколько большой документ вы можете сравнить?
Сравнение посещает каждый узел в обоих деревьях один раз, поэтому работа линейно масштабируется с размером документа. На практике: документы в сотни килобайт сравниваются мгновенно, мегабайты однозначные, полные в течение секунды, на что напоминают современный ноутбук; будут работать десятки мегабайт, но вы это почувствуете, так как браузер должен одновременно анализировать оба документа и держать оба дерева в памяти.
Два практических совета для очень больших полезных нагрузок Во-первых, если вас волнует только часть документа, сравните только это поддерево - вставить response.data.items с обеих сторон, а не полного конверта. Во-вторых, если дифференциация производит тысячи записей, это обычно знак, что одна сторона отличается фасон (массив, завернутый в объект, дополнительный уровень вложенности) - проверьте первые несколько путей перед прокруткой; они' расскажут вам, смотрите ли вы' смотрите на одно структурное изменение каскадно или на тысячи подлинных.
часто задаваемые вопросы
Как сравнить два файла JSON онлайн?
откройте json diff чеккер, вставить один документ в левую панель, а другой в правую, и нажмите Сравнить. вы получаете категоризированный список каждого добавленного, удаленного, измененного и измененного типа значения с его точным JSON путь. оба документа обрабатываются полностью в вашем браузере - ничего не загружается на любой сервер.
Почему текстовый diff показывает так много изменений, когда мои данные JSON одинаковы?
Поскольку текстовые дифференциалы сравнивают строки, а JSON позволяет записывать одни и те же данные разными способами. Переупорядоченные клавиши, разные отступы и пробелы изменяют текст без изменения данных. Структурный дифференциал сначала анализирует оба документа и сравнивает фактические значения, поэтому различия в форматировании приводят к нулю сообщаемых изменений.
Имеет ли значение порядок ключей в объекте JSON?
нет RFC 8259 определяет объект JSON как неупорядоченную коллекцию пар имени/значения, поэтому {"a":1,"b":2} а {"b":2,"a":1} являются одним и тем же объектом. средство проверки различий сравнивает объекты по имени ключа и никогда не сообщает о переупорядочении как об изменении. порядок элементов массива, напротив, значим по умолчанию - массивы упорядочены в спецификации.
Когда я должен использовать опцию "Игнорировать порядок массива?
Используйте его, когда ваши массивы семантически наборы, а не последовательности - списки тегов, коллекции ролей, идентификаторы из несортированного запроса базы данных. с опцией на, [1,2,3] а [3,1,2] Сравните как равняться. Оставьте его в том, что положение имеет значение, например, упорядоченные цепочки промежуточного программного обеспечения, ранжированные результаты или списки с разбиением на страницы.
Что такое изменение типа и почему оно помечается отдельно?
Изменение типа - это когда значение 's JSON-тип различается в разных документах, даже если он выглядит похожим - число 3000 стать струной "3000" это классический случай. Он помечен отдельно, потому что он ломает потребители со строгим набором, проверку схемы и строгие проверки равенства, но при этом почти незаметны в текстовых дифференциалах и журналах. Это одна из наиболее распространенных причин интеграции API.
Могу ли я поделиться результатом сравнения с моей командой?
да. Кнопка Копировать отчет генерирует отчет DIFF в виде обычного текста с + (добавлено), - (удалено), ~ (изменено) и ! (Тип изменен) маркеры и полные пути JSON для каждой разницы. Он отформатирован для чистоты вставки в комментарии извлечения запросов, провисание потоков и трекеры проблем.
Безопасно ли вставлять ответы API-интерфейса в инструмент?
Да. Анализ и сравнение полностью выполняются на JavaScript в вашем браузере - с вашими данными не делается сетевой запрос, ничего не регистрируется и не сохраняется, и инструмент продолжает работать в автономном режиме. Это делает его безопасным для полезных данных, содержащих данные клиентов, внутренние имена хостов или учетные данные, хотя и редактирует секреты перед обменом сводка все еще на тебе.
Что произойдет, если один из моих документов не действителен в JSON?
Инструмент проверяет обе стороны перед сравнением и сообщает синтаксический анализатор's точное сообщение об ошибке вместе с тем, с какой стороны оно пришло - слева или справа. Обычными виновниками являются конечные запятые, одиночные кавычки вместо двойных и нецитируемые ключи. Исправьте сообщаемую проблему или проведите документ через Форматтер JSON Чтобы найти проблему, затем сравните еще раз.
Структурное сравнение — один из тех инструментов, которые меняют, какие ошибки можно даже полагаться. Text diffs ответ & quot;изменились ли байты?& quot;; для JSON важен вопрос & quot;изменились ли данные?& quot; - и для полезных данных API, конфигураций и манифестов, которые запускают ваши системы, json diff чеккер отвечает за секунды, в вашем браузере, с ваши данные никогда не покидают вашу машину. больше рабочих процессов JSON - форматирование, проверка, преобразование - живут в Руководство по инструментам кодирования, йо-
