В жизни каждого системного аналитика наступает момент, когда он открывает две вкладки: слева – Swagger с контрактом системы А, справа – Confluence с контрактом системы Б. Между ними – пустая Excel-таблица, либо ещё одна вкладка Confluence. Задача – простая, как мир: смаппить поля.
И начинается знакомый ритуал: скопировать атрибут из одного места, вставить в другое. Ctrl+C → Ctrl+V, снова и снова. Одно неверное движение или опечатка — и через пару дней от разработчика прилетит таск с комментарием «маппинг не работает, проверь пути».
Меня зовут Владислав, и этот ритуал был частью моей ежедневной работы системным аналитиком в телеком-компании. Мой проект — это оркестратор сложных бизнес-процессов по работе с документами, который постоянно интегрируется по REST API с финансовыми системами, службами безопасности и другими сервисами. А где REST, там, как правило, и JSON.
Сразу оговорюсь, что я не профессиональный разработчик. Скорее, занимаюсь тем, что можно назвать "vibe-коддингом" — пишу код, чтобы решить конкретную прикладную задачу, не претендуя на идеальную архитектуру. И однажды, после очередного марафона по маппингу, я решил, что пора автоматизировать эту боль.
Так родилась идея десктопного приложения. Я выбрал Python и PyQt5, потому что это позволяло быстро накидать графический интерфейс. После нескольких недель вечерами и на выходных получился инструмент, который покрыл все мои потребности.
О программе
1. Визуальное представление «бок о бок»
Главный экран программы — это то, чего мне так не хватало. Слева — структура-источник, справа — структура-приёмник. Никаких плоских таблиц! Оба JSON-файла отображаются в виде иерархических деревьев, где сразу видна вложенность объектов и массивов. Для наглядности у каждого типа данных своя иконка. Это моментально решает проблему потерянной вложенности из Excel.
2. Маппинг с помощью Drag-and-Drop
Это главная фича, убивающая рутину. Вместо копирования путей, я просто зажимаю поле в одном дереве и перетаскиваю его на нужное поле в другом. Готово! Программа сама создает связь, и в центральной таблице появляется новая строка маппинга. Быстро и без единой опечатки.
3. Таблица маппинга
Все созданные связи отображаются в таблице в центре экрана. Здесь наглядно видно:
Полные пути в источнике и приёмнике.
Типы данных. Программа автоматически подсвечивает красным несовпадающие типы (например, string в integer), помогая ловить ошибки на самой ранней стадии.
Если кликнуть на строку, программа подсветит связанные поля в обоих деревьях и прокрутит к ним. Это невероятно удобно при работе с большими JSON-структурами.
4. Управление метаданными: всё в одном месте
Маппинг — это не только про «путь-в-путь». Поэтому для каждого поля можно задать метаданные:
Тип данных: Можно уточнить, что строка — это date или enum.
Обязательность (Required): Удобный чек-бокс для обязательных полей.
Описание: Место для человекочитаемых комментариев.
Пример/Enum значения: Для перечислений можно задать список возможных значений.
Причем система сохраняет консистентность: если изменить тип поля здесь, он тут же обновится и в главном окне маппинга, и наоборот. Вся информация теперь живёт в одном месте.
5. Не просто маппер, а мини-редактор JSON
Иногда нужно спроектировать новую структуру, а не работать с готовой. Правый клик по узлу в дереве позволяет:
Добавить дочерний элемент.
Переименовать ключ.
Изменить значение или тип.
Удалить узел со всей его вложенностью.
Это превращает программу в удобный инструмент для проектирования JSON-контрактов.
6. Сохранение и экспорт: гибкость для командной работы
Весь проект — обе JSON-структуры, все маппинги и все метаданные — можно сохранить в один файл-проект .json. Это позволяет передать всю работу коллеге или вернуться к ней позже.
Объект mappins – это сам маппинг
Объекты source_json_structure_preview и target_json_structure_preview – можно использовать как примеры json’a
Объекты source_field_metadata и target_field_metadata – описывают метаданные атрибутов (тип, валидация, описание и т.д.)
А для тех, кто не может жить без Excel, я добавил функцию экспорта и импорта в .xlsx. Программа создает файл с тремя листами: Mappings, Source Metadata и Target Metadata. Это идеальный мост между моим удобным инструментом и корпоративными стандартами документации.
Заключение
Инструмент, который родился из моей личной боли, оказался решением широкой проблемы. Он экономит часы работы, снижает количество глупых ошибок и превращает рутинную задачу в почти творческий процесс. Я уверен, он может быть полезен не только мне.
Готов поделиться с коллегами-аналитиками. Для вопросов и предложений можно написать мне в Telegram: @vlad_pere
Спасибо за внимание, и пусть ваши маппинги всегда будут безошибочными!