Как разделить фронтенд на модули и связать их между собой: на примере маркетплейса

Привет, меня зовут Иван Некипелов, я технический руководитель команды фронтенд-инфраструктуры в RWB.

Эта статья для frontend-разработчиков, которые хотят сделать растущее приложение проще в поддержке. На примере маркетплейса покажем, как разделить код на модули, связать сервисы и проверять бизнес-логику отдельно от интерфейса. Примеры написаны на React и TypeScript, но подход можно использовать с другим UI-фреймворком.

Основной вопрос — как провести границы между частями приложения. Оформлению заказа нужен расчёт доставки, корзине — данные о товарах. Как связать их так, чтобы изменение одной фичи не требовало правок по всему проекту? И как сохранить код понятным разработчикам и LLM, не перегружая его абстракциями?

Мы используем собственное разбиение на feature-модули: каталог, корзину, доставку и другие части приложения. Это не реализация Feature-Sliced Design, хотя отдельные принципы могут совпадать. Разберём структуру директорий, допустимые зависимости, сборку сервисов через DI, хранение состояния и доступ к платформенным API.

Код примера доступен в репозитории. В нём есть работающий интерфейс, простой DI-контейнер, архитектурные ESLint-правила, ADR и инструкции для агентов.

Физическая организация модулей

Один из вопросов, который возникает при проектировании архитектуры: как физически организовать код в файловой системе. Один из распространённых вариантов — группировать файлы по их техническому назначению:

Такая структура хорошо подходит для небольшого приложения: её преимущества очевидны — она проста и понятна. Однако по мере роста проекта каждый технический слой начинает объединять совершенно разные, а зачастую и слабо связанные части системы. Например, в нашем случае в каталоге services оказались бы сервисы корзины, авторизации, карточки товара, рекомендаций и других бизнес-направлений. При этом файлы, относящиеся к одной функциональности, были бы распределены по всему дереву проекта. В результате границы изменений становятся менее очевидными, сложнее оценить их влияние на систему и сформировать для LLM компактный и релевантный контекст.

Для маркетплейса мы выбрали организацию вокруг набора бизнес-сценариев (фич) приложения:

Каждый feature-модуль владеет определённой бизнес-логикой. Например, всё, что относится к корзине, находится внутри basket, логика каталога — внутри catalog, а работа с избранным — внутри favorites. Благодаря этому структура проекта отражает устройство продукта, а код, изменяющийся по одной бизнес-причине, оказывается собран в одном месте.

В infrastructure мы размещаем технические механизмы, не принадлежащие конкретному бизнес-сценарию: HTTP-клиент, работу с токенами сессии, логирование, локализацию, конфигурацию окружения и адаптеры внешних SDK. Feature-модули могут пользоваться инфраструктурой, но инфраструктура ничего не знает о конкретных фичах. Например, HTTP-сервис умеет отправлять запросы и обрабатывать транспортные ошибки, но не знает, что такое корзина или карточка товара. 

Слой app отвечает за процессы всего приложения. Здесь находятся точки входа, глобальная конфигурация, провайдеры и composition root — место, в котором создаются общие зависимости и feature-модули связываются между собой.

В pages мы собираем страницы из фич и связываем их с маршрутизацией. В shared оставляем переиспользуемые компоненты, чистые функции и небольшие stateless-адаптеры платформенных API без привязки к бизнес-сценариям.

Внутреннее устройство feature-модуля

Группировка вокруг бизнес-сценариев определяет владельца логики. Внутри каждой фичи мы дополнительно разделяем код по его роли: модели данных, сервисы, состояние, хуки и компоненты интерфейса.

Модуль создаёт только те роли, которые ему действительно нужны: небольшая фича может состоять из модели и одного хука, а более сложная — содержать собственные сервисы, состояние и UI.

Каждая роль предоставляет свой публичный вход через index.ts: в нём экспортируем только то, что понадобится остальному приложению. Общий barrel-файл в корне фичи не создаём — по импорту должно быть видно, какую часть фичи мы используем.

Как модули взаимодействуют между собой?

Физического разделения кода по директориям недостаточно: границы модулей определяются не их расположением, а связями между ними. Поэтому мы явно задаём допустимое направление зависимостей:

Вышестоящий слой может использовать публичные возможности нижестоящего, но не наоборот. Например, страница может подключить фичу, а фича воспользоваться HTTP-клиентом из инфраструктуры. При этом инфраструктура ничего не знает о бизнес-фичах, а фичи — о страницах, на которых они используются.

Дополнительно запрещаем runtime-импорты между разными фичами и импорты между разными страницами.

Фича не должна напрямую импортировать реализацию другой фичи, а одна страница — использовать внутренности другой страницы. Такие зависимости быстро размывают границы ответственности: изменение одного модуля начинает затрагивать соседние, а отдельную функциональность становится сложнее заменить, протестировать или удалить. По мере роста приложения граф зависимостей становится сложнее, в нём могут появляться неочевидные и циклические связи. В результате понять, как работает конкретная фича и от чего она зависит, становится труднее как человеку, так и LLM.

Но бизнес-сценарии не существуют изолированно. Корзине нужна информация о товарах, а оформлению заказа — расчёт стоимости доставки. Если фича не может напрямую использовать runtime-реализацию другой фичи, как тогда выразить такую зависимость?

Type-only зависимости

Полностью изолировать feature-модули друг от друга не только сложно, но и не всегда нужно. Например, корзина может оперировать типом товара, а аналитика — использовать тип поискового запроса. Такая зависимость описывает общий язык предметной области, но не требует загрузки чужой реализации.

Поэтому type-only импорты между фичами разрешены:

В отличие от обычного импорта, import type удаляется при компиляции TypeScript и не создаёт runtime-связь между модулями. Код корзины может знать форму товара, но при этом не загружает сервисы, store или UI модуля product.

Как передавать зависимости между модулями

Type-only импорты позволяют одному модулю использовать контракты другого, но не решают вопрос передачи runtime-реализаций.

Рассмотрим упрощённый пример взаимодействия двух feature-модулей. При оформлении заказа модулю checkout необходимо рассчитать стоимость доставки, но сама логика расчёта принадлежит модулю delivery.

Для примера зафиксируем простой контракт: сервис получает сумму товаров и возвращает стоимость доставки. 

Сначала вариант с прямым созданием зависимости:

Такой импорт запрещён нашим архитектурным ESLint-правилом: checkout выбирает конкретную реализацию чужой фичи и сам управляет её созданием. Вместо этого импортируем только контракт и получаем готовый сервис через конструктор:

Теперь CheckoutService получает сервис доставки снаружи, а не создаёт его самостоятельно. Такой подход называется внедрением зависимостей — Dependency Injection или DI.

В этом примере контракт принадлежит delivery и является частью его публичного API. В другом случае контракт может определяться потребителем: например, checkout может объявить минимальный интерфейс DeliveryCalculator, который реализует сервис доставки. Выбор зависит от того, кому по смыслу принадлежит контракт.

Остаётся определить, кто создаст оба сервиса и свяжет их между собой. Это задача слоя app, который разберём дальше.

Где собираются зависимости?

Сервисы связываем в слое app. Здесь runtime-импорты нескольких фич допустимы: этот слой выбирает реализации и собирает из них приложение.

Для этого мы используем DI-контейнер.

Важен здесь не сам DI-контейнер, а наличие composition root — места, где приложение выбирает конкретные реализации и связывает их между собой. Это можно сделать обычными конструкторами и фабриками. Контейнер лишь инструмент, который упрощает такую сборку, когда зависимостей становится много.

В примерах контейнер доступен как di из @infra/di. Покажем простой API: register сохраняет готовый экземпляр, а get возвращает его по токену.

Токен — идентификатор зависимости в контейнере. Типовой параметр указывает, какой сервис мы ожидаем получить:

В app создаём сервис доставки и передаём его сервису оформления заказа.

Здесь зависимости передаются явно. Имя токена не обязано совпадать с параметром конструктора: нужный сервис мы получаем через get и сами передаём в CheckoutService. Порядок регистрации важен — сервис доставки должен быть зарегистрирован раньше его потребителя.

registerServices() вызывается в точке запуска до рендера React-приложения. После этого хук своей фичи может получить готовый сервис:

Сам CheckoutService ничего не знает о контейнере. Он получает зависимость через конструктор, поэтому в тесте его можно создать напрямую, передав тестовый объект.

Так же передаются инфраструктурные зависимости. Например, сервисам нескольких фич можно передать общий HTTP-клиент: он отвечает за транспорт, а каждый feature-сервис — за свои запросы и обработку ответов.

Какую реализацию DI выбрать?

В небольшом приложении можно обойтись без контейнера: создать сервисы в app и передать зависимости в конструкторы вручную. Контейнер становится полезен, когда регистрацию, получение и жизненный цикл большого числа сервисов неудобно поддерживать самостоятельно.

Внутри команды на наших проектах мы обычно используем собственную реализацию DI-контейнера. Также в опенсорсе есть готовые библиотеки:

• TSyringe — контейнер с внедрением через конструкторы и декораторами.

• InversifyJS — позволяет связывать идентификаторы сервисов с реализациями и настраивать их создание.

• Awilix — вариант без обязательных декораторов, с регистрацией классов, фабрик и готовых значений.

• InferDI — контейнер с явной регистрацией сервисов и проверкой зависимостей на уровне типов TypeScript.

API и возможности библиотек различаются. Примеры выше используют учебный контейнер, который хранит готовые экземпляры. Такой же принцип показан в демо-репозитории: без автоматического внедрения и ленивой загрузки.

Жизненный цикл зависимостей тоже нужно определить. В клиентском приложении контейнер может существовать всё время работы приложения. При SSR сервисы с пользовательскими данными должны быть изолированы на запрос.

DI не исправляет неудачные связи между модулями. Если два сервиса требуют друг друга или для одной операции приходится передавать сервис с десятками несвязанных методов, стоит пересмотреть границы и контракты.

Где находятся пользовательские сценарии?

Сервисы загружают товары, рассчитывают доставку и отправляют заказы. Но действие пользователя обычно требует нескольких шагов: собрать данные, вызвать сервис, показать ожидание и обработать результат.

В нашем React-приложении за это отвечают хуки в слое hooks соответствующей фичи. Они вызывают сервисы, управляют состоянием сценария и возвращают компоненту данные и доступные действия. Например, useCheckout предоставляет функцию оформления заказа, признак отправки, ошибку и идентификатор созданного заказа.

При этом сложную бизнес-логику и последовательность бизнес-операций не переносим в хуки: хук связывает React с сервисами и управляет состоянием пользовательского сценария.

В учебном примере обойдёмся обычным useState. Предположим, что у CheckoutService есть метод placeOrder(input), который отправляет заказ и возвращает его идентификатор:

Компонент получает данные и функцию оформления заказа. Входные данные передаются при её вызове:

Где хранить состояние приложения?

Для этой архитектуры не требуется конкретная библиотека управления состоянием. Выбор зависит от того, откуда приходят данные, кто их использует и сколько они должны существовать. Мы выделяем три основные категории.

Серверное состояние — товары, заказы, доступные способы доставки и другие данные с сервера. На клиенте хранится их копия, которая может устаревать. Для загрузки, кэширования и обновления можно использовать React Query, SWR или RTK Query.

Клиентское состояние — выбранные позиции корзины, черновик заказа и другие данные, которыми пользуются несколько компонентов. Для него подходят Zustand, Redux Toolkit или состояние общего родительского компонента, передаваемое через props либо Context.

Локальное состояние — раскрытый блок, значение поля или состояние операции, нужное только одному компоненту или хуку. Обычно достаточно встроенных useState и useReducer.

Эти способы могут сочетаться на одном экране. Не нужно переносить всё в общий store или дублировать в нём данные, которыми уже управляет серверный кэш. Для каждого значения должно быть понятно, где оно хранится и кто его обновляет.

Как отделить логику от платформы?

До этого мы обсуждали зависимости между модулями приложения. Но у frontend-кода есть ещё один источник зависимостей — окружение, в котором он выполняется. Обращаясь к window, document, localStorage или браузерному SDK, мы неявно предполагаем, что код всегда будет работать в браузере и нужный API окажется доступен.

Это предположение удобно до тех пор, пока модуль не потребуется импортировать в серверном окружении, запустить в тестах или использовать в другой платформенной реализации. Даже в браузере отдельные возможности могут быть недоступны: например, доступ к storage может быть ограничен настройками окружения.

Под platform-agnosticподходом мы понимаем явное отделение логики приложения от таких платформенных возможностей. Это не означает, что React-компоненты автоматически смогут работать в любом runtime. Речь о том, чтобы зависимость от конкретного окружения была локализована и имела понятный контракт.

Доступ к платформенным API

В нашем приложении доступ к браузерным API сосредоточен в shared/platform. Например, вместо прямого обращения к localStorage используется функция, которая проверяет его доступность:

Вызывающий код обязан учитывать, что хранилище может отсутствовать:

Если хранилище недоступно или сохранённого запроса нет, read() возвращает null. При записи обрабатываем возможную ошибку: например, превышение квоты. Поиск продолжает работать, даже если последний запрос не удалось сохранить.

Что остаётся зависимым от React?

Компоненты и хуки остаются связаны с React. Модели, расчёты и сервисы мы отделяем от React и браузерных API, чтобы использовать одну и ту же логику в разных окружениях. При смене платформы меняются интерфейс и платформенные адаптеры, а бизнес-логика сохраняется.

Как проверить, что границы работают?

Архитектура полезна, если её правила можно проверить. В нашем случае ESLint ограничивает направление импортов, запрещает runtime cross-импорты между фичами и прямое обращение к браузерным глобальным объектам вне платформенного слоя. TypeScript проверяет соответствие реализаций контрактам, а тесты — их поведение. Правило no-restricted-globals само по себе не перекрывает все способы доступа, например globalThis.window: такие формы тоже нужно учитывать в конфигурации проверок.

Простой практический тест для DI — можно ли создать сервис без запуска приложения. В примере оформления заказа достаточно передать небольшой объект с методом calculate:

Тест не инициализирует React, не создаёт контейнер и не импортирует реализацию delivery. Мы проверяем именно правило checkout: доставка включается в итоговую сумму. Сам расчёт тарифа проверяется отдельно, внутри delivery. Дополнительный интеграционный тест должен проверять сборку контейнера: правильно ли зарегистрированы токены и удаётся ли получить готовый CheckoutService.

Цена такого подхода

У подхода есть накладные расходы: токены, регистрации и контракты увеличивают объём кода, а часть ошибок сборки обнаруживается только при выполнении. Излишнее дробление фич и слишком общие интерфейсы могут сделать проект сложнее. Поэтому мы не оборачиваем в DI каждую функцию, используем только там, где нужно межфичевое взаимодействие.

Для небольшого приложения нескольких модулей и явной передачи зависимостей может быть достаточно. Контейнер становится полезен, когда сборка повторяется, зависимостей становится много или нужны разные реализации. Критерий тот же, с которого мы начали: структура должна упрощать работу над продуктом, а не требовать постоянных объяснений самой себя.

Итоги

В итоге мы организовали код вокруг понятных бизнес-сценариев, внутри модулей разделили его по роли и явно задали допустимые зависимости. Сервисы загружают товары, рассчитывают доставку и отправляют заказы, хуки связывают эту логику с интерфейсом, а состояние остаётся у своего владельца. DI переносит выбор реализаций в точку сборки, платформенный слой локализует работу с окружением.

Это не универсальная схема и не набор обязательных папок.

Пользу от такой организации проще всего оценить на обычной задаче. Нужно изменить расчёт доставки — понятно, где лежит код, кто его вызывает и как проверить, что всё работает. Если для этого приходится разбираться в половине приложения, стоит пересмотреть границы модулей.

При этом не стоит увлекаться изящными абстракциями. Не каждой функции нужен сервис, не каждому классу — интерфейс, а небольшой задаче — ещё один слой. Код должен быть простым и понятным и для разработчика, и для LLM, которой вы поручаете изменения. Если для небольшой правки приходится объяснять модели устройство всего проекта и загружать десятки файлов, стоит проверить, не усложнили ли вы архитектуру. Добавлять абстракцию стоит тогда, когда она решает конкретную проблему и с ней действительно проще работать.