Как проектировать React-приложение так, чтобы через год его не хотелось переписать

•
Опубликовано
•
16 мин чтения

Текст написан с позиции октября 2024 года: так, как тема выглядела тогда, без технологий и событий, появившихся позже.

Желание переписать React-приложение через год после старта почти никогда не означает, что команда внезапно “поумнела”, а прошлые решения были глупыми. Обычно это симптом более приземленной проблемы: приложение росло быстрее, чем росла ясность его границ. Сначала все выглядело вполне разумно. Есть роуты, есть страницы, есть компоненты, есть несколько хуков, где-то лежат запросы, где-то стор, где-то формы, где-то общие утилиты. На ранней стадии этого почти всегда хватает. Но проходит время, и внезапно выясняется, что каждое изменение тянет за собой не одну локальную правку, а цепочку случайных зависимостей. Компоненты знают слишком много. Страницы стали оркестраторами половины системы. Общие модули превратились в склад всего подряд. Состояние расползлось по нескольким уровням, а простая задача почему-то требует лезть в пять файлов, три эффекта и один старый helper, про который никто уже не помнит, зачем он был написан.

Вот в этот момент и рождается опасная мысль: “может, проще переписать заново?”. Она кажется рациональной не потому, что люди любят переписывать код, а потому, что система перестает ощущаться управляемой. У разработчика исчезает чувство локальности. Он больше не уверен, что понимает последствия изменения. Каждая новая фича как будто не встраивается в проект, а пробивает его с усилием. И если такая динамика сохраняется, переписывание начинает выглядеть не как каприз, а как единственный способ снова почувствовать контроль.

Самая вредная реакция на этот момент — услышать “систему пора переписать” и решить, что проблема была в выборе библиотеки, структуре папок или недостатке модного стека. Переписывание очень редко лечит корень. Если команда не меняет подход к проектированию, новый код через год приходит примерно туда же, просто по более свежему маршруту. Поэтому полезнее не мечтать о будущем heroic rewrite, а изначально строить React-приложение так, чтобы оно умело взрослеть без ощущения архитектурного распада. И речь тут не о том, чтобы “сразу придумать идеальную систему на годы вперед”, а ровно об обратном: самые живучие проекты стартуют не с гигантского blueprint, а с нескольких правильных ограничений и ясных правил, которые помогают коду расти без потери формы.

Именно в этом смысле хороший React-проект отличается не количеством папок и не модностью стека. Он отличается тем, насколько спокойно переживает изменение. Если через год вы не хотите его переписать, это почти всегда значит, что приложение сохранило три вещи: понятные границы, соразмерную сложность и предсказуемую эволюцию. Все остальное — уже следствие. Вопрос проектирования здесь не “какой стек выбрать”, а “как сделать так, чтобы изменение оставалось локальным”.

Начинать нужно не со структуры папок, а с карты изменений

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

Например, если вы строите внутренний кабинет, то, скорее всего, часто будут меняться формы, таблицы, фильтры, роли, сценарии согласования, состояние выбранных сущностей. Если вы делаете контентный продукт, чаще будут меняться состав экранов, блоки представления, загрузка данных, SEO-значимые страницы, система карточек и навигация. Если это сложный SaaS-интерфейс, через год вы почти наверняка увидите рост общих workflow, feature-флагов, экранов с несколькими зависимыми зонами и большого количества полуглобального UI state.

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

Проще говоря, хороший проект не пытается заранее ответить на все вопросы. Он заранее выбирает, какие вопросы будут самыми частыми, и строит для них удобную форму.

Самая полезная ранняя дисциплина — разделять UI, данные и сценарии

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

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

Когда эти вещи спаяны внутри одного дерева компонентов без четких границ, система сначала кажется компактной, а потом внезапно становится липкой. Компоненты начинают знать и про API, и про маршруты, и про бизнес-ограничения, и про состояние соседних зон экрана. Любой рефакторинг превращается в операцию на живом организме. А вот когда UI, данные и сценарии различены хотя бы на уровне мышления, приложение взрослеет намного спокойнее.

Это не значит, что каждый клик должен проходить через архитектурную церемонию из десяти слоев. Речь о другом: у кода должна быть понятная причина жить именно там, где он живет. Визуальный компонент не должен превращаться в полусервис. Хук загрузки не должен незаметно становиться центром бизнес-правил. Страница не должна быть местом, где случайно собрались и layout, и orchestration, и все условия мира.

Не делайте “общие компоненты” слишком рано

Парадокс React-разработки в том, что многие проекты начинают стареть не из-за дублирования, а из-за преждевременного переиспользования. Команда видит два похожих блока и немедленно создает универсальный компонент. Потом появляется третий похожий блок — в компонент добавляют еще пропсы. Через полгода это уже monster-компонент, который умеет почти все, но только если знать двадцать скрытых комбинаций параметров и помнить, какие из них исторически нельзя сочетать.

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

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

Состояние должно жить там, где у него минимальная зона ответственности

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

Хорошее проектирование почти всегда начинается с простого вопроса: кто на самом деле владеет этим состоянием? Если выбор фильтра влияет только на одну страницу и не должен жить за ее пределами, нет причин тянуть его в глобальный store ради ощущения порядка. Если активная сущность нужна нескольким удаленным областям экрана и участвует в последовательности пользовательских действий, делать вид, что это локальный state одного компонента, тоже вредно.

Зрелый подход здесь не в том, чтобы заранее выбрать “все локально” или “все через store”. Он в том, чтобы для каждого типа состояния определить естественную область жизни. UI state, server state, form state, workflow state, selection state — у всех них разная природа. Чем раньше команда перестает складывать их в одну ментальную коробку, тем меньше шансов, что через год проект превратится в вязкий спор между разными способами хранения данных.

Страницы должны композировать, а не знать все

Есть очень типичный путь деградации React-приложения: страницы постепенно становятся умнее всех вокруг. В них живут загрузка данных, условия отображения, layout, логика роутинга, orchestration нескольких блоков, часть form state, эффекты для синхронизации и еще набор мелких правил, которые просто “некуда было положить”. Со временем страница превращается в файл, который никто не любит открывать и все боятся трогать.

Чтобы этого не случилось, полезно с самого начала считать страницу не мозгом всего экрана, а местом композиции. Она должна знать, какие крупные блоки входят в экран, какие данные на уровне маршрута или use case нужны им всем, как они компонуются и в каком порядке отображаются. Но она не должна быть местом, где живет каждая подробность поведения системы.

Это особенно важно в проектах, где через год почти наверняка появятся A/B-варианты экранов, новые зоны, дополнительные панели и растущие сценарии. Если страница изначально строится как точка сборки крупных, относительно самостоятельных блоков, такие изменения переживаются легче. Если же она сразу становится “толстым дирижером”, переписывание потом начинает казаться очень логичной мечтой.

API-слой должен быть скучным и предсказуемым

Один из самых недооцененных источников боли в React-приложениях — хаотичный слой работы с сетью. Где-то fetch живет прямо в компоненте. Где-то в hooks. Где-то в services. Где-то есть data client. Где-то response shape трансформируется сразу, где-то позже, а где-то вообще прямо в JSX. В моменте все это может работать. Через год оказывается, что приложение не столько сложно, сколько несогласованно.

Хороший API-слой должен быть скучным. Это комплимент. Скучный слой — это слой, в котором понятно, как формируются запросы, где происходит базовое преобразование ответа, где живут типы, где обрабатываются ошибки, где настраивается кэш и как frontend-код получает данные дальше. Чем меньше в этом слое сюрпризов и “особенных случаев”, тем меньше ментальной грязи накапливается в системе.

Именно здесь часто выигрывают не самые умные решения, а самые повторяемые. Если команда всякий раз делает запрос по-разному, никакой красивый UI-слой потом не спасет чувство архитектурной целостности. Через год такой проект хочется переписать не потому, что React плох, а потому что система потеряла единый ритм.

Хуки должны быть не тайным слоем магии, а ясными единицами поведения

Custom hooks сильно помогли React-сообществу, но одновременно создали новый тип архитектурного риска. Имена стали выглядеть очень чисто: useSomething, useSomethingElse, useFeature. Кажется, будто логика хорошо вынесена. Но если открыть файл, внутри часто оказывается смешение из запросов, локального состояния, бизнес-правил, эффектов, работы с роутером и побочных операций. Формально код “реиспользуемый”. По сути — это просто спрятанный сложный слой, который теперь еще труднее читать, потому что он маскируется под легкий hook.

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

Хороший тест очень простой: можно ли объяснить роль этого hook одной фразой без слов “и еще”? Если нет, возможно, он уже слишком многое на себя взял.

Думайте о модуле как о продуктовой области, а не как о наборе файлов

Очень многие React-проекты плохо стареют потому, что их структура отражает не продукт, а технические категории: components, hooks, utils, services, pages, store. На раннем этапе это удобно. На длинной дистанции такая структура начинает ломать локальность. Один пользовательский сценарий размазывается по нескольким глобальным папкам, и любое изменение превращается в навигацию по всему репозиторию.

Гораздо устойчивее живут проекты, где хотя бы часть структуры организована вокруг продуктовых областей или use-case зон. Например, users, billing, media, catalog, auth, notifications, reports. Внутри таких областей уже могут быть свои ui, model, api, hooks и что угодно еще. Но главное — связанный по смыслу код живет рядом. Это снижает когнитивную цену изменений и помогает разработчику мыслить не файлами, а участками продукта.

Именно такие структуры реже вызывают желание переписать все целиком. Потому что даже если отдельный модуль устарел, он ощущается как локальная зона, а не как щупальца по всему приложению.

Дизайн-система и приложение должны быть разведены по роли

Еще одна причина, по которой через год проект хочется сжечь, — смешение системного UI и продуктового UI. Если в “общих компонентах” одновременно живут button, modal и три виджета, сделанных под конкретный экран, очень скоро библиотека компонентов превращается в архив случайностей. Дальше начинается знакомый кошмар: никто не знает, что по-настоящему общее, а что исторически оказалось рядом.

Чтобы этого не произошло, важно довольно рано развести слои. Есть UI-примитивы и дизайн-системные элементы. Они должны быть максимально независимы от бизнес-контекста. И есть продуктовые сборки — карточки, панели, блоки, summary-виджеты, таблицы и прочие вещи, которые принадлежат конкретной области приложения. Они могут быть переиспользуемыми, но это не делает их частью дизайн-системы автоматически.

Когда эта граница не проведена, приложение стареет особенно неприятно: изменения в UI-слое начинают случайно влиять на продуктовую логику, а продуктовые особенности начинают заражать якобы общий слой. Отсюда и желание “переписать архитектуру нормально”.

Долгосрочно выигрывает не самый гибкий код, а самый предсказуемый

В React-мире очень легко полюбить гибкость как ценность саму по себе. Компоненты становятся configurable, хуки — универсальными, слои — максимально абстрактными “на будущее”. Кажется, будто это и есть зрелость. На практике же через год чаще выигрывает не код, который умеет все, а код, про который всем понятно, как он должен использоваться.

Предсказуемость здесь важнее элегантности. У компонента должен быть ясный диапазон вариантов. У модуля — понятная ответственность. У состояния — конкретная область жизни. У API-слоя — стабильная модель. У экранов — понятный способ композиции. Как только код начинает соревноваться в гибкости с реальными требованиями продукта, он почти неизбежно проигрывает. Потому что продукт меняется не так, как предполагала абстракция.

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

Нужно проектировать не “идеальную систему”, а удобный рефакторинг

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

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

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

Самый ценный early warning signal — когда изменение перестает быть локальным

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

На такие сигналы нужно реагировать раньше, чем появится мысль о переписывании. Не heroic rewrite, а локальным наведением порядка: выделить границу, пересобрать модуль, упростить store, разнести роли компонентов, вытащить продуктовый сценарий из общего слоя, нормализовать API-модель, сократить monster-hook. Маленькие структурные исправления, сделанные вовремя, почти всегда дешевле, чем будущая тотальная миграция под лозунгом “сделаем нормально”.

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

Преждевременная архитектура опасна не меньше, чем ее отсутствие

Здесь важно не свалиться в другую крайность. Все перечисленное — разделение UI, данных и сценариев, границы модулей, продуктовая нарезка, разведение дизайн-системы — это не бесплатная победа, а сознательный обмен. Вы платите дисциплиной на старте, когда ее меньше всего хочется платить. Ранний проект почти всегда быстрее писать “в одном месте”, и команда, которая на первой неделе начинает раскладывать состояние по областям ответственности и проводить границы между слоями, действительно движется медленнее той, что просто лепит экраны. Эту цену нужно проговаривать честно, а не делать вид, что зрелая структура достается даром.

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

Итог

Если вы хотите спроектировать React-приложение так, чтобы через год его не хотелось переписать, не пытайтесь заранее изобрести идеальную архитектуру. Куда важнее заложить несколько устойчивых принципов. Строить структуру вокруг будущих изменений, а не вокруг красивой картинки стартового состояния. Разделять UI, данные и сценарии. Держать состояние в минимально необходимой области ответственности. Не обобщать слишком рано. Не превращать страницы в центры всей вселенной. Делать API-слой скучным, а hooks — понятными. Организовывать код по продуктовым областям, а не только по техническим категориям. Разводить дизайн-системный слой и продуктовые сборки. И ценить предсказуемость выше гибкости ради гибкости.

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

Если сформулировать главный вывод совсем прямо, то он будет таким: хорошая архитектура — это не та, в которой ничего не придется менять, а та, в которой любое изменение остается локальным; React-проект хорошо стареет не тогда, когда в нем все сразу идеально, а тогда, когда его границы, состояние и сценарии устроены так, что систему можно переразбирать по частям, не теряя формы. Когда это условие соблюдается, через год проект может быть сложнее, больше и взрослее — но его не хочется сжечь и переписать. Его хочется продолжать развивать. А это и есть самая ценная архитектурная победа.

Автор

Senior Principal JavaScript Developer, Tech Lead. Пишет о React, TypeScript, React Native, архитектуре фронтенда и бэкенда и о том, как AI меняет работу разработчика.

Обновлено

Читайте также