Aleksandr Meshchriakov
25176f31b4
6.9 KiB
ADR-013: Parser Stability and Source Change Detection for External Sources
Status
Accepted
Context
Система зависит от внешних источников данных, которые находятся вне зоны контроля команды:
- государственные порталы
- HTML-страницы
- JS-heavy интерфейсы
- файловые выгрузки
- SOAP/API интеграции
- Excel/XML источники
Эти источники подвержены изменениям:
- меняется DOM-структура
- меняются URL и маршруты
- меняются названия полей
- меняется формат выгрузки
- появляются новые обязательные поля
- меняются ограничения доступа
- изменяется поведение клиентского JavaScript
Для системы такого типа изменение внешнего источника является не исключением, а ожидаемым операционным событием.
Decision
Проект принимает стратегию parser instability as expected.
Это означает:
- каждый внешний источник считается потенциально нестабильным
- отказ парсера по причине изменения источника рассматривается как ожидаемый класс инцидента
- архитектура должна облегчать локализацию, диагностику и восстановление интеграции
Архитектурные правила
- Каждый источник должен быть изолирован в собственном parser/client/service слое.
- Логика получения данных из источника не должна быть размазана по нескольким доменам без явной границы.
- Изменение одного источника не должно ломать остальные интеграции.
- Парсер должен быть максимально отделён от логики сохранения данных.
- Нормализация и запись в БД не должны зависеть от деталей DOM/HTML/XML конкретного источника.
Change detection policy
Система должна позволять определить, что проблема вызвана именно изменением внешнего источника, а не внутренней ошибкой приложения.
Минимально необходимы:
- явное логирование этапа сбоя
- логирование URL, периода, типа выгрузки или источника
- различение сетевых ошибок, ошибок структуры ответа и ошибок сохранения
- сохранение диагностического контекста для повторного анализа
Playwright policy
Playwright допускается для источников, где:
- критическая логика формируется на клиенте
- прямой HTTP scraping недостаточен
- требуется JS rendering или пользовательская навигация
При этом Playwright считается более хрупкой интеграционной точкой по сравнению с HTTP/API клиентами.
Для Playwright-based интеграций принимаются дополнительные ограничения:
- сценарий навигации должен быть максимально коротким
- DOM-селекторы должны быть минимально хрупкими
- логика парсинга должна быть отделена от логики браузерной навигации
- fallback или быстрая диагностика деградации обязательны
Resilience policy
При изменении внешнего источника система должна:
- завершать конкретную задачу контролируемой ошибкой
- не повреждать уже сохранённые данные
- не маскировать сбой как успешную синхронизацию
- сохранять возможность повторного запуска после исправления
Ownership policy
Каждая интеграция с внешним источником должна иметь:
- понятную точку входа
- понятный набор задач
- понятный формат выходных данных
- наблюдаемый статус выполнения
Consequences
Positive
- уменьшается связность между интеграциями
- упрощается ремонт конкретного источника
- проще локализовать причину отказа
- снижается риск каскадного повреждения всей системы
- повышается операционная предсказуемость
Negative
- возрастает количество прикладного кода и адаптеров
- приходится поддерживать отдельные контракты на источник
- растут требования к логированию и smoke-проверкам
- интеграции невозможно считать "написал один раз и забыл"
Alternatives considered
1. Общий универсальный парсер для разных источников
Отклонено, так как источники сильно отличаются по протоколу, структуре и стабильности.
2. Встраивание логики источников прямо в задачи или view-слой
Отклонено, так как это увеличивает связность и ухудшает сопровождаемость.
3. Опора только на "ручное замечание", что парсер сломался
Отклонено, так как это не соответствует требованиям эксплуатационной зрелости.
Notes
Следующим развитием данного решения должны быть:
- smoke checks для критичных источников
- классификация типов ошибок интеграции
- runbook для восстановления парсеров после изменения внешних порталов