Архитектура большого UI: почему «ещё один общий util.js» — это начало проблем

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

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

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

Сразу зафиксируем главное, чтобы не свалиться в другую крайность. Дело не в том, что вспомогательные функции — это зло, и не в том, что повторно используемый код не нужен. Наоборот, хороший фронтенд невозможен без выделения общих кусков логики. Проблема не в наличии утилит, а в том, что общийutil.js слишком часто становится местом, где архитектура перестаёт отвечать на вопрос «к какой области системы относится этот код?» и начинает отвечать только «куда бы это временно положить, чтобы не мешалось». А временные решения, как известно, удивительно хорошо умеют становиться постоянными.

В маленьком приложении масштаб этой проблемы неочевиден. Несколько компонентов, пара преобразований данных, форматирование дат, обрезка строк, какая-нибудь сортировка или фильтрация — всё это ещё можно пережить даже в одном файле. Именно так обычно и начинается. Но большой UI живёт по другим законам. В нём уже есть несколько экранов, разные доменные области, асинхронные данные, формы, состояние интерфейса, разные пользовательские сценарии и как минимум несколько разработчиков. В таком контексте каждый новый кусок кода, положенный в «общий util», не просто меняет размер файла. Он размывает границы ответственности проекта.

И вот это — настоящий тезис, который часто недооценивают. Архитектурная проблема util.js не в длине файла; длина — лишь симптом. Проблема в том, что файл с таким названием поощряет безответственное размещение логики. В него попадает всё, что «вроде бы может пригодиться ещё где-то», всё, что «не хочется держать рядом с компонентом», всё, что «не похоже на полноценный модуль». В итоге проект теряет важнейшее качество зрелой архитектуры — способность объяснить, где живёт знание о конкретной части системы.

Проблема не в длине файла, а в том, что слово «утилита» отменяет мысль

Хорошая архитектура большого UI строится вокруг смысловых областей. Есть логика пользователей, логика фильтрации, логика отображения каталога, логика работы с формой, логика форматирования конкретных сущностей, логика роутинга, логика авторизации. Не обязательно по одному модулю на каждое слово, но принцип именно такой: код должен тяготеть к той области системы, чьё поведение он выражает. Аutil.js ломает этот принцип, потому что даёт слишком лёгкий путь в сторону: не нужно решать, к чему относится функция, достаточно признать её «утилитой» — и вопрос вроде бы закрыт.

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

Вот здесь и начинается медленное архитектурное разрушение. Когда специфичная логика оказывается в «общем» месте, проект начинает врать сам себе. По названию файла кажется, будто там живут нейтральные помощники. По факту там уже содержатся куски реальной бизнес- или интерфейсной логики. Другой разработчик открывает файл, видит знакомый паттерн и кладёт туда ещё одну похожую функцию. Потом ещё одну. Импорты из util.js расползаются по приложению как паутина, и чем больше мест его используют, тем страшнее в нём что-либо менять. Так утилитарный файл превращается в серую зону, от которой зависит слишком многое, но у которой при этом нет ясного смыслового центра.

Интерфейсная логика почти никогда не бывает по-настоящему «общей»

В больших UI-системах это особенно опасно, потому что интерфейсная логика крайне редко бывает «общей» в наивном смысле слова. Даже форматирование текста, дат или полей часто зависит от контекста экрана, локали, состояния формы, типа пользователя или модели данных. Даже простая фильтрация может знать о специальных значениях, появившихся в конкретном разделе. Даже «универсальный» mapper нередко опирается на форму сущности, которая используется только в одном продукте. Когда такие вещи лежат вutil.js, иллюзия универсальности мешает вовремя заметить их настоящую природу.

Есть и прямое следствие — ухудшение навигации по проекту. В хорошо организованной кодовой базе разработчик задаёт вопрос в предметных терминах. Где живёт логика отображения списка заказов? Где лежат преобразования пользователя? Где код фильтров поиска? Где функции работы с календарным диапазоном для отчётов? Когда проект устроен по смысловым областям, ответы предсказуемы. Но если значительная часть мелкой и средней логики уходит в общие файлы помощников, навигация слабеет. Разработчик уже не идёт к нужному модулю по смыслу, а вынужден вспоминать: может, это в util.js, а может, вhelpers.js, а может, в одном из двух common-файлов, появившихся исторически.

Это, кстати, один из самых надёжных признаков архитектурной деградации: когда найти код проще через глобальный поиск по строке, чем через понимание структуры проекта. Поиск — прекрасный инструмент, но он не должен заменять архитектуру. Если без него нельзя догадаться, где живёт логика, значит, кодовая база перестала быть самопоясняющейся. Общие util-файлы ускоряют именно такой распад, потому что предлагают слишком удобную чёрную дыру для разнородных решений.

В команде безликое имя файла превращается в дорогое скрытое знание

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

Так рождается ещё одна беда — ложное переиспользование. В большом UI повторное использование кода само по себе не является абсолютным благом. Иногда лучше иметь две небольшие похожие функции в разных доменных модулях, чем одну псевдоуниверсальную функцию в util.js, обросшую условиями, флагами и скрытыми допущениями. Но общие утилитарные файлы психологически подталкивают делать наоборот. Раз код уже вынесен «в общее», значит, его как будто нужно использовать снова и снова. В результате функция начинает обслуживать сценарии, для которых не была спроектирована, и постепенно превращается в комбайн с размытым контрактом.

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

util.js — это обходной путь мимо компонентных и доменных границ

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

Беда ещё и в том, что утилитарные файлы быстро начинают смешивать разные уровни абстракции. В одномutil.js соседствуют строковые помощники, функции для работы с массивами, преобразование ответа API, логика построения подписи для конкретного виджета, вычисление доступных действий в интерфейсе и случайная проверка флагов. Рядом оказываются и почти универсальные операции, и вещи, завязанные на конкретные сущности продукта. Такое соседство разрушает важное ощущение архитектурного масштаба: разработчик больше не видит разницы между инфраструктурным помощником и кусочком продуктовой логики. Если всё выглядит как «просто хелперы», значит, и думать о границах вроде бы необязательно.

Нельзя не сказать и про тестирование, потому что здесь легко обмануться. Формально функции вutil.js удобно тестировать: они маленькие, чистые, принимают аргументы и возвращают результат. На первых порах кажется, будто общий util-файл — это хорошо тестируемый слой проекта. Но тестируемость отдельных функций не равна хорошей архитектуре. Да, можно покрыть тестами двадцать функций в одном помощнике. Но если они принадлежат разным доменным зонам, завязаны на разные соглашения и живут в общем файле без чётких границ, тесты не спасут проект от путаницы — они лишь закрепят текущее положение дел. Более того, чем сильнее код из util.js расползается по проекту, тем больше тесты работают не как средство уверенного развития, а как цемент для случайно сложившейся архитектуры.

Скрытые цепочки зависимостей превращают мелкий код в хрупкую систему

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

Важно не перепутать причину и форму. Проблема не решается простым переименованиемutil.js в utils, shared или helpers. Это одна и та же архитектурная идея под разными масками. Если файл или папка по-прежнему означает «место, куда складывают все неясно классифицированные мелкие куски логики», ничего принципиально не меняется. Иногда становится даже хуже, потому что папка создаёт иллюзию порядка: функций стало больше, но они теперь вроде бы разложены по нескольким общим каталогам. На деле это всё та же серая зона, просто растянутая по структуре проекта.

Лекарство — спрашивать, к какой области относится код, а не «куда его положить»

Приземлим до конкретики. Прежде всего стоит заставить себя отвечать на неудобный, но чрезвычайно полезный вопрос: к какой области системы относится этот код на самом деле? Если функция преобразует пользователя для отображения, ей место рядом с user-domain или модулем представления пользователя, а не в абстрактном util-файле. Если функция вычисляет видимые элементы списка на основе фильтров, возможно, это селектор или часть логики конкретного feature-модуля. Если функция форматирует сумму в денежном виде, она, вероятно, относится к модулю форматирования или области локализации, а не к общей свалке. Первый шаг — перестать прятать доменную принадлежность под нейтральным названием.

Второй принцип — различать действительно общие низкоуровневые помощники и прикладную логику. Универсальные операции над массивами, объектами, строками или датами имеют право на существование в отдельном слое, если они действительно нейтральны, малы и не знают ничего о продуктовой модели. Но этот слой должен быть очень строгим по составу. Попасть туда должно быть трудно. Малейший намёк на предметное знание — уже повод искать другой дом для кода. Иначе низкоуровневый слой немедленно превращается в новыйutil.js, только с более приличным названием.

Третий принцип звучит почти как ересь для тех, кто привык бороться с любым повтором: не бойтесь локального дублирования там, где оно честнее ложной общности. В большом UI важнее ясные границы, чем преждевременная централизация. Если две похожие функции живут в разных feature-модулях и обслуживают разные доменные случаи, иногда лучше сохранить это различие, чем вытаскивать их в общий helper ради формальной «сухости» кода. Настоящее переиспользование рождается из устойчивого общего смысла, а не из поверхностного сходства нескольких строк.

Каждую функцию в util.js стоит судить как долг, а появление нового — как событие на review

Здесь важно проговорить цену подхода, иначе он превратится в очередную догму. Регулярный пересмотр уже существующих общих утилит полезен, но это работа, а не разовая чистка. Если util.js уже есть, его не обязательно немедленно сжигать в ритуальном огне. Стоит начать смотреть на него не как на данность, а как на список долгов. Каждая функция внутри должна отвечать на вопросы: действительно ли она общая? где её естественный дом? кто ею пользуется? знает ли она о предметной модели? не пора ли ей стать частью более конкретного модуля? Такой разбор почти всегда вскрывает удивительные вещи: половина «хелперов» давно принадлежит разным зонам приложения и просто никогда не была возвращена домой.

В больших командах решает не идеальная файловая структура, а соглашение на уровне культуры разработки. Появление нового общего util-файла стоит трактовать как событие, требующее обоснования, а не как умолчание. На code review полезно спрашивать не только «работает ли эта функция», но и «почему она лежит именно здесь». Полезно поощрять размещение логики рядом с доменом или feature-областью, если это делает код понятнее, и не награждать разработчика скрытым ощущением аккуратности за то, что он вынес всё «в helpers», если при этом проект потерял смысловую структуру. Архитектурная дисциплина часто начинается именно с таких привычек обсуждения — и да, она стоит времени, которого в спринте всегда не хватает.

И ещё одно уточнение, чтобы не звучать как борьба за эстетику. Война с культом util.js — не война за красивую структуру папок. Это борьба за устойчивость изменений. Чем яснее у кода дом, тем легче его менять без страха задеть случайные части системы. Чем ближе логика к своей предметной области, тем проще понять её контракт и влияние. Чем меньше серых зон общего назначения, тем ниже риск, что локальная правка породит неожиданный каскад. Для большого UI это критично, потому что основная стоимость проекта почти всегда не в первой реализации, а в долгой жизни, поддержке и постоянных изменениях.

Итог

«Ещё один общий util.js» — не техническая мелочь и не вопрос вкуса. Это не плохое имя файла, а начало привычки откладывать архитектурные решения. Вместо ответа на вопрос, к чему относится логика, команда выбирает временный нейтральный контейнер. Вместо укрепления доменных границ создаёт общий слой без лица. Вместо проектирования модульности покупает краткосрочное удобство ценой будущей путаницы. В маленьком масштабе это почти незаметно. В большом — становится одной из причин, по которым интерфейс перестаёт быть системой и превращается в накопление случайных решений.

Самый здоровый вывод здесь, пожалуй, такой: общая утилита — это не преступление, но подозрительная привилегия. Её нужно заслужить реальной общностью, а не выдавать по умолчанию любой функции, которую лень классифицировать. Большой UI выигрывает не от того, что в нём меньше файлов, а от того, что у логики есть понятные границы и дома. Фронтенд давно вышел из эпохи, когда несколько helper-функций могли безнаказанно жить на обочине проекта: интерфейсы стали слишком сложными, долгоживущими и командными, чтобы серые зоны проходили без последствий.

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

Автор

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

Обновлено

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