Создание модулей теория

В этом уроке мы разберём, как реализовать модули приложения внутри кодовой базы. Модули — это ключевые строительные блоки архитектуры. Мы определили их ранее, когда создавали Design Doc: модуль Home, модуль Login, модуль Delivery и т.д.

Во многих случаях модули совпадают по смыслу с маршрутами системы. Например, модуль доставки часто соответствует маршруту /delivery. Но важно понимать: модули и маршруты — разные концепции, и их не всегда стоит смешивать.

Маршруты Next.js и модули

Напомню, что Next.js использует файловую маршрутизацию, где:

• любой page.tsx внутри папки app становится отдельным маршрутом;
• папка = сегмент URL;
• вложенность папок = вложенность маршрутов;
• существует множество соглашений для динамических и параметризованных маршрутов.

Получается что файл page.tsx в папке /app становится маршрутом /. Если внутри папки /app создать папку /delivery и внутри нее положить файл page.tsx, он станет отображаться по маршруту /delivery. Также мы можем создавать динамические маршруты. Например для создания страницы ресторана мы создадим следующую структуру папок - /app/restaurant/[id]. В данном случае файл page.tsx размещенный по этому пути будет отображаться на странице /restaurant/:id, где id является динамическим параметром.

На первый взгляд кажется логичным складывать содержимое модуля (его компоненты, логику и т.п.) прямо в папку маршрута delivery/ или home/. Но у этого подхода есть несколько проблем.

1. Модули не всегда совпадают с маршрутами 1:1

Некоторые модули могут не иметь собственных маршрутов.

Например:

• Shopping Cart — корзина существует как логика, но не обязательно будет иметьсобственный URL.
• Auth — модуль авторизации также не всегда соответствует страницам.

Если складывать код по маршрутам, такие модули окажутся «без места» — и придётся создавать странные структуры или использовать нестандартные соглашения (например, папки в скобках в Next.js).

2. Хочется видеть все модули в одном месте

Если модули раскиданы по папкам маршрутов, они теряются в структуре app/. Гораздо удобнее иметь единую директорию, например /modules в которой будут храниться все модули приложения.

3. Маршруты ≠ архитектурная структура

Модули — часть архитектуры. Маршруты — часть фреймворка. Маршруты отражают только URL-ы. Модули отражают:

• доменные задачи,
• бизнес-логику,
• связанную функциональность.

Поэтому лучше разделять эти уровни.

4. Вложенные маршруты могут ломать навигацию по модулям и иерархию

Например:

• Модуль Menu Item является частью модуля Restaurant по маршрутам (/restaurant/:id/menu/:itemId).
• Но по смыслу это отдельный модуль. Если хранить код внутри маршрутов, найти модуль будет сложно.

Предлагаемая структура

Итак внутри папке /app оставляем только маршруты. Внутри маршрутов только рендер и какие-то простейшие операции.

Внутри маршрутов — только рендер и простые операции:

// app/delivery/page.tsx
import { DeliveryPage } from "@/modules/delivery";

export default function Page() {
  return <DeliveryPage />;
}

Содержимое модулей храним в папке /modules. Подходов к организации файлов внутри модулей существует огромное количество. Давайте рассмотрим два из них.

Подход 1: Классическая модульная архитектура

Это подход к организации кода, при котором приложение разбивается на независимые, самодостаточные блоки (модули), каждый из которых отвечает за конкретную функциональность. Каждый модуль — это «мини‑приложение» внутри общего проекта. Он содержит всё необходимое для своей работы:

• компоненты UI;
• логику (хуки, сервисы);
• управление состоянием (stores);
• стили;
• константы и утилиты;
• тесты и т.д.

Модули слабо связаны друг с другом, что снижает риск побочных эффектов при изменениях.

Ключевые принципы модульной архитектуры:

• Инкапсуляция Всё, что нужно модулю, находится внутри его директории. Внешние компоненты не лезут в его внутренности.
• Изоляция Модули не зависят друг от друга напрямую. Общение — через чётко определённые интерфейсы (например, пропсы или события).
• Повторное использование Общие компоненты, хуки и утилиты выносятся в отдельную папку shared и подключаются всеми модулями.
• Чёткие границы Модули могут обращаться только к общим ресурсам (shared), но не к внутренностям других модулей.
• Единообразие структуры Для всех модулей используется одинаковая организация папок и файлов (например, components/, hooks/, stores/).

В модульной архитектуре каждый модуль, как правило имеет одинаковую структуру. Например, в каждом модуле следующие папки:

• features/
• components/
• hooks/
• services/
• types/
• utils/

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

Безусловно, такой подход имеет и недостатки. Например, нам необходимо время на проектирвоание архитектуры (то чем мы как раз и занимаемся сейчас). При росте числа модулей сложнее управлять их связями, иногда может возникать дублирование кода и т.д. Основная мысль - не существует "серебрянной пули" или универсального подхода, решающего любые проблемы. В каждом конкретном случае нужно принимать решение исходя из конкретных задач и требований. Однако, модульная архитектура идеально подходит в нашем случае. Она довольно понятна и легко усваивается даже начинающими архитекторами, поэтому мы и будем использовать этот подход в следующих уроках.

Однако, чтобы показать вам, что могуть быть и другие варианты построения архитектруы давайте обсудим довольно популярный подход - FSD.

Feature‑Sliced Design (FSD)

Feature‑Sliced Design (FSD) — архитектурная методология созданная специально для фронтенд‑проектов. Это не жёсткая архитектура, а свод правил и соглашений по организации кода. Её цель — сделать проект понятным, структурированным и удобным для поддержки, особенно при частых изменениях требований.

FSD делит код на слои, слайсы и сегменты по чётким правилам. Слои, слайсы и сегменты образуют иерархию, как показано на схеме: !(FSD Visualization)[https://s3.twcstorage.ru/f280a6ef-learning-hub-test/lessons/frontend-architecture/assets/FSD%20visual%20schema.jpg]

Слои стандартизированы во всех проектах FSD. Вам не обязательно использовать все слои, но их названия важны. На данный момент их семь (сверху вниз):

1. App — всё, благодаря чему приложение запускается — роутинг, точки входа, глобальные стили, провайдеры и т. д.
2. Processes (процессы, устаревший) — сложные межстраничные сценарии.
3. Pages (страницы) — полные страницы или большие части страницы при вложенном роутинге.
4. Widgets (виджеты) — большие самодостаточные куски функциональности или интерфейса, обычно реализующие целый пользовательский сценарий.
5. Features (фичи) — повторно используемые реализации целых фич продукта, то есть действий, приносящих бизнес-ценность пользователю.
6. Entities (сущности) — бизнес-сущности, с которыми работает проект, например user или product.
7. Shared — переиспользуемый код, особенно когда он отделён от специфики проекта/бизнеса, хотя это не обязательно.

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

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

Слайсы, а также слои App и Shared, состоят из сегментов, а сегменты группируют код по его назначению. Имена сегментов не зафиксированы стандартом, но существует несколько общепринятых имен для наиболее распространенных целей:

• ui — всё, что связано с отображением: UI-компоненты, форматтеры дат, стили и т.д.
• api — взаимодействие с бэкендом: функции запросов, типы данных, мапперы.
• model — модель данных: схемы валидации, интерфейсы, хранилища и бизнес-логика.
• lib — библиотечный код, который нужен другим модулям этого слайса.
• config — файлы конфигурации и фиче-флаги. Обычно этих сегментов достаточно для большинства слоев, поэтому свои собственные сегменты обычно создают только в Shared или App, но это не жёсткое правило.

Преимущества FSD: Масштабируемость — легко добавлять новые фичи без нарушения структуры. Поддерживаемость — изменения в одном срезе редко влияют на другие. Стандартизация — единые правила упрощают онбординг новых разработчиков. Параллельная разработка — команды могут работать над разными срезами независимо. Тестируемость — каждый срез можно тестировать изолированно. Повторное использование — общий код выносится в shared. Гибкость — можно внедрять постепенно, даже в существующий проект.

Ограничения и сложности FSD подхода: Избыточность для простых проектов — для мини‑проектов FSD может добавить лишней сложности. Начальные затраты — нужно время на проектирование и настройку. Строгие правила — требуют дисциплины и ревью кода. Кривая обучения — новым разработчикам нужно время, чтобы разобраться в структуре. Не для всех стеков — лучше всего работает с React, но применим и к другим фреймворкам.

Feature‑Sliced Design (FSD) стоит изучить, потому что это современная методология организации фронтенд‑кода, которая учит структурировать проекты по бизнес‑логике, обеспечивает масштабируемость, снижает связанность компонентов и упрощает командную разработку — всё это критически важные навыки для профессионального роста. Однако в текущем проекте мы не будем её применять, поскольку FSD предполагает достаточно сложную систему слоёв, слайсов и сегментов с жёсткими правилами зависимостей, что может перегрузить начинающих: на раннем этапе важнее освоить базовые принципы модульности и компоненты, не погружаясь в детали строгой архитектурной методологии.

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