Feature-based структура проекта: как разложить код по смыслу, а не по типам файлов
Текст написан с позиции сентября 2018 года: так, как тема выглядела тогда, без технологий и событий, появившихся позже.
Одна из самых устойчивых проблем во фронтенд-проектах появляется не тогда, когда код уже совсем развалился, а намного раньше — в тот момент, когда структура каталогов еще выглядит аккуратно, но уже начинает подталкивать команду к неправильному мышлению. Обычно это происходит почти незаметно. На старте все кажется логичным: вот папка components, вот actions, вот reducers, вот utils, вот services, вот pages. Визуально все на месте, по типам файлов разложено, новичку как будто даже проще ориентироваться. Но проходит немного времени, проект растет, и выясняется, что такая аккуратность была скорее косметической, чем архитектурной. Код продолжает накапливаться, а ответ на главный вопрос — «где живет логика конкретной части продукта?» — становится все менее очевидным.
Именно на этом фоне feature-based структура проекта начинает выглядеть не модной альтернативой, а довольно здравым шагом взросления. Ее основной принцип на удивление прост: раскладывать код не по техническому типу файла, а по смысловым областям приложения. Не складывать все компоненты в одну общую папку просто потому, что они компоненты. Не хранить все reducers вместе только потому, что это reducers. Не собирать actions, selectors, validators и helpers в отдельные глобальные кучи. Вместо этого группировать то, что относится к одной feature-области, рядом. То есть строить структуру проекта так, чтобы она отвечала прежде всего на вопрос «к какой части продукта относится этот код?», а уже потом — «что это за техническая сущность?»
Самая поверхностная реакция на эту мысль — услышать «раскладывайте код по feature» и решить, что речь идет о косметике: переименовать папки, переложить файлы, и порядок наведен. Но это не про новые имена каталогов, а про то, на какой вопрос отвечает структура в первую очередь. На сентябрь 2018 года такая идея уже не выглядит странной. Наоборот, она довольно хорошо совпадает с тем, как развивался фронтенд последние годы. Компонентный подход укрепился. Redux и похожие практики заставили серьезнее думать о границах состояния. TypeScript научил команды формализовывать контракты. Backend-слой в JavaScript-мире тоже стал говорить о модулях и доменах. На этом фоне файловая структура по техническим типам начинает казаться пережитком эпохи, когда приложение было либо маленьким, либо слишком хаотичным, чтобы его вообще можно было осмысленно разложить по предметным зонам. В большом интерфейсе вопрос «какой это тип файла?» часто оказывается не самым важным. Намного важнее вопрос: «какой кусок продукта мы сейчас открыли?»
Структура по типам файлов выигрывает только на короткой дистанции
Проблема структуры по типам файлов в том, что она хорошо служит проекту только на очень короткой дистанции. Пока у вас десять компонентов, одна форма и один reducer, папка components не вызывает боли. Но как только компонентов становится сто, а reducers, selectors, service-функции и типы размазываются по всему репозиторию в разных местах, возникает неприятный эффект. Чтобы понять одну feature, разработчик вынужден постоянно прыгать между разными папками. UI находится в одном месте. Логика состояния — в другом. API-запрос — в третьем. Типы — в четвертом. Валидация — в пятом. Тесты — где-то еще. И хотя каждый фрагмент формально лежит «на своем месте», сама feature как смысловая единица нигде не существует целиком. Ее нужно каждый раз заново собирать в голове.
Это и есть ключевой недостаток типовой структуры: она оптимизирует навигацию по техническим ролям, но ухудшает навигацию по продуктовой логике. Разработчик быстро понимает, где лежат все reducers вообще. Но ему гораздо сложнее быстро увидеть, где живет вся логика, связанная, например, с поиском пользователей, корзиной, профилем, фильтрами товаров или настройками аккаунта. В реальной повседневной работе второй вопрос обычно важнее первого. Мы реже открываем проект с мыслью «пойду-ка я посмотрю на reducers как явление». Намного чаще мы идем по следу конкретного сценария пользователя или конкретной feature. И именно здесь feature-based структура начинает выигрывать очень заметно.
Feature перестаёт быть мыслью в голове и становится видимой единицей кода
Когда код разложен по смыслу, каждая feature превращается в относительно самостоятельный модуль. У нее могут быть свои компоненты, свои selectors, свои reducers или контекст, свои типы, свои запросы к API, свои тесты. Все это не обязательно хранить в одной плоской папке без иерархии, но важно, что эти сущности живут рядом, потому что относятся к одному куску приложения. Такой подход дает очень простой, но мощный эффект: feature перестает быть абстрактной мыслью в голове разработчика и становится видимой единицей кода. Это резко облегчает чтение, изменение и сопровождение.
Особенно хорошо это ощущается в больших командах. Пока проект пишет один человек, он еще может компенсировать неудачную структуру собственной памятью. Он знает, что в components лежит UI, в selectors — производные данные, в api — вызовы, а странная функция для фильтрации на самом деле почему-то живет в utils. Но как только над проектом работают несколько разработчиков, а особенно если люди регулярно подключаются к новым частям системы, такая карта в голове перестает быть устойчивым решением. Нужна структура, которая сама подсказывает, где искать код конкретной feature. Feature-based подход как раз и дает эту самопоясняемость. Открывая папку user-profile или product-search, разработчик видит не абстрактный технический слой, а реальную функциональную область.
Структура по смыслу делает границы ответственности заметными
Очень важно, что такая структура почти автоматически улучшает разговор об ответственности кода. Когда UI, состояние, запросы и типы живут рядом внутри feature, становится намного труднее незаметно размывать границы. Уже не так просто вынести странную логику в глобальный utils только потому, что не хочется решать, где ей место. Уже не так просто добавить кусок состояния в общий reducer без понимания, к какой области он относится. Уже не так просто положить компонент в огромную глобальную папку, где он потеряется среди десятков несвязанных соседей. Feature-based структура не делает неправильные решения невозможными, но делает их более видимыми и, значит, более обсуждаемыми.
Подход работает там, где есть реальные продуктовые области, а не красивые папки
При этом важно не превратить саму идею в новый ритуал. Feature-based подход хорош не потому, что нужно любой ценой упаковать весь проект в папки с красивыми названиями feature. Он хорош тогда, когда в приложении действительно есть осмысленные продуктовые области. А они есть почти всегда, как только проект становится крупнее демонстрационного примера. Например, поиск, авторизация, профиль пользователя, каталог, корзина, оформление заказа, уведомления, модуль отчетов, управление ролями, комментарии, редактор сущности, список задач. Все это естественные feature-области. Если проект раскладывается вокруг таких понятий, его структура начинает говорить на языке продукта, а не только на языке инфраструктуры.
Это особенно полезно еще и потому, что технические роли во фронтенде становятся все более многочисленными. Если раньше можно было ограничиться компонентами, стилями и парой сервисных файлов, то сейчас в реальных приложениях уже обычно есть и selectors, и reducers, и context, и types, и schemas, и validation, и эффекты, и тесты нескольких уровней, и иногда storybook-обвязка, и локальные утилиты, и адаптеры данных. Если все это раскладывать строго по типам файлов, структура проекта начинает напоминать каталог типов инженерной деятельности, а не карту продукта. Каждый новый технический слой добавляет еще одну общую папку, и навигация распадается еще сильнее. Feature-based подход в этом смысле просто лучше масштабируется вместе с современной сложностью фронтенда.
Локальность лечит ложное переиспользование лучше, чем общие папки
Очень показателен вопрос о повторном использовании. У типовой структуры есть скрытое свойство: она психологически поощряет преждевременную «общность». Раз компонент лежит в components, кажется, будто он уже почти общий. Раз helper лежит в utils, кажется, будто его можно использовать где угодно. Раз selector вынесен в общую папку, будто бы он уже принадлежит всей системе. На практике это часто ведет к ложному переиспользованию. Код, который на самом деле связан с одной feature, выдается за универсальный только потому, что физически лежит в общем каталоге. Feature-based структура, наоборот, делает локальность естественной. Компонент по умолчанию принадлежит feature, а не «всему приложению». Если позже выяснится, что он действительно становится общим примитивом, его можно поднять выше осознанно. Но не заранее и не автоматически.
Это очень здоровая архитектурная привычка: двигать код к большей общности только тогда, когда общность действительно доказана. А не наоборот — объявлять почти все потенциально общим лишь потому, что так удобнее разложить в папках. В этом смысле feature-based структура помогает бороться с одним из самых распространенных видов фронтенд-хаоса: разрастанием глобальных «общих» слоев, которые фактически становятся свалкой разнородного кода.
Общий слой не исчезает, а перестаёт быть центром мира
Разумеется, это не означает, что в проекте вообще не должно быть общих папок верхнего уровня. Почти всегда есть слой действительно общих вещей: дизайн-примитивы, базовые UI-компоненты, инфраструктура приложения, роутинг, глобальные типы окружения, общие библиотеки доступа к API, механизмы темы, утилиты нижнего уровня, которые действительно нейтральны. Но разница в том, что в feature-based подходе эти общие слои перестают быть центром мира. Центром становится продуктовая карта приложения, а общий код — это уже отдельный и более строго охраняемый слой, куда попадает далеко не все подряд. Такое смещение центра тяжести обычно очень полезно.
Собранная рядом feature намного спокойнее переживает рефакторинг
Есть еще одна важная выгода, которая особенно заметна при рефакторинге. Когда feature собрана рядом, ее намного проще перемещать, переосмысливать, разбивать или даже удалять. Если нужно вынести модуль в отдельный пакет, отключить функциональность, переписать один большой сценарий или заменить способ управления состоянием в одной части приложения, работать с локализованной feature гораздо спокойнее. В типовой структуре такие изменения почти всегда сопровождаются широким археологическим походом по репозиторию: здесь лежит UI, тут — selectors, тут — тесты, тут — API-вызовы, тут — валидация. То есть даже локальный рефакторинг начинает ощущаться как изменение всей системы. Feature-based модульность уменьшает этот эффект.
Очень полезно и то, что такая структура хорошо сочетается с разными внутренними архитектурными стилями. Неважно, используете вы Redux, Context, reducers, сервисный слой, TypeScript или более легкий JavaScript-проект — feature-based принцип живет выше этих деталей. Внутри одной feature у вас может быть свой reducer, у другой — просто локальный context, у третьей — более выраженный API-слой. При этом общая навигация по проекту остается стабильной: сначала мы входим в продуктовую область, а уже потом видим ее техническое устройство. Это намного удобнее, чем когда сама верхняя структура проекта меняется всякий раз, как команда принимает новую техническую практику.
Лес папок по три файла и feature, перепутанная со страницей, — типичные срывы подхода
Впрочем, было бы нечестно делать вид, будто feature-based структура не имеет своих рисков. Они есть, и их стоит проговорить. Первый риск — чрезмерная детализация feature. Иногда команда настолько вдохновляется идеей, что начинает выделять feature под каждый малейший фрагмент интерфейса. В итоге вместо ясных продуктовых областей появляется лес папок, каждая из которых содержит три файла и слабо отличается от соседней. Это перегружает структуру и делает ее не менее утомительной, чем разложение по типам. Feature должна быть достаточно крупной, чтобы выражать реальную функциональную зону, а не каждый визуальный элемент по отдельности.
Второй риск — отсутствие продуманного слоя shared-кода. Если толковать feature-based подход слишком буквально, можно дойти до другой крайности: начать дублировать действительно общие вещи просто потому, что «пусть все живет внутри feature». Это тоже не здорово. В хорошей системе должны быть и feature-области, и аккуратно организованный общий слой. Вопрос не в том, чтобы отрицать общность, а в том, чтобы не объявлять общим то, что еще не доказало свою общность. То есть структура по смыслу требует не отказа от shared, а более зрелого отношения к нему.
Третий риск — путаница между feature и страницей. Это очень распространенная ошибка. Страница и feature могут пересекаться, но не обязаны совпадать. Например, на одной странице могут жить несколько feature-областей: фильтры, список сущностей, блок уведомлений, панель действий. И наоборот, одна feature может использоваться на нескольких страницах. Если привязать все слишком жестко к страницам, структура станет отражать только навигацию, а не реальные области логики. Поэтому feature-based подход требует все-таки думать о функциональности, а не только о роутинге.
Публичная поверхность feature превращает навигацию в контроль зависимостей
Отличить feature от страницы или компонента помогает простой вопрос: если бы нам пришлось переиспользовать или отдельно развивать этот кусок продукта, был бы он самодостаточной областью со своей логикой, UI и состоянием? Если ответ да, скорее всего перед нами feature. Если нет, возможно, это просто компонент, внутренний подмодуль или часть другой более крупной feature. Такая проверка лучше, чем механическое деление по размеру или по количеству файлов.
Практически feature-based структура часто оказывается особенно хорошей в сочетании с локальными barrel-файлами или публичными API на уровне папок. То есть внутри feature может быть сколько угодно файлов и подпапок, но наружу она экспортирует только то, что действительно считается ее публичной поверхностью. Это очень полезно для удержания границ. Тогда другие части приложения не начинают обращаться к внутренностям feature напрямую. Они взаимодействуют с ней через более осмысленный вход: компонент, selector, action creator, service-функцию или тип, которые feature официально предоставляет. В результате структура по смыслу превращается не только в удобную навигацию, но и в реальное средство контроля зависимостей.
Тесты и язык команды тоже выигрывают от структуры по смыслу
Отдельно стоит сказать о тестах, потому что именно они часто особенно страдают в типовой структуре. Когда тесты живут отдельно от feature, понимание того, что именно покрывается и к чему относится сценарий, становится менее очевидным. В feature-based подходе тесты естественно держать рядом с кодом той области, которую они проверяют. Это удобно не только с точки зрения навигации. Это еще и психологически делает тестирование частью feature, а не внешней технической обязанностью. Точно так же рядом могут жить stories, mock-данные, fixtures и локальные схемы валидации. Все это усиливает ощущение, что feature — реальная единица разработки, а не просто папка.
Есть и культурный эффект внутри команды. Когда структура проекта построена по смысловым областям, обсуждение задач и код-ревью тоже становятся предметнее. Люди говорят не «я менял что-то в components и reducers», а «я работал над модулем фильтрации каталога» или «я трогал feature комментариев». Это кажется мелочью, но на самом деле меняет мышление. Команда начинает говорить о продукте через код, а о коде — через продукт. Для долгоживущих систем это очень полезная форма выравнивания.
Переход стоит делать эволюционно, а не косметическим переездом файлов
На практике переход к такой структуре не обязательно должен быть революционным. Более того, полная мгновенная перестройка большого проекта часто только пугает команду и создает много шума. Гораздо разумнее начинать с новых feature и с наиболее болезненных старых областей. Если есть очевидно перегруженный модуль, который сегодня размазан по components, actions, selectors и utils, можно собрать его рядом и посмотреть, как изменится стоимость работы с ним. Обычно эффект становится заметен довольно быстро. А когда команда однажды почувствовала, насколько проще читать и менять feature, собранную в одном месте, возвращаться к плоской типовой структуре уже не хочется.
Очень важно только не превратить переход в косметический переезд файлов без пересмотра смысловых границ. Если просто создать папки с названиями feature, но внутри продолжать тащить старые привычки — общий utils, бессмысленные shared-хелперы, глобальные типы без границ, компоненты без явной принадлежности, — эффект будет слабее. Feature-based структура работает по-настоящему тогда, когда за ней стоит готовность спрашивать: к какой части продукта относится этот код? должен ли он быть локальным? действительно ли он общий? где проходит граница этой feature? Без этих вопросов любая структура со временем деградирует.
Структура должна говорить языком продукта, а не языком типов файлов
Если подвести итог совсем прямо, то feature-based подход ценен потому, что он делает файловую структуру ближе к тому, как команда реально думает о продукте. Мы строим не приложение из «reducers, components и utils», а приложение из поиска, профиля, каталога, корзины, отчетов, уведомлений и других функциональных областей. Технические роли внутри этих областей, конечно, никуда не исчезают. Но они перестают определять верхний уровень карты проекта. А это и есть главный поворот: структура начинает отвечать не на вопрос «что это за тип файла?», а на вопрос «какой смысловой кусок системы мы сейчас рассматриваем?»
Сейчас это выглядит очень своевременно. Проекты стали достаточно сложными, чтобы глобальные кучи компонентов, reducers и utils перестали быть безобидными. Команды стали достаточно большими, чтобы память отдельных людей уже не могла компенсировать неудачную навигацию. А экосистема стала достаточно зрелой, чтобы признать: порядок в проекте — это не про красивый список типов файлов, а про то, насколько код отражает реальную структуру продукта. Именно поэтому feature-based организация выглядит не как очередная модная схема, а как довольно естественный способ разложить код по смыслу — и тем самым сделать его заметно спокойнее для жизни.
Раскладывайте код не по тому, что это за тип файла, а по тому, к какой части продукта он относится, — и охраняйте границу shared-слоя так же строго, как границы самих feature.