Проверка изменений API с JSON Diff

После обновления API с версии 1 до версии 2: какие поля появились в ответе JSON? Есть ли какие-то критические изменения? Благодаря 500 строкам ответа и построчному сравнению легко пропустить изменения глубоко внутри вложенных объектов.

В этой статье, предназначенной для инженеров внешнего и внутреннего интерфейса, а также инженеров по тестированию, объясняются принципы JSON Diff, варианты использования, пятиэтапный рабочий процесс и подводные камни, такие как порядок массивов и точность с плавающей запятой. Затем вы можете использовать функцию сравнения JSON Toolbox для выполнения полного аудита изменений API локально в браузере — без загрузки.

Почему JSON Diff обязателен после обновлений API

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

Из повседневной жизни: API списка пользователей v2 изменил pagination.total с числа на строку — старые мобильные клиенты вылетали с белым экраном. Если бы вы сравнили примеры ответов v1/v2 с JSON Diff перед выпуском, изменение типа было бы отмечено за секунды.

Что такое разница JSON

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

Основное отличие от текстового различия

Читать результаты различий

• Зеленый / добавлено: поле только в правом JSON.
• Красный/удалено: поле только в левом JSON.
• Желтый/изменено: тот же путь, другое значение.
• Без акцента: структура идентична

Для кого подходит JSON Diff

Типичные случаи использования

• Регрессия версии API: структура ответа v1 и v2
• Аудит конфигурации: JSON до и после развертывания
• ETL/миграция: выходные данные сценария и ожидания
• Обзор кода: быстрый просмотр больших фикстур JSON

Практика: 5 шагов к проверке изменений API

Рабочий процесс с инструментом JSON Toolbox Diff — локально в браузере, также для внутренних примеров (токен, предварительное удаление паролей).

1. Сохраните старый ответ: пример из версии 1 или документации как baseline.json.
2. Получите новый ответ: API v2 или обновленные фиктивные данные
3. Необязательное форматирование: аккуратно отформатируйте обе стороны, избегая пробелов.
4. Выполнить разницу: вставьте оба JSON слева/справа, «Начать сравнение».
5. Различия в документах: проверьте отмеченные пункты в CHANGELOG или тестах.

Пример: два ответа User API

JSON A (v1, старая версия):

{
  "name": "Alice",
  "age": 30,
  "tags": ["dev", "json"],
  "profile": {
    "city": "Shanghai",
    "level": "senior"
  }
}

JSON B (v2, новый):

{
  "name": "Alice",
  "age": 31,
  "tags": ["dev", "tools"],
  "active": true,
  "profile": {
    "city": "Beijing",
    "level": "senior"
  }
}

Разница отметок: возраст 30 → 31; изменено содержимое тегов; профиль.город Шанхай → Пекин; активный новый. Если это отсутствует в примечаниях к выпуску, существует риск проблем совместимости клиентов.

Советы и типичные подводные камни

Сначала форматируй, потом сравнивай

Одна страница уменьшена, другая многострочная — разница в тексте создает шум. Отформатируйте оба, а затем учитывайте только семантические изменения.

Порядок массива ≠ изменение содержимого

Тот же контент, другой порядок — JSON Diff может отображать множество изменений. Уточним дело: массив упорядочен (временная шкала) или просто набор?

Плавающая точка и типы

• 1,0 против 1000 можно считать изменением — при необходимости нормализуйте
• Строка «123»; против номера 123 – разные типы, часто ломающие изменения
• пустое поле или отсутствующее поле — разная семантика, diff разделяет оба

Удалить конфиденциальные данные

Перед сравнением замените access_token, пароль, идентификаторы заполнителями (например, «***»). JSON Toolbox работает исключительно через интерфейс — удаление остается хорошей практикой.

JSON Diff по сравнению с другими методами

Лучшая практика: в Dev JSON Diff для быстрых обзоров → важные различия в автоматических тестах → перед основными выпусками схема JSON для структуры. Дополняют друг друга, а не заменяют друг друга.

Часто задаваемые вопросы (FAQ)

Выводы и дальнейшие шаги

После обновления API, миграции конфигурации или синхронизации данных JSON Diff является одним из наиболее эффективных средств против «тихих» критических изменений. Ключевые моменты: формат → проверка цветной маркировки → запись в журнал изменений или тесты.

Интерфейс/тестирование: сохранение базового уровня во время отладки сразу после обновления Diff. Серверная часть: в шаблонах PR требуется скриншот различий v1/v2 в качестве ворот выпуска.