Вступление
Рано или поздно сложную систему приходится объяснять человеку со стороны: новому разработчику, техлиду, архитектору или ревьюеру.
И тут часто начинается боль: репозитории уже показали, основные сущности вроде бы объяснили, но всё ещё непонятно, как данные проходят через систему.
В этой части я покажу, как сделать первое погружение в код наменее болезненным: выбрать один главный flow, проследить конкретную сущность и собрать артефакты, которые помогут не скакать по проекту хаотично.
Очевидно, потоков данных в любом приложении полно. Важно уметь выбрать главный или главные. Тут я покажу как определить, какой поток именно в вашем случае является главным, а также как эффективно описать этот поток, чтобы новенькому было понятно.
По ходу статьи получится маленький toolkit: 1. как выбрать главный flow; 2. как заполнить карточку сущности; 3. как составить таблицу изменения формы данных; 4. как проверить точки поломки.
Выбираем главное
Как бы ни хотелось обрисовать все, ведь в системе точно много важного, придется выбирать, на чем вы остановитесь. Напомню, если у вас будет в онбординге 100 схем и таблиц, их просто не прочитают вообще. Нужен баланс. Хорошая карта системы — это не архив всего подряд, а набор артефактов, по которым команда, новый разработчик, техлид или внешний ревьюер быстро понимает, где в системе создаётся ценность и где лежат риски.
В рамках данного проекта Theme Parks достаточно 1 флоу, это относительно небольшой проект. В больших системах будет больше важных процессов. Но и там можно сделать флоу для конкретных ролей, например для инженера в команде логинки очевидно надо выделять этот флоу именно в логинке, а не в оплате, например.
Возможно, вы уже знаете, какой флоу системы надо описать. А если нет (и если да), то вот мой чеклист, как понять что вы выбрали правильно:
[ ] связан с главной пользовательской ценностью;
[ ] проходит через 3+ ключевые части системы;
[ ] заканчивается на публичной границе: API / UI / SDK / export;
[ ] часто ломается или вызывает вопросы;
[ ] показывает, где данные рождаются, меняют форму и становятся контрактом;
[ ] затрагивает важный кусок кода
[ ] помогает понять, что является главным маршрутом, а что обвязка вокруг него
Для ThemeParks API было несколько претендентов - парк, аттракцион, лайф статусы и время ожидания. Разумеется еще с первого взгляда на продукт больше всего хотелось понять как работает live status. По ходу анализа это желание только укоренилось.
Карточка сущности
На этом этапе мы соберем такую “анкету друга” про выбранную сущность. Это опять же промежуточный артефакт для построение data flow.
Попробуем заполнить на примере ThemeParks:
Поле | Описание | Пример |
Entity | Что отслеживаем? | Attraction live status / standby wait time |
Business meaning | Зачем нужно бизнесу? | Пользователь / внешний разработчик хочет понять, открыт ли аттракцион и сколько сейчас ждать в обычной очереди |
Representative fields | Важные показательные поля | id, name, entityType, parkId, destinationId, status, queue.STANDBY.waitTime |
Source | Где значение появляется впервые? | В source-specific данных конкретного парка / destination implementation. В parksapi базовый класс ожидает, что конкретный парк реализует buildLiveData() и вернёт LiveData[]. |
Normalization | Где source-specific данные приводятся к общей модели? | В implementation конкретного destination + общих helper-слоях parksapi: buildLiveData() собирает данные в общий LiveData[]; createStatusMap() маппит source-specific строки статусов в общий набор OPERATING / CLOSED / DOWN / REFURBISHMENT; базовый getLiveData() дополнительно чистит некорректные waitTime, превращая нечисловые/не-finite значения в null. |
Contract | Где закреплены форма и смысл значения? | В @themeparks/typelib: LiveData содержит id, status, queue, operatingHours, showtimes, diningAvailability; LiveQueue описывает варианты очередей, включая STANDBY.waitTime; LiveStatusTypeEnum ограничивает статусы значениями OPERATING, DOWN, CLOSED, REFURBISHMENT; QueueTypeEnum задаёт типы очередей вроде STANDBY, SINGLE_RIDER, RETURN_TIME, PAID_RETURN_TIME, BOARDING_GROUP. |
Public boundary | Где значение становится доступным внешнему потребителю? | ThemeParks.wiki API. В JS SDK live-данные читаются через tp.entity(id).live() или raw-метод tp.raw.getEntityLive(id). |
Consumer | Кто использует значение дальше? | JavaScript / TypeScript SDK, Python SDK, внешние приложения и интеграции. В JS SDK пример проходит по live.liveData, читает entry.queue.STANDBY?.waitTime и использует helper currentWaitTime(entry). |
Update behavior | Как значение обновляется или устаревает? | Есть два режима: обычный getLiveData() возвращает snapshot live data, а streamLiveData() поддерживает real-time stream для парков с live feed. На стороне JS SDK есть in-memory cache для GET-запросов; при дебаге его можно отключать через cache: false. |
Responsible layer | Какой слой отвечает за корректность значения? | Source adapter / destination implementation отвечает за получение и первичную сборку; normalization layer отвечает за маппинг статусов и чистку значений; typelib отвечает за контракт; API layer отдаёт публичный response; SDK layer делает значение удобным для потребителя. |
Failure points | Где значение может исказиться, устареть или потеряться? | Полагаю, но это не точно: |
Прослеживаем как данные меняют форму
Теперь на основе карточки сущности уже не так сложно составить собственно data flow.
Мы не просто так отвечали на вопросы выше, это такие дефолтные слои, по которым мы будем продвигаться. И тут мы можем уже упасть на уровень ниже, ведь в общих чертах мы уже рассмотрели флоу.
Stage | Где смотреть в ThemeParks | Что происходит с формой данных |
Source | parksapi → конкретные destination adapters: src/parks/<park>/<park>.ts или похожие файлы конкретного парка | Данные приходят в source-specific формате конкретного парка или провайдера. На этом этапе status / waitTime ещё не обязательно похожи на общий контракт ThemeParks. |
Collection | parksapi → src/destination.ts → Destination.getLiveData() вызывает buildLiveData(); конкретный destination должен реализовать buildLiveData() | Source-specific данные превращаются в массив LiveData[]. getLiveData() — общий final method, а buildLiveData() — точка, где конкретный парк отдаёт live data системе. |
Normalization | parksapi → конкретный destination adapter + helper logic в src/destination.ts | Значения приводятся к общей модели: live-запись получает id, status, queue; для обычной очереди появляется форма queue.STANDBY.waitTime. Базовый getLiveData() дополнительно чистит waitTime: если значение не finite number, оно становится null. |
Contract | typelib / generated TypeDoc → LiveData, LiveQueue, LiveStatusTypeEnum, QueueTypeEnum | Здесь закрепляется форма и смысл значения. LiveData содержит id, status, queue; LiveQueue.STANDBY.waitTime описывает текущее ожидание в минутах; LiveStatusTypeEnum ограничивает статус набором OPERATING, DOWN, CLOSED, REFURBISHMENT. |
Public boundary | ThemeParks.wiki API → public API response для live data | Внутренняя модель становится публичным ответом API. С этого момента поле уже нельзя трактовать как локальную деталь реализации: внешний потребитель ожидает стабильную форму данных. |
SDK layer | ThemeParks_JavaScript → README examples / SDK methods: tp.entity(id).live(), currentWaitTime(entry), entry.queue.STANDBY?.waitTime | API response превращается в developer-facing usage: внешний разработчик получает live.liveData, может брать wait time через helper currentWaitTime(entry) или напрямую читать entry.queue.STANDBY?.waitTime. |
Consumer | Внешнее приложение / интеграция, использующая API или SDK | Техническое значение становится пользовательским результатом: “аттракцион работает / закрыт / временно недоступен” и “ждать примерно N минут”. |
Это и есть первое безболезненное погружение в код. Мы получили простой флоу:
source-specific status / wait time → LiveData[] → queue.STANDBY.waitTime: number | null → public API response → SDK helper / SDK model → consumer-facing value
Мне нравится этот артефакт ещё и потому, что он полезен не только для новичков. Такая таблица помогает быстро объяснить систему человеку снаружи: архитектору, аудитору, техническому консультанту или инвестору на technical due diligence. Не на уровне “у нас там микросервисы и API”, а на уровне конкретного маршрута: где данные появляются, где меняют форму, где становятся контрактом и где могут сломаться.
Очень полезно наложить этот флоу на карту репозиториев, если есть капасити.
Тут я дам свой лайфхак из области мнемотехники. Наш мозг хорошо цепляется за образы. Запомнить схему будет куда проще, если соотнести ее с какой-то картинкой. Например я тут вижу кальмара с полипом на щеке.
Он потребляет данные (наверное через рот), и поскольку они все разные, ему приходится пропускать их через фильтр typelib в виде полипа, чтобы их переварить. В туловище оно переваривается и отдается через 2 его щупальцы - ThemeParks_JavaScript и ThemeParks_Python.
Этот метод для меня — настоящее сокровище: его можно использовать почти везде, где надо запомнить сложную схему / иностранные слова / факты, что угодно.
Но вернемся к нашей теме.
Чек-лист точек поломки flow
Раз уж мы прошли по всему flow, грех не пометить, где он может поломаться. После карточки сущности и таблицы изменения формы данных это уже не составляет особого труда: мы не придумываем failure points с нуля, а просто идём по тем же data layers.
На реальном проекте такой чек-лист может составить любой разработчик, который уже хорошо знает систему. Более того, он ещё и подскажет, какой слой ломается чаще обычного. И это, кстати, может быть сигналом, что там уже пора рефакторить.
Вот мой довольно универсальный чек-лист:
[ ] источник отдал корректное значение;
[ ] данные не потерялись при сборе;
[ ] нормализация не изменила смысл;
[ ] типы / схемы покрывают этот случай;
[ ] API отдаёт ожидаемый контракт;
[ ] SDK не переименовал / не преобразовал поле;
[ ] consumer правильно интерпретирует значение;
[ ] cache / TTL / update frequency не создают устаревшее значение;
[ ] fallback logic не скрывает ошибку;
[ ] monitoring/logs позволяют увидеть, на каком этапе значение изменилось.
Для меня главная ценность этого чек-листа — в детерминированности шага.
Мы не просто говорим новичку: “иди разберись, почему waitTime неправильный”. Мы заранее привязываем каждый шаг проверки к data layer: source, collection, normalization, contract, API, SDK, consumer.
В итоге дебаг перестаёт быть хаотичным прыжком по коду. У вас появляется трасса значения. Можно идти с конца — от того, что увидел пользователь, назад к источнику. Можно идти с начала — от source data к consumer layer. Это уже дело вкуса и ситуации.
Главное, что размер шага задан заранее: один слой данных — одна проверка.
Делитесь в комментариях, как вы выбираете размер шага при дебаге: идёте от пользователя назад, от источника вперёд или комбинируете оба подхода?
Итоги дня
Сегодня мы получили 4 практичных артефакта:
чек-лист выбора главного flow;
карточку отслеживаемой сущности;
таблицу изменения формы данных;
чек-лист точек поломки flow.
На реальном проекте я бы выбрала 3–4 важных flow и описала их в таком виде. Но даже один хорошо разобранный flow уже даёт ясность: новичок видит не просто набор репозиториев, а первый надёжный маршрут через систему.
Он понимает, где данные появляются, где меняют форму, где становятся контрактом и где могут сломаться. А ещё такой flow становится маленьким evidence-артефактом: его можно показать не только новичку, но и внешнему человеку, которому нужно быстро оценить устройство и риски системы.
Это был экватор нашего onboarding-приключения. Дальше — runtime и deployment.
Спасибо за прочтение!