…крайне болезненно

Привет, Хабр. Меня зовут Серафим Недошивин, я 18-летний разработчик на Go, PHP и, видимо, TS. В предыдущей статье я делился опытом создания мультитенатной ERP-подобной системы для малого бизнеса на Go+chi+pgx. В прошлый раз я акцентировал внимание читателя на 10 основных архитектурных проблемах, которые вам, вероятнее всего, придётся решить при создании подобной системы (включая изоляцию данных организаций, связанность модулей и доступы).

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

Сделаю поправку на то, что очевидно: объём кода не свидетельствует о его чистоте и виртуозном ведении (опытные читатели скорее установят обратную зависимость).

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

GitHub проекта | dev-стенд

Стек и структура

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

Думаю, практически каждый слышал о существовании Next.js и тем более TypeScript, которые в связке представляют собой некое подобие хирургического скальпеля, тонкими слоями нарезающего ваш фронтенд на типизированные и производительные JS-чанки (first load фронта на 130+ страниц занял 102 КБ).

Помимо всего прочего, App Router, поставляющийся Next, просто потрясающе ложится на REST-ful методологию вашего серверного API, где каждая страница может практически полностью соответствовать вашей структуре бэкенда. Динамические параметры вида [companyId] прямо в структуре директорий вашего фронтенда, от которых любой бэкендер испытает структурный оргазм, подобный оргазму от грамотной организации internal/директории бэкенда.

Но лишь на фреймворке и типизации фронтенд не заканчивается. Мой конкретный набор выглядит так, из общей массы которого я выделю дополнительно:

SCSS — в первую очередь из-за наличия миксинов (mixin);
React Query — не хотел возиться со сложным стейт-менеджером, удобный и простой кэш.

Немного про app и apps

Я насмотрелся проектов с использованием TS, авторы которых накидывают типы, хуки и контексты в одну директорию, смешивая всё это дело с представлением. Во мне всё ещё осталось наследие PHP, в особенности Laravel, кричащего вам, что так делать не стоит.

Именно поэтому подход с разделением проекта на:

app/ — представление из page, layout и всех поддиректорий поверх App Router;
apps/ — отдельно хуки, типы, контексты, разделённые по поддиректориям в соответствии с предметной областью —

я нахожу наиболее разумным.

Про наименование файлов

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

А теперь, с позволения читателя, нырнём в мой океан боли.

Дублирование типов | Разбухание фронтенда

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

Мы имеем дело с ERP-подобной системой, в рамках бэкенда которой существуют десятки моделей.

Что сделал бы умный человек?

взял бы tygorgen и гонял типы через zod на фронтенд или вовсе генерировал из спецификации OpenAPI.

Что сделал я?

решил, что можно и немного пописать руками.

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

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

Контексты | Загадка ререндеров

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

Механизм стейт-менеджера можно имитировать с помощью контекстов и react-query (не стейт-менеджер, а скорее просто кэш) — такой подход и используется в Kroncl.

Если определённая часть приложения использует статичные данные организации (например, наименование, изображение, текущий тарифный план), мы просто оборачиваем layout пространства организации в провайдер, в который помещаем логику добычи данных из API и сохранения в кэш.

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

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

Ререндеры терпимы, но оказывают сильное влияние на восприятие вашего сервиса как слегка подлагивающего. С чем я на данный момент смирился.

Пользовательская документация | Становимся техписом

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

Логичнее всего мне показалось организовать доку в основном репозитории, поддиректория app/docs. Существует множество готовых решений, организующих доку хоть в качестве отдельного репозитория… но это не наш вариант. Статьи редактируются часто, функционал ещё чаще — логично объединить всё это в одном репозитории.

Для глав документации использовался формат mdx, который по неведомой мне причине не захотел вставать на стандартный сборщик Next под названием Turbopack, из-за чего пришлось мигрировать на Webpack.

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

Визуализация RBAC | usePermission

В отдельной статье, посвящённой системе доступов к организациям в рамках Kroncl, я затрагивал аспект реализации определения доступа на уровне кнопок/страниц с помощью хука usePermission.

Но на деле система далеко не идеальна, и за всё время её реализации я был близок несколько раз покончить с этим всем традиционным способом фронтенд-разработчиков — харакири удалением репозитория.

В чём же дело? В синхронизации кодов разрешений конкретной организации и аккаунта в ней с бэкендом. Сводя количество ненужного читателю доменного контекста до минимума:

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

На основании двух таких массивов реализована система определения доступности действия, позволяющая скрывать/показывать конкретные действия на клиенте с точностью до кнопок в зависимости от прав пользователя.

Вся боль здесь сконцентрирована не в сути системы, а в количестве функционала, которое нужно покрыть таким хуком usePermission. На момент реализации этой системы уже было завершено 4/5 модулей, а это означает более 50 страниц, в каждой из которых десятки кнопок и карточек объектов. В начале каждой такой страницы было необходимо вызвать хук usePermission (пусть даже одной строкой), а затем показать/скрыть объект/действие в зависимости от результата проверки доступа.

Желание вскрыть вены в таких случаях граничит с критическим. Тем не менее дело было сделано, а читателю я могу лишь посоветовать закладывать подобную фундаментальную логику, как определение доступов, до реализации основного функционала (очевидно, но не для таких голубцов, как я).

А что по размерам?

Все любят цифры. Я тоже люблю. Next отлично справляется с оптимизацией: first load каждой страницы (коих 130), включая документацию, динамические страницы (модули каждой организации) и лендинг, держится в диапазоне 102–261 КБ при размере страниц от 100 Б до 9,5 КБ.

Что очевидно, больше всего тянут страницы, использующие Recharts (визуализацию графиков и диаграмм), но при таких размерах оптимизировать их было бы странно.

Мидлвар авторизации (базовая проверка refresh_token) из httpOnly — 34 КБ, что терпимо.

Завершение | Как ощущается?

Отлично ощущается, трансгендерный переход удался. Жалко только… времени потерял. Выглядит зато неплохо.

GitHub проекта | клиент | сервер | dev-стенд

Как ощущаются 70к строк TS для гетеросексуала Go — потратить год жизни в 18