Поскольку структура стандартизирована, проекты становятся более единообразными, что облегчает набор новых участников в команду. * **Устойчивость к изменениям и рефакторингу**
Модуль на одном слое не может использовать другие модули на том же слое или слоях выше.
Это позволяет вам вносить изолированные правки без непредвиденных последствий для остальной части приложения. * **Контролируемое переиспользование логики**
В зависимости от уровня вы можете сделать код либо очень переиспользуемым, либо очень локальным.
Это сохраняет баланс между соблюдением принципа **DRY** и практичностью. * **Ориентация на потребности бизнеса и пользователей**
Приложение разделено на бизнес-домены, и при именовании поощряется использование терминологии бизнеса, чтобы вы могли делать полезную работу в продукте, не вникая полностью во все другие несвязанные части проекта. ## Постепенное внедрение[](#incremental-adoption "Прямая ссылка на этот заголовок") Если у вас есть существующая кодовая база, которую вы хотите перенести на FSD, мы предлагаем следующую стратегию. На нашем собственном опыте миграции она хорошо себя зарекомендовала. 1. Начните постепенно формировать слои App и Shared, чтобы создать фундамент. 2. Раскидайте весь существующий интерфейсный код по виджетам и страницам, даже если у них пока что есть зависимости, нарушающие правила FSD. 3. Постепенно исправляйте нарушения правил на импорты, а по ходу извлекайте сущности и, возможно, фичи. Рекомендуется воздержаться от добавления новых крупных сущностей во время рефакторинга, а также рефакторинга по частям. ## Следующие шаги[](#next-steps "Прямая ссылка на этот заголовок") * **Хотите разобраться в том, как мыслить по-FSD-шному?** Прочтите [Туториал](/documentation/ru/docs/get-started/tutorial.md). * **Предпочитаете учиться на примерах?** У нас их много в разделе [Примеры](/documentation/ru/examples.md). * **Есть вопросы?** Загляните в наш [чат Telegram](https://t.me/feature_sliced) и спросите у сообщества. --- # Туториал ## Часть 1. На бумаге[](#часть-1-на-бумаге "Прямая ссылка на этот заголовок") В этом руководстве мы рассмотрим приложение Real World App, также известное как Conduit. Conduit является упрощённым клоном [Medium](https://medium.com/) — он позволяет вам читать и писать статьи в блогах, а также комментировать статьи других людей.  Это довольно небольшое приложение, поэтому мы не станем сильно усложнять разработку излишней декомпозицией. Вероятнее всего, что всё приложение поместится в три слоя: **App**, **Pages** и **Shared**. Если нет, будем вводить дополнительные слои по ходу. Готовы? ### Начните с перечисления страниц[](#начните-с-перечисления-страниц "Прямая ссылка на этот заголовок") Если мы посмотрим на скриншот выше, мы можем предположить, что по крайней мере, есть следующие страницы: * Домашняя (лента статей) * Войти и зарегистрироваться * Просмотр статей * Редактор статей * Просмотр профилей людей * Редактор профиля (настройки) Каждая из этих страниц станет отдельным *слайсом* на *слое* Pages. Вспомните из обзора, что слайсы — это просто папки внутри слоев, а слои — это просто папки с заранее определенными названиями, например, `pages`. Таким образом, наша папка Pages будет выглядеть так: ``` 📂 pages/ 📁 feed/ (лента) 📁 sign-in/ (войти/зарегистрироваться) 📁 article-read/ (просмотр статей) 📁 article-edit/ (редактор статей) 📁 profile/ (профиль) 📁 settings/ (настройки) ``` Ключевое отличие Feature-Sliced Design от произвольной структуры кода заключается в том, что страницы не могут зависеть друг от друга. То есть одна страница не может импортировать код с другой страницы. Это связано с **правилом импорта для слоёв**: *Модуль (файл) в слайсе может импортировать другие слайсы только в том случае, если они расположены на слоях строго ниже.* В этом случае страница является слайсом, поэтому модули (файлы) внутри этой страницы могут импортировать код только из слоев ниже, а не из других страниц. ### Пристальный взгляд на ленту[](#пристальный-взгляд-на-ленту "Прямая ссылка на этот заголовок")  *Перспектива анонимного посетителя*  *Перспектива авторизованного пользователя* На странице ленты есть три динамических области: 1. Ссылки для логина, показывающие статус авторизации 2. Список тэгов, фильтрующих ленту 3. Одна—две ленты статей, у каждой статьи кнопка лайка Ссылки для логина — часть заголовка, общего для всех страниц, так что пока что отложим их. #### Список тэгов[](#список-тэгов "Прямая ссылка на этот заголовок") Чтобы создать список тэгов, нам нужно получить все доступные тэги, отобразить каждый тэг как чип ([chip](https://m3.material.io/components/chips/overview)) и сохранить выбранные тэги в хранилище на стороне клиента. Эти операции относятся к категориям «взаимодействие с API», «пользовательский интерфейс» и «хранение данных». В Feature-Sliced Design код делится по назначению с помощью *сегментов*. Сегменты — это папки в слайсах, и они могут иметь произвольные названия, описывающие их цель, но некоторые цели настолько распространены, что существует несколько общепринятых названий: * 📂 `api/` для взаимодействия с бэкендом * 📂 `ui/` для кода, отвечающего за отображение и внешний вид * 📂 `model/` для хранения данных и бизнес-логики * 📂 `config/` для фиче-флагов, переменных окружения и других форм конфигурации Мы поместим код, который получает тэги, в `api`, сам компонент тэга в `ui`, а взаимодействие с хранилищем в `model`. #### Статьи[](#статьи "Прямая ссылка на этот заголовок") Следуя той же логике, мы можем разбить ленту статей на те же три сегмента: * 📂 `api/`: получить постраничный список статей с количеством лайков, оставить лайк * 📂 `ui/`: * список вкладок, который может отображать дополнительную вкладку при выборе тэга * отдельная статья * рабочая пагинация * 📂 `model/`: клиентское хранилище загруженных постов и текущей страницы (при необходимости) ### Переиспользование общего кода[](#переиспользование-общего-кода "Прямая ссылка на этот заголовок") Страницы, как правило, очень отличаются по своей цели, но что-то остается одинаковым по всему приложению — например, UI-кит, соответствующий языку дизайна, или соглашение на бэкенде, что все делается через REST API с конкретным методом аутентификации. Поскольку слайсы должны быть изолированными, переиспользование кода происходит за счёт слоя ниже, **Shared**. Shared отличается от других слоев тем, что он содержит сегменты, а не слайсы. Таким образом, слой Shared представляет собой гибрид между слоем и слайсом. Обычно код в Shared не планируется заранее, а извлекается по ходу разработки, потому что только во время разработки становится ясно, какие части кода действительно переиспользуются. Тем не менее, полезно держать в голове, какой код имеет смысл хранить в Shared: * 📂 `ui/` — UI-кит, только внешний вид, без бизнес-логики. Например, кнопки, диалоги, поля форм. * 📂 `api/` — удобные обёртки вокруг запросов на бэкенд (например, обёртка над `fetch()` в случае веба) * 📂 `config/` — обработка переменных окружения * 📂 `i18n/` — конфигурация поддержки разных языков * 📂 `router/` — примитивы и константы маршрутизации Это лишь примеры сегментов в Shared, вы можете опустить любой из них или создать свой собственный. Единственное, что нужно помнить при создании новых сегментов — названия сегментов должны описывать **цель (почему), а не суть (что)**. Такие названия как `components` , `hooks` или `modals` *не стоит* использовать, потому что они описывают, что содержат эти файлы по сути, а не то, с какой целью писался этот код. Как следствие таких названий, команде приходится копаться в таких папках, чтоб найти нужное. Помимо этого, несвязанный код лежит рядом, из-за чего при рефакторинге затрагивается большая часть приложения, что усложняет ревью и тестирование. ### Определите строгий публичный API[](#определите-строгий-публичный-api "Прямая ссылка на этот заголовок") В контексте Feature-Sliced Design термин *публичный API* означает, что слайс или сегмент объявляет, что из него могут импортировать другие модули в проекте. Например, в JavaScript это может быть файл `index.js`, который переэкспортирует объекты из других файлов в слайсе. Это обеспечивает свободу рефакторинга внутри слайса до тех пор, пока контракт с внешним миром (т.е. публичный API) остается неизменным. Для слоя Shared, на котором нет слайсов, обычно удобнее определить публичный API (он же индекс) на уровне сегментов, а не один индекс на весь слой. В таком случае импорты из Shared естественным образом организуются по назначению. Для других слоев, на которых слайсы есть, верно обратное — обычно практичнее определить один индекс на слайс и позволить слайсу самому контролировать набор сегментов внутри, потому что другие слои обычно имеют гораздо меньше экспортов и чаще рефакторятся. Наши слайсы/сегменты будут выглядеть друг для друга следующим образом: ``` 📂 pages/ 📂 feed/ 📄 index 📂 sign-in/ 📄 index 📂 article-read/ 📄 index 📁 … 📂 shared/ 📂 ui/ 📄 index 📂 api/ 📄 index 📁 … ``` Все, что находится внутри папок типа `pages/feed` или `shared/ui` , известно только этим папкам, и нет никаких гарантий по содержанию этих папок. ### Крупные переиспользуемые блоки интерфейса[](#крупные-переиспользуемые-блоки-интерфейса "Прямая ссылка на этот заголовок") Ранее мы хотели отдельно вернуться к переиспользуемому заголовку приложения. Собирать его заново на каждой странице было бы непрактично, поэтому мы его переиспользуем. У нас уже есть слой Shared для переиспользования кода, однако, в случае крупных блоков интерфейса в Shared есть нюанс — слой Shared не должен знать о слоях выше. Между слоями Shared и Pages есть три других слоя: Entities, Features и Widgets. В других проектах на этих слоях может лежать что-то, что хочется использовать в крупном переиспользуемом блоке, и тогда мы не сможем поместить этот блок в Shared, потому что тогда ему придется импортировать со слоёв выше, а это запрещено. Тут приходит на помощь слой Widgets. Он расположен выше Shared, Entities и Features, поэтому он может использовать их всех. В нашем случае заголовок очень простой — это статический логотип и навигация верхнего уровня. Навигация должна спросить у API, авторизован ли сейчас пользователь, но это может быть решено простым импортом из сегмента `api`. Поэтому мы оставим наш заголовок в Shared. ### Пристальный взгляд на страницу с формой[](#пристальный-взгляд-на-страницу-с-формой "Прямая ссылка на этот заголовок") Давайте также рассмотрим страницу, на которой можно не только читать, но и редактировать. К примеру, редактор статей:  Она выглядит тривиально, но содержит несколько аспектов разработки приложений, которые мы еще не исследовали — валидацию форм, состояние ошибки и постоянное хранение данных. Для создания этой страницы нам нужно несколько полей и кнопок из Shared, которые мы соберём в форму в сегменте `ui` этой страницы. Затем, в сегменте `api` мы определим изменяющий запрос, чтобы создать статью на бэкенде. Чтобы проверить запрос перед отправкой, нам нужна схема валидации, и хорошим местом для нее является сегмент `model` , поскольку это модель данных. Там же мы сгенерируем сообщение об ошибке, а отобразим его с помощью ещё одного компонента в сегменте `ui`. Чтобы улучшить пользовательский опыт, мы также можем сохранять введённые данные постоянно, чтобы предотвратить случайную потерю при закрытии браузера. Это тоже подходит под сегмент `model`. ### Итоги[](#итоги "Прямая ссылка на этот заголовок") Мы разобрали несколько страниц и пришли к базовой структуре нашего приложения: 1. Слой Shared 1. `ui` будет содержать наш переиспользуемый UI-кит 2. `api` будет содержать наши примитивы для взаимодействия с бэкендом 3. Остальное разложим по ходу написания кода 2. Слой Pages — для каждой страницы отдельный слайс 1. `ui` будет содержать саму страницу и составляющие её блоки 2. `api` будет содержать более специализированные функции получения данных, использующие `shared/api` 3. `model` может содержать клиентское хранилище данных, которые мы будем отображать Давайте создадим это приложение! ## Часть 2. В коде[](#часть-2-в-коде "Прямая ссылка на этот заголовок") Теперь, когда у нас есть план, давайте воплотим его в жизнь. Мы будем использовать React и [Remix](https://remix.run/). Для этого проекта уже есть готовый шаблон, cклонируйте его с GitHub, чтобы начать работу:
conduit
A place to share your knowledge.
{article.author.username}
{new Date(article.createdAt).toLocaleDateString(undefined, {
dateStyle: "long",
})}
{article.title}
{article.description}
Read more...-
{article.tagList.map((tag) => (
- {tag} ))}
conduit
A place to share your knowledge.
{articles.articles.map((article) => (
conduit
A place to share your knowledge.
{articles.articles.map((article) => (
Popular Tags
conduit
A place to share your knowledge.
{articles.articles.map((article) => (
Popular Tags
Sign up
Have an account?
{registerData?.error && (-
{registerData.error.errors.body.map((error) => (
- {error} ))}
Sign in
Need an account?
{signInData?.error && (-
{signInData.error.errors.body.map((error) => (
- {error} ))}
Popular Tags
conduit
A place to share your knowledge.
{article.author.username}
{new Date(article.createdAt).toLocaleDateString(undefined, {
dateStyle: "long",
})}
{article.title}
{article.description}
Read more...-
{article.tagList.map((tag) => (
- {tag} ))}
{article.article.title}
{article.article.body}
-
{article.article.tagList.map((tag) => (
- {tag} ))}
{currentUser !== null ? (
) : (
)}
{comments.comments.map((comment) => (
{comment.author.username}
{comment.createdAt}
{comment.author.username === currentUser?.username && (
)}
))}
);
}
```
А вместе с этим и наша читалка статей! Кнопки "Подписаться на автора", "Мне нравится" и "Оставить комментарий" теперь должны работать как положено.
Читалка статей с рабочими кнопками подписки и лайка
### Редактор статей[](#редактор-статей "Прямая ссылка на этот заголовок")
Это последняя страница, которую мы рассмотрим в этом руководстве, и самая интересная часть здесь — это то, как мы будем проверять данные формы.
Сама страница, `article-edit/ui/ArticleEditPage.tsx`, будет довольно простой, дополнительная логика будет скрыта в двух других компонентах:
pages/article-edit/ui/ArticleEditPage.tsx
```
import { Form, useLoaderData } from "@remix-run/react";
import type { loader } from "../api/loader";
import { TagsInput } from "./TagsInput";
import { FormErrors } from "./FormErrors";
export function ArticleEditPage() {
const article = useLoaderDataSign in or Sign up to add comments on this article.
{comment.body}
-
{actionData.errors.map((error) => (
- {error} ))}
{tagListState.map((tag) => (
[" ", "Enter"].includes(e.key) && removeTag(tag)
}
onClick={() => removeTag(tag)}
>{" "}
{tag}
))}
);
}
```
Теперь перейдем к API-части. Загрузчик должен посмотреть на URL, и если в нем есть ссылка на статью, это означает, что мы редактируем существующую статью, и ее данные должны быть загружены. В противном случае ничего не возвращается. Давайте создадим этот загрузчик:
pages/article-edit/api/loader.ts
```
import { json, type LoaderFunctionArgs } from "@remix-run/node";
import type { FetchResponse } from "openapi-fetch";
import { GET, requireUser } from "shared/api";
async function throwAnyErrorsЭто самое простое решение, но оно быстро становится неудобным, и если у вас нет строгой типизации, об этом легко забыть. Это решение также несовместимо с паттерном middleware для API-клиента в Shared. 2. **Открыть доступ к токену для всего приложения через контекст или глобальное хранилище вроде `localStorage`**
Ключ, по которому можно будет получить токен, будет храниться в `shared/api`, чтобы API-клиент мог его использовать. Реактивное хранилище токена будет экспортировано из сущности User, а провайдер контекста (если требуется) будет настроен на слое App. Это дает больше свободы для дизайна API-клиента, но такой подход создаёт неявную зависимость 3. **Вставлять токен в API-клиент каждый раз, когда токен меняется**
Если ваше хранилище реактивное, то можно подписаться на изменения и обновлять токен в API-клиенте каждый раз, когда хранилище в сущности User меняется. Это похоже на прошлое решение тем, что они оба создают неявную зависимость, но это решение более императивное ("push"), тогда как предыдущее — более декларативное ("pull"). Решив проблему доступности токена, хранящегося в модели сущности User, вы сможете описать дополнительную бизнес-логику, связанную с управлением токенами. Например, сегмент `model` может содержать логику, которая делает токен недействительным через определенный период времени или обновляет токен по истечении срока его действия. Чтобы совершать запросы на бэкенд для выполнения этих задач, используйте сегмент `api` сущности User или `shared/api`. ### В Pages/Widgets (не рекомендуется)[](#в-pageswidgets-не-рекомендуется "Прямая ссылка на этот заголовок") Не рекомендуется хранить состояние, актуальное для всего приложения, как например токен доступа, в страницах или виджетах. Не стоит размещать хранилище токенов в сегменте `model` на странице логина. Вместо этого выберите одно из первых двух решений: Shared или Entities. ## Логаут и аннулирование токена[](#логаут-и-аннулирование-токена "Прямая ссылка на этот заголовок") Обычно в приложениях не делают целую отдельную страницу для логаута, но функционал логаута, тем не менее, очень важен. В этот функционал входит авторизованный запрос на бэкенд и обновление хранилища токенов. Если вы храните все ваши запросы в `shared/api`, оставьте там функцию для запроса на логаут, рядом с функцией для логина. Если нет, разместите функцию-запрос на логаут рядом с кнопкой, которая её вызывает. Например, если у вас есть виджет хэдера, который есть на каждой странице и содержит ссылку для логаута, поместите этот запрос в сегмент `api` этого виджета. Обновление хранилища токенов также должно будет запускаться с места кнопки логаута, как, например, виджет заголовка. Вы можете объединить запрос и обновление хранилища в сегменте `model` этого виджета. ### Автоматический логаут[](#автоматический-логаут "Прямая ссылка на этот заголовок") Не забудьте предусмотреть ситуации сбоя запроса на логаут или сбоя запроса на обновление токена. В обоих случаях вам следует очистить хранилище токенов. Если вы храните свой токен в Entities, этот код можно поместить в сегмент `model`, поскольку это чистая бизнес-логика. Если вы храните токен в Shared, размещение этой логики в `shared/api` может раздуть сегмент и размыть его предназначение. Если вы замечаете, что ваш сегмент `api` содержит две несвязанные вещи, рассмотрите возможность выделения логики управления токенами в другой сегмент, например, `shared/auth`. --- # Автокомплит WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/170) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > Про декомпозицию по слоям ## См. также[](#see-also "Прямая ссылка на этот заголовок") * [(Дискуссия) Про применение методологии для селекта с подгружаемыми справочниками](https://github.com/feature-sliced/documentation/discussions/65#discussioncomment-480807) --- # Browser API WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/197) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > Про работу с Browser API: localStorage, audioApi, bluetoothAPI и т.п. > > Подробнее про идею можно спросить [@alex\_novi](https://t.me/alex_novich) --- # CMS WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/172) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* ## Фичи бывают разные[](#features-may-be-different "Прямая ссылка на этот заголовок") В некоторых проектах весь функционал сосредоточен в данных с сервера >
*🍰 Stay tuned!* > Errors, Alerts, Notifications, ... --- # i18n WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/171) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* ## Куда положить? Как с этим работать?[](#where-to-place-it-how-to-work-with-this "Прямая ссылка на этот заголовок") *
*🍰 Stay tuned!* > Про способы инициализировать метрики в приложении --- # Монорепозитории WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/221) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > Про применимость для монорепозиториев, про bff, про микроаппы ## См. также[](#see-also "Прямая ссылка на этот заголовок") * [(Дискуссия) Про монорепозитории и подключаемые модули-пакеты](https://github.com/feature-sliced/documentation/discussions/50) * [(Тред) Про применение для монорепозитория](https://t.me/feature_sliced/2412) --- # Лейауты страниц Это руководство рассматривает абстракцию *лейаута страницы* — когда несколько страниц имеют одинаковую структуру, отличаясь только основным содержимым. к сведению Вашего вопроса нет в этом руководстве? Напишите свой вопрос, оставив отзыв к этой статье (синяя кнопка справа), и мы рассмотрим возможность расширения этого руководства! ## Простой лейаут[](#простой-лейаут "Прямая ссылка на этот заголовок") Самый простой лейаут можно увидеть прямо на этой странице. Он имеет хэдер с навигацией по сайту, два сайдбара и футер с внешними ссылками. Здесь нет сложной бизнес-логики, и единственные динамические части — это сайдбары и переключатели справа в хэдере. Такой лейаут можно разместить целиком в `shared/ui` или в `app/layouts`, с заполнением контента сайдбаров через пропы: shared/ui/layout/Layout.tsx ``` import { Link, Outlet } from "react-router-dom"; import { useThemeSwitcher } from "./useThemeSwitcher"; export function Layout({ siblingPages, headings }) { const [theme, toggleTheme] = useThemeSwitcher(); return (
Это отлично подходит для роутеров, поддерживающих вложенность, потому что вы можете группировать определенные маршруты и применять нужный лейаут только к ним. 2. **Просто скопируйте его**
Желание абстрагировать код часто переоценено. Это особенно верно для лейаутов, потому что они редко меняются. В какой-то момент, если одна из этих страниц потребует изменений, вы можете просто внести изменения, не затрагивая другие страницы. Если вы беспокоитесь, что кто-то может забыть обновить другие страницы, всегда можно оставить комментарий, описывающий отношения между страницами. Если ни один из вышеперечисленных вариантов не подходит, есть два решения для включения виджета в лейаут: 1. **Используйте render props или слоты**
Большинство фреймворков позволяют передавать часть UI внешне. В React это называется [render props](https://www.patterns.dev/react/render-props-pattern/), в Vue — [слоты](https://ru.vuejs.org/guide/components/slots). 2. **Переместите лейаут на уровень App**
Вы также можете хранить свой лейаут на уровне App, например, в `app/layouts`, и комбинировать любые виджеты, которые вам нужны. ## Дополнительные материалы[](#дополнительные-материалы "Прямая ссылка на этот заголовок") * Пример создания лейаута с аутентификацией с помощью React и Remix (аналогичен React Router) можно найти в [туториале](/documentation/ru/docs/get-started/tutorial.md). --- # Desktop/Touch платформы WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/198) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > Про применение методологии для desktop/touch --- # SSR WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/173) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > Про реализацию SSR с применением методологии --- # Темизация WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/207) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* ## Куда положить работу с темой и палитрой?[](#where-should-i-put-my-work-with-the-theme-and-palette "Прямая ссылка на этот заголовок") >
*🍰 Stay tuned!* > Figma, brand uikit, templates, адаптируемость к брендам ## См. также[](#see-also "Прямая ссылка на этот заголовок") * [(Тред) Про применение для white-labels (брендированных) проектов](https://t.me/feature_sliced/1543) * [(Презентация) Про white-labels приложения и дизайн](https://yadi.sk/i/5IdhzsWrpO3v4Q) --- # Кросс-импорты WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/220) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* > Кросс-импорты появляются тогда, когда слой/абстракция начинает брать слишком много ответственности, чем должна. Именно поэтому методология выделяет новые слои, которые позволяют расцепить эти кросс-импорты ## См. также[](#see-also "Прямая ссылка на этот заголовок") * [(Тред) Про предполагаемую неизбежность кросс-импортов](https://t.me/feature_sliced/4515) * [(Тред) Про резолвинг кросс-импортов в сущностях](https://t.me/feature_sliced/3678) * [(Тред) Про кросс-импорты и ответственность](https://t.me/feature_sliced/3287) * [(Тред) Про импорты между сегментами](https://t.me/feature_sliced/4021) * [(Тред) Про кросс-импорты внутри shared](https://t.me/feature_sliced/3618) --- # Десегментация WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/148) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* ## Ситуация[](#situation "Прямая ссылка на этот заголовок") Очень часто на проектах встречается ситуация, когда модули, относящиеся к конкретному домену из предметной области, излишне десегментированы и раскиданы по проекту ``` ├── components/ | ├── DeliveryCard | ├── DeliveryChoice | ├── RegionSelect | ├── UserAvatar ├── actions/ | ├── delivery.js | ├── region.js | ├── user.js ├── epics/ | ├── delivery.js | ├── region.js | ├── user.js ├── constants/ | ├── delivery.js | ├── region.js | ├── user.js ├── helpers/ | ├── delivery.js | ├── region.js | ├── user.js ├── entities/ | ├── delivery/ | | ├── getters.js | | ├── selectors.js | ├── region/ | ├── user/ ``` ## Проблема[](#problem "Прямая ссылка на этот заголовок") Проблема проявляется как минимум в нарушении принципа **High Cohesion** и излишнего растягивания **оси изменений** ## Если проигнорировать[](#if-you-ignore-it "Прямая ссылка на этот заголовок") * При необходимости затронуть логику, например, доставки - нам придется держать в голове, что она лежит в нескольких местах и затронуть в коде именно несколько мест - что излишне растягивает нашу **Ось изменений** * Если нам надо изучить логику по пользователю, нам придется пройтись по всему-всему проекту, чтобы изучить в деталях **actions, epics, constants, entities, components** - вместо того, чтобы это лежало в одном месте * Неявные связи и неконтролируемость растущей предметной области * При таком подходе очень часто замыливается глаз и можно не заметить, как мы "создаем константы ради констант", создавая свалку в соответствующей директории проекта ## Решение[](#solution "Прямая ссылка на этот заголовок") Располагать все модули, относящиеся к конкретному домену/юзкейсу - непосредственно рядом Чтобы при изучении конкретного модуля - все его составляющие лежали рядом, а не были раскиданы по проекту > Это также повышает discoverability и явность кодовой базы и связей между модулями ``` - ├── components/ - | ├── DeliveryCard - | ├── DeliveryChoice - | ├── RegionSelect - | ├── UserAvatar - ├── actions/ - | ├── delivery.js - | ├── region.js - | ├── user.js - ├── epics/{...} - ├── constants/{...} - ├── helpers/{...} ├── entities/ | ├── delivery/ + | | ├── ui/ # ~ components/ + | | | ├── card.js + | | | ├── choice.js + | | ├── model/ + | | | ├── actions.js + | | | ├── constants.js + | | | ├── epics.js + | | | ├── getters.js + | | | ├── selectors.js + | | ├── lib/ # ~ helpers | ├── region/ | ├── user/ ``` ## См. также[](#see-also "Прямая ссылка на этот заголовок") * [(Статья) Про Low Coupling и High Cohesion наглядно](https://enterprisecraftsmanship.com/posts/cohesion-coupling-difference/) * [(Статья) Low Coupling и High Cohesion. Закон Деметры](https://medium.com/german-gorelkin/low-coupling-high-cohesion-d36369fb1be9) --- # Роутинг WIP Статья находится в процессе написания Чтобы ускорить ее появление, можно: * 📢 Поделиться обратной связью [в тикете (комментарии/эмодзи-реакция)](https://github.com/feature-sliced/documentation/issues/169) * 💬 Собрать в тикет накопленный по теме [материал из чата](https://t.me/feature_sliced) * ⚒️ Посодействовать [любым другим способом](https://github.com/feature-sliced/documentation/blob/master/CONTRIBUTING.md)
*🍰 Stay tuned!* ## Ситуация[](#situation "Прямая ссылка на этот заголовок") Урлы к страницам хардкодятся в слоях ниже pages entities/post/card ```
Сначала убедите своих коллег в том, что преимущества перевешивают стоимость миграции и стоимость изучения новой архитектуры вместо установленной. Также имейте в виду, что любые изменения в архитектуре незаметны для руководства в моменте. Убедитесь, что они поддерживают переход, прежде чем начинать, и объясните им, как этот переход может быть полезен для проекта. подсказка Если вам нужна помощь в убеждении менеджера проекта в том, что FSD вам полезен, вот несколько идей: 1. Миграция на FSD может происходить постепенно, поэтому она не остановит разработку новых функций 2. Хорошая архитектура может значительно сократить время, которое потребуется новым разработчикам для достижения производительности 3. FSD — это документированная архитектура, поэтому команде не нужно постоянно тратить время на поддержание собственной документации *** Если вы всё-таки приняли решение начать миграцию, то первое, что вам следует сделать, — настроить алиас для `📁 src`. Это будет полезно позже, чтоб ссылаться на папки верхнего уровня. Далее в тексте мы будем считать `@` псевдонимом для `./src`. ## Шаг 1. Разделите код по страницам[](#divide-code-by-pages "Прямая ссылка на этот заголовок") Большинство кастомных архитектур уже имеют разделение по страницам, независимо от размера логики. Если у вас уже есть `📁 pages`, вы можете пропустить этот шаг. Если у вас есть только `📁 routes`, создайте `📁 pages` и попробуйте переместить как можно больше кода компонентов из `📁 routes`. Идеально, если у вас будет маленький файл роута и больший файл страницы. При перемещении кода создайте папку для каждой страницы и добавьте в нее индекс-файл: примечание Пока что ваши страницы могут импортировать друг из друга, это нормально. Позже будет отдельный шаг для устранения этих зависимостей, но сейчас сосредоточьтесь на установлении явного разделения по страницам. Файл роута: src/routes/products.\[id].js ``` export { ProductPage as default } from "@/pages/product" ``` Индекс-файл страницы: src/pages/product/index.js ``` export { ProductPage } from "./ProductPage.jsx" ``` Файл с компонентом страницы: src/pages/product/ProductPage.jsx ``` export function ProductPage(props) { return ; } ``` ## Шаг 2. Отделите все остальное от страниц[](#separate-everything-else-from-pages "Прямая ссылка на этот заголовок") Создайте папку `📁 src/shared` и переместите туда все, что не импортируется из `📁 pages` или `📁 routes`. Создайте папку `📁 src/app` и переместите туда все, что импортирует страницы или роуты, включая сами роуты. Помните, что у слоя Shared нет слайсов, поэтому сегменты могут импортировать друг из друга. В итоге у вас должна получиться структура файлов, похожая на эту: 📁 src * 📁 app * 📁 routes * 📄 products.jsx * 📄 products.\[id].jsx * 📄 App.jsx * 📄 index.js * 📁 pages * 📁 product * 📁 ui * 📄 ProductPage.jsx * 📄 index.js * 📁 catalog * 📁 shared * 📁 actions * 📁 api * 📁 components * 📁 containers * 📁 constants * 📁 i18n * 📁 modules * 📁 helpers * 📁 utils * 📁 reducers * 📁 selectors * 📁 styles ## Шаг 3. Устраните кросс-импорты между страницами[](#tackle-cross-imports-between-pages "Прямая ссылка на этот заголовок") Найдите все случаи, когда одна страница импортирует что-то из другой, и сделайте одно из двух: 1. Скопируйте код, который импортируется, в зависимую страницу, чтобы убрать зависимость 2. Переместите код в соответствующий сегмент в Shared: * если это часть UI-кита, переместите в `📁 shared/ui`; * если это константа конфигурации, переместите в `📁 shared/config`; * если это взаимодействие с бэкендом, переместите в `📁 shared/api`. примечание **Копирование само по себе не является архитектурной проблемой**, на самом деле иногда даже правильнее продублировать что-то, чем абстрагировать в новый переиспользуемый модуль. Дело в том, что иногда общие части страниц начинают расходиться, и в этих случаях вам не нужно, чтобы эти зависимости мешались. Однако существует смысл в принципе DRY ("don't repeat yourself" — "не повторяйтесь"), поэтому убедитесь, что вы не копируете бизнес-логику. В противном случае вам придется держать в голове, что баги нужно исправлять в нескольких местах одновременно. ## Шаг 4. Разберите слой Shared[](#unpack-shared-layer "Прямая ссылка на этот заголовок") На данном этапе у вас может быть много всего в слое Shared, и в целом, следует избегать таких ситуаций. Причина этому в том, что слой Shared может быть зависимостью для любого другого слоя в вашем коде, поэтому внесение изменений в этот код автоматически более чревато непредвиденными последствиями. Найдите все объекты, которые используются только на одной странице, и переместите их в слайс этой страницы. И да, *это относится и к экшнам (actions), редьюсерам (reducers) и селекторам (selectors)*. Нет никакой пользы в группировке всех экшнов вместе, но есть польза в том, чтобы поместить актуальные экшны рядом с их местом использования. В итоге у вас должна получиться структура файлов, похожая на эту: 📁 src * 📁 app (unchanged) * 📁 pages * 📁 product * 📁 actions * 📁 reducers * 📁 selectors * 📁 ui * 📄 Component.jsx * 📄 Container.jsx * 📄 ProductPage.jsx * 📄 index.js * 📁 catalog * 📁 shared (only objects that are reused) * 📁 actions * 📁 api * 📁 components * 📁 containers * 📁 constants * 📁 i18n * 📁 modules * 📁 helpers * 📁 utils * 📁 reducers * 📁 selectors * 📁 styles ## Шаг 5. Распределите код по техническому назначению[](#organize-by-technical-purpose "Прямая ссылка на этот заголовок") В FSD разделение по техническому назначению происходит с помощью *сегментов*. Существует несколько часто встречающихся сегментов: * `ui` — всё, что связано с отображением интерфейса: компоненты UI, форматирование дат, стили и т. д. * `api` — взаимодействие с бэкендом: функции запросов, типы данных, мапперы и т. д. * `model` — модель данных: схемы, интерфейсы, хранилища и бизнес-логика. * `lib` — библиотечный код, который нужен другим модулям на этом слайсе. * `config` — файлы конфигурации и фиче-флаги. Вы можете создавать свои собственные сегменты, если это необходимо. Убедитесь, что не создаете сегменты, которые группируют код по тому, чем он является, например, `components`, `actions`, `types`, `utils`. Вместо этого группируйте код по тому, для чего он предназначен. Перераспределите код ваших страниц по сегментам. У вас уже должен быть сегмент `ui`, теперь пришло время создать другие сегменты, например, `model` для ваших экшнов, редьюсеров и селекторов, или `api` для ваших thunk-ов и мутаций. Также перераспределите слой Shared, чтобы удалить следующие папки: * `📁 components`, `📁 containers` — большинство из их содержимого должно стать `📁 shared/ui`; * `📁 helpers`, `📁 utils` — если остались какие-то повторно используемые хелперы, сгруппируйте их по назначению, например, даты или преобразования типов, и переместите эти группы в `📁 shared/lib`; * `📁 constants` — так же сгруппируйте по назначению и переместите в `📁 shared/config`. ## Шаги по желанию[](#optional-steps "Прямая ссылка на этот заголовок") ### Шаг 6. Создайте сущности/фичи ёмкостью из Redux-слайсов, которые используются на нескольких страницах[](#form-entities-features-from-redux "Прямая ссылка на этот заголовок") Обычно эти переиспользуемые Redux-слайсы будут описывать что-то, что имеет отношение к бизнесу, например, продукты или пользователи, поэтому их можно переместить в слой Entities, одна сущность на одну папку. Если Redux-слайс скорее связан с действием, которое ваши пользователи хотят совершить в вашем приложении, например, комментарии, то его можно переместить в слой Features. Сущности и фичи должны быть независимы друг от друга. Если ваша бизнес-область содержит встроенные связи между сущностями, обратитесь к [руководству по бизнес-сущностям](/documentation/ru/docs/guides/examples/types.md#business-entities-and-their-cross-references) за советом по организации этих связей. API-функции, связанные с этими слайсами, могут остаться в `📁 shared/api`. ### Шаг 7. Проведите рефакторинг modules[](#refactor-your-modules "Прямая ссылка на этот заголовок") Папка `📁 modules` обычно используется для бизнес-логики, поэтому она уже довольно похожа по своей природе на слой Features из FSD. Некоторые модули могут также описывать большие части пользовательского интерфейса, например, шапку приложения. В этом случае их можно переместить в слой Widgets. ### Шаг 8. Сформируйте чистый фундамент UI в `shared/ui`[](#form-clean-ui-foundation "Прямая ссылка на этот заголовок") `📁 shared/ui`, в идеале, должен содержать набор UI-элементов, в которых нет бизнес-логики. Они также должны быть очень переиспользуемыми. Проведите рефакторинг UI-компонентов, которые раньше находились в `📁 components` и `📁 containers`, чтобы отделить бизнес-логику. Переместите эту бизнес-логику в верхние слои. Если она не используется в слишком многих местах, вы даже можете рассмотреть копирование как вариант. ## See also[](#see-also "Прямая ссылка на этот заголовок") * [(Доклад) Ilya Klimov — Крысиные бега бесконечного рефакторинга: как не дать техническому долгу убить мотивацию и продукт](https://youtu.be/aOiJ3k2UvO4) --- # Миграция с v1 ## Зачем v2?[](#why-v2 "Прямая ссылка на этот заголовок") Изначальная концепция **feature-slices** [была заявлена](https://t.me/feature_slices) еще в 2018 году. С тех пор прошло много трансформаций методологии, но при этом **[сохранялись базовые принципы](https://feature-sliced.github.io/featureslices.dev/v1.0.html)**: * Использование *стандартизированной* структуры фронтенд-проектов * Разбиение приложения в первую очередь - согласно *бизнес-логике* * Использование *изолированных фичей*, для предотвращения неявных сайд-эффектов и циклических зависимостей * Использование *Public API* с запретом лезть "во внутренности" модуля При этом, в прежней версии методологии все равно **оставались слабые места**, которые * Где-то приводили к бойлерплейту * Где-то к чрезмерному усложнению кодовой базы и неочевидным правилам между абстракциями * Где-то к неявным архитектурным решениям, что мешало поддержке проекта и онбордингу новых людей Новая версия методологии ([v2](https://github.com/feature-sliced/documentation)) призвана **устранить эти недостатки, сохраняя при этом и имеющиеся достоинства** подхода. С 2018 года [развивалась](https://github.com/kof/feature-driven-architecture/issues) и другая подобная методология - [**feature-driven**](https://github.com/feature-sliced/documentation/tree/rc/feature-driven), о которой заявил впервые [Oleg Isonen](https://github.com/kof). В результате слияния двух подходов, **были улучшены и доработаны существующие практики** - в сторону большей гибкости, понятности и эффективности при применении. > По итогу это повлияло даже на наименование методологии - *"feature-slice**d**"* ## Почему имеет смысл мигрировать проект на v2?[](#why-does-it-make-sense-to-migrate-the-project-to-v2 "Прямая ссылка на этот заголовок") > `WIP:` Текущая версия методологии находится на стадии разработки и некоторые детали *могут измениться* #### 🔍 Более прозрачная и простая архитектура[](#-more-transparent-and-simple-architecture "Прямая ссылка на этот заголовок") Методология (v2) предлагает **более интуитивно понятные и более распространенные среди разработчиков абстракции и способы разделения логики.** Все это крайне положительно влияет на привлечение новых людей, а также изучение текущего состояния проекта, и распределение бизнес-логики приложения. #### 📦 Более гибкая и честная модульность[](#-more-flexible-and-honest-modularity "Прямая ссылка на этот заголовок") Методология (v2) позволяет **распределять логику более гибким способом:** * С возможностью рефакторить с нуля изолированные части * С возможностью опираться на одни и те же абстракции, но без лишних переплетений зависимостей * С более простыми требованиями для расположения нового модуля *(layer => slice => segment)* #### 🚀 Больше спецификации, планов, комьюнити[](#-more-specifications-plans-community "Прямая ссылка на этот заголовок") На данный момент `core-team` ведет активную работу именно над последней (v2) версией методологии А значит именно для нее: * будет больше описанных кейсов / проблем * будет больше гайдов по применению * будет больше реальных примеров * будет в целом больше документации для онбординга новых людей и изучения концепций методологии * будет развиваться в дальнейшем тулкит для соблюдения концепций и конвенций по архитектуре > Само собой, будет поддержка пользователей и по первой версии - но для нас первоочередная все же последняя версия > > В будущем же, при следующих мажорных обновлениях - у вас сохранится доступ и к текущей версии (v2) методологии, **без рисков для ваших команд и проектов** ## Changelog[](#changelog "Прямая ссылка на этот заголовок") ### `BREAKING` Layers[](#breaking-layers "Прямая ссылка на этот заголовок") Теперь методология предполагает явное выделение слоев на верхнем уровне * `/app` > `/processes` > **`/pages`** > **`/features`** > `/entities` > `/shared` * *Т.е. не все теперь трактуется как фичи/страницы* * Такой подход позволяет [явно задать правила для слоев](https://t.me/atomicdesign/18708): * Чем **выше расположен слой** модуля - тем большим **контекстом** он располагает *(иными словами - каждый модуль слоя - может импортировать только модули нижележащих слоев, но не выше)* * Чем **ниже расположен слой** модуля - тем больше **опасности и ответственности**, чтобы внести в него изменения *(потому что, как правило - более переиспользуемыми являются именно нижележащие слои)* ### `BREAKING` Shared[](#breaking-shared "Прямая ссылка на этот заголовок") Инфраструктурные абстракции `/ui`, `/lib`, `/api`, которые раньше лежали в src-корне проекта, теперь обособлены отдельной директорией `/src/shared` * `shared/ui` - Все так же общий uikit приложения (опционален) * *При этом никто не запрещает использовать здесь `Atomic Design` как раньше* * `shared/lib` - Набор вспомогательных библиотек для реализации логики * *По-прежнему - без свалки хелперов* * `shared/api` - Общий энтрипоинт для обращения к API * *Может прописываться и локально в каждой фиче/странице - но не рекомендуется* * Как и раньше - в `shared` не должно быть явной привязки к бизнес-логике * *При необходимости - нужно выносить эту связь на уровень `entities` или еще выше* ### `NEW` Entities, Processes[](#new-entities-processes "Прямая ссылка на этот заголовок") В v2 **добавлены и другие новые абстракции**, для устранения проблем усложнения логики и сильной связности. * `/entities` - слой **бизнес-сущностей**, содержащий в себе слайсы, относящиеся напрямую к бизнес-моделям или синтетическим сущностям, необходимым только на фронтенде * *Примеры: `user`, `i18n`, `order`, `blog`* * `/processes` - слой **бизнес-процессов**, пронизывающих приложение * **Слой опционален**, обычно рекомендуется использовать, когда *логика разрастается и начинает размываться в нескольких страницах* * *Примеры: `payment`, `auth`, `quick-tour`* ### `BREAKING` Abstractions & Naming[](#breaking-abstractions--naming "Прямая ссылка на этот заголовок") Теперь определены конкретные абстракции и [четкие рекомендации для их нейминга](/documentation/ru/docs/about/understanding/naming.md) #### Layers[](#layers "Прямая ссылка на этот заголовок") * `/app` — **слой инициализации приложения** * *Прежние варианты: `app`, `core`, `init`, `src/index` (и такое бывает)* * `/processes` — [**слой бизнес-процессов**](https://github.com/feature-sliced/documentation/discussions/20) * *Прежние варианты: `processes`, `flows`, `workflows`* * `/pages` — **слой страниц приложения** * *Прежние варианты: `pages`, `screens`, `views`, `layouts`, `components`, `containers`* * `/features` — [**слой частей функциональности**](https://github.com/feature-sliced/documentation/discussions/23) * *Прежние варианты: `features`, `components`, `containers`* * `/entities` — [**слой бизнес-сущностей**](https://github.com/feature-sliced/documentation/discussions/18#discussioncomment-422649) * *Прежние варианты: `entities`, `models`, `shared`* * `/shared` — [**слой переиспользуемого инфраструктурного кода**](https://github.com/feature-sliced/documentation/discussions/31#discussioncomment-453020) 🔥 * *Прежние варианты: `shared`, `common`, `lib`* #### Segments[](#segments "Прямая ссылка на этот заголовок") * `/ui` — [**UI-сегмент**](https://github.com/feature-sliced/documentation/discussions/31#discussioncomment-453132) 🔥 * *Прежние варианты: `ui`, `components`, `view`* * `/model` — [**БЛ-сегмент**](https://github.com/feature-sliced/documentation/discussions/31#discussioncomment-472645) 🔥 * *Прежние варианты: `model`, `store`, `state`, `services`, `controller`* * `/lib` — сегмент **вспомогательного кода** * *Прежние варианты: `lib`, `libs`, `utils`, `helpers`* * `/api` — [**API-сегмент**](https://github.com/feature-sliced/documentation/discussions/66) * *Прежние варианты: `api`, `service`, `requests`, `queries`* * `/config` — **сегмент конфигурации приложения** * *Прежние варианты: `config`, `env`, `get-env`* ### `REFINED` Low coupling[](#refined-low-coupling "Прямая ссылка на этот заголовок") Теперь гораздо проще [соблюдать принцип низкой связности](/documentation/ru/docs/reference/slices-segments.md#zero-coupling-high-cohesion) между модулями, благодаря новым слоям. *При этом по-прежнему рекомендуется максимально избегать случаев, где крайне трудно "расцепить" модули* ## См. также[](#see-also "Прямая ссылка на этот заголовок") * [Заметки с доклада "React SPB Meetup #1"](https://t.me/feature_slices) * [React Berlin Talk - Oleg Isonen "Feature Driven Architecture"](https://www.youtube.com/watch?v=BWAeYuWFHhs) * [Сравнение с v1 (community-chat)](https://t.me/feature_sliced/493) * [Новые идеи v2 с пояснениями (atomicdesign-chat)](https://t.me/atomicdesign/18708) * [Обсуждение абстракций и нейминга для новой версии методологии (v2)](https://github.com/feature-sliced/documentation/discussions/31) --- # Миграция с v2.0 на v2.1 Основным изменением в v2.1 является новая ментальная модель разложения интерфейса — сначала страницы. В версии FSD 2.0 рекомендовалось найти сущности и фичи в вашем интерфейсе, рассматривая даже малейшие части представления сущностей и интерактивность как кандидаты на декомпозицию. Затем вы бы могли строить виджеты и страницы из сущностей и фич. В этой модели декомпозиции большая часть логики находилась в сущностях и фичах, а страницы были просто композиционными слоями, которые сами по себе не имели большого значения. В версии FSD 2.1 мы рекомендуем начинать со страниц, и возможно даже на них и остановиться. Большинство людей уже знают, как разделить приложение на страницы, и страницы также часто являются отправной точкой при попытке найти компонент в кодовой базе. В новой модели декомпозиции вы храните большую часть интерфейса и логики в каждой отдельной странице, а повторно используемый фундамент — в Shared. Если возникнет необходимость переиспользования бизнес-логики на нескольких страницах, вы можете переместить её на слой ниже. Другим нововведением в Feature-Sliced Design 2.1 является стандартизация кросс-импортов между сущностями с помощью `@x`-нотации. ## Как мигрировать[](#how-to-migrate "Прямая ссылка на этот заголовок") В версии 2.1 нет ломающих изменений, что означает, что проект, написанный с использованием FSD v2.0, также является валидным проектом в FSD v2.1. Однако мы считаем, что новая ментальная модель более полезна для команд и особенно для обучения новых разработчиков, поэтому рекомендуем внести небольшие изменения в вашу декомпозицию. ### Соедините слайсы[](#соедините-слайсы "Прямая ссылка на этот заголовок") Простой способ начать — запустить на проекте наш линтер, [Steiger](https://github.com/feature-sliced/steiger). Steiger построен с новой ментальной моделью, и наиболее полезные правила будут: * [`insignificant-slice`](https://github.com/feature-sliced/steiger/tree/master/packages/steiger-plugin-fsd/src/insignificant-slice) — если сущность или фича используется только на одной странице, это правило предложит целиком переместить код этой сущности или фичи прямо в эту страницу. * [`excessive-slicing`](https://github.com/feature-sliced/steiger/tree/master/packages/steiger-plugin-fsd/src/excessive-slicing) — если у слоя слишком много слайсов, это обычно означает, что декомпозиция слишком мелкая. Это правило предложит объединить или сгруппировать некоторые слайсы, чтобы помочь в навигации по проекту. ``` npx steiger src ``` Это поможет вам определить, какие слайсы используются только один раз, чтобы вы могли ещё раз подумать, действительно ли они необходимы. Помните, что слой формирует своего рода глобальное пространство имен для всех слайсов внутри него. Точно так же, как вы не захотите загрязнять глобальное пространство имен переменными, которые используются только один раз, вы должны относиться к месту в пространстве имен слоя как к ценному месту, которое следует использовать сдержанно. ### Стандартизируйте кросс-импорты[](#стандартизируйте-кросс-импорты "Прямая ссылка на этот заголовок") Если у вас были кросс-импорты в вашем проекте до этого (мы не осуждаем!), вы теперь можете воспользоваться новой нотацией для кросс-импортов в Feature-Sliced Design — `@x`-нотацией. Она выглядит так: entities/B/some/file.ts ``` import type { EntityA } from "entities/A/@x/B"; ``` Чтоб узнать больше об этом, обратитесь к разделу [Публичный API для кросс-импортов](/documentation/ru/docs/reference/public-api.md#public-api-for-cross-imports) в разделе справочника. --- # Использование с Electron Electron-приложения имеют особую архитектуру, состоящую из нескольких процессов с разными ответственностями. Применение FSD в таком контексте требует адаптации структуры под специфику Electron. ``` └── src ├── app # Общий слой app │ ├── main # Main процесс │ │ └── index.ts # Точка входа main процесса │ ├── preload # Preload скрипт и Context Bridge │ │ └── index.ts # Точка входа preload │ └── renderer # Renderer процесс │ └── index.html # Точка входа renderer процесса ├── main │ ├── features │ │ └── user │ │ └── ipc │ │ ├── get-user.ts │ │ └── send-user.ts │ ├── entities │ └── shared ├── renderer │ ├── pages │ │ ├── settings │ │ │ ├── ipc │ │ │ │ ├── get-user.ts │ │ │ │ └── save-user.ts │ │ │ ├── ui │ │ │ │ └── user.tsx │ │ │ └── index.ts │ │ └── home │ │ ├── ui │ │ │ └── home.tsx │ │ └── index.ts │ ├── widgets │ ├── features │ ├── entities │ └── shared └── shared # Общий код между main и renderer └── ipc # Описание IPC (наименование event'ов, контракты) ``` ## Правила для публичного API[](#правила-для-публичного-api "Прямая ссылка на этот заголовок") Каждый процесс должен иметь свой публичный API, как пример, нельзя импортировать модули из `main` в `renderer`. Общедоступным между процессами кодом является только папка `src/shared`. Она же необходима для описания контрактов по взаимодействию процессов. ## Дополнительные изменения в стандартной структуре[](#дополнительные-изменения-в-стандартной-структуре "Прямая ссылка на этот заголовок") Предлагается использовать новый сегмент `ipc`, в котором происходит взаимодействие между процессами. Слои `pages` и `widgets`, исходя из названия, не должны присутствовать в `src/main`, вы можете использовать `features`, `entities` и `shared`. Слой `app` в `src` содержит точки входа для `main` и `renderer`, а также IPC. Сегментам в слое `app` нежелательно иметь точек пересечения ## Пример взаимодействия[](#пример-взаимодействия "Прямая ссылка на этот заголовок") src/shared/ipc/channels.ts ``` export const CHANNELS = { GET_USER_DATA: 'GET_USER_DATA', SAVE_USER: 'SAVE_USER', } as const; export type TChannelKeys = keyof typeof CHANNELS; ``` src/shared/ipc/events.ts ``` import { CHANNELS } from './channels'; export interface IEvents { [CHANNELS.GET_USER_DATA]: { args: void, response?: { name: string; email: string; }; }; [CHANNELS.SAVE_USER]: { args: { name: string; }; response: void; }; } ``` src/shared/ipc/preload.ts ``` import { CHANNELS } from './channels'; import type { IEvents } from './events'; type TOptionalArgs
My Custom App component
Loading...
;
}
if (isError || !post) {
return <>{error?.message};
}
return (
Post id: {post.id}
{post.title}
{post.body}
Owner: {post.userId}
Компоненты на этом слое не должны содержать бизнес-логику, но могут быть тематически связаны с бизнесом. Например, здесь можно разместить логотип компании и макет страницы. Компоненты с UI-логикой также допустимы (например, автозаполнение или строка поиска). * `📁 lib` — коллекция внутренних библиотек.
Эта папка не должна рассматриваться как хелперы или утилиты ([прочитайте здесь, почему эти папки часто превращаются в свалку](https://sergeysova.com/ru/why-utils-and-helpers-is-a-dump/)). Вместо этого каждая библиотека в этой папке должна иметь одну область фокуса, например, даты, цвета, манипуляции с текстом и т.д. Эта область фокуса должна быть задокументирована в файле README. Разработчики в вашей команде должны знать, что можно и что нельзя добавлять в эти библиотеки. * `📁 config` — переменные окружения, глобальные фиче-флаги и другая глобальная конфигурация для вашего приложения. * `📁 routes` — константы маршрутов или шаблоны для сопоставления маршрутов. * `📁 i18n` — код, настраивающий систему переводов, а также глобальные строки перевода. Вы можете добавлять ещё сегментов, но убедитесь, что название этих сегментов описывает цель содержимого, а не его суть. Например, `components`, `hooks` и `types` — плохие имена сегментов, поскольку они не очень полезны при поиске кода. ### Entities[](#entities "Прямая ссылка на этот заголовок") Слайсы на этом слое представляют концепции из реального мира, с которыми работает проект. Обычно это термины, которые бизнес использует для описания продукта. Например, социальная сеть может работать с бизнес-сущностями, такими как Пользователь, Публикация и Группа. Слайс сущности может содержать хранилище данных (`📁 model`), схемы валидации данных (`📁 model`), функции запросов API, связанные с сущностями (`📁 api`), а также визуальное представление этой сущности в интерфейсе (`📁 ui`). Это визуальное представление не обязательно должно создавать полный блок пользовательского интерфейса — оно в первую очередь предназначено для переиспользования одного и того же внешнего вида на нескольких страницах приложения, и к нему может быть присоединена различная бизнес-логика через пропы или слоты. #### Связи между сущностями[](#связи-между-сущностями "Прямая ссылка на этот заголовок") Сущности в FSD являются слайсами, и по умолчанию слайсы не могут знать друг о друге. Однако в реальной жизни сущности часто взаимодействуют друг с другом, и иногда одна сущность владеет или содержит другие сущности. Из-за этого бизнес-логику этих взаимодействий лучше всего хранить на более высоких уровнях, таких как Features или Pages. Когда объект данных одной сущности содержит другие объекты данных, обычно хорошей идеей является сделать связь между сущностями явной и обойти изоляцию слайсов, создав API для кросс-ссылок через `@x`-нотацию. Причина в том, что связанные сущности должны рефакториться вместе, поэтому лучше сделать так, чтоб связь было невозможно не заметить. Например: entities/artist/model/artist.ts ``` import type { Song } from "entities/song/@x/artist"; export interface Artist { name: string; songs: Array
Например, если у вас есть индекс для фичи "comments", `📄 features/comments/index.js`, нет смысла иметь еще один индекс для `ui` сегмента этой фичи, `📄 features/comments/ui/index.js`. 3. Если у вас очень большой проект, есть большая вероятность, что ваше приложение можно разделить на несколько больших кусков.
Например, у Google Docs очень разные обязанности для редактора документов и для файлового браузера. Вы можете создать монорепозиторий, где каждый пакет является отдельным корнем FSD со своим набором слоев. Некоторые пакеты могут иметь только слои Shared и Entities, другие могут иметь только Pages и App, а некоторые могут включать свой небольшой Shared, но при этом использовать большой Shared из другого пакета. --- # Слайсы и сегменты ## Слайсы[](#слайсы "Прямая ссылка на этот заголовок") Слайсы — это второй уровень в организационной иерархии Feature-Sliced Design. Их основное назначение — группировать код по его значению для продукта, бизнеса или просто приложения. Имена слайсов не стандартизированы, поскольку они напрямую определяются бизнес-областью вашего приложения. Например, фотогалерея может иметь слайсы `photo`, `effects`, `gallery-page`. Для социальной сети потребуются другие слайсы, например, `post`, `comments`, `news-feed`. Слои Shared и App не содержат слайсов. Это потому, что Shared не должен содержать никакой бизнес-логики, следовательно, не имеет продуктового значения, а App должен содержать только код, касающийся всего приложения, поэтому разделение не требуется. ### Нулевая сцепленность и высокая связность[](#zero-coupling-high-cohesion "Прямая ссылка на этот заголовок") Слайсы задуманы как независимые и сильно связанные группы файлов кода. Картинка ниже может помочь визуализировать такие сложные концепции как *связность* (cohesion) и *сцепленность* (coupling):  Картинка вдохновлена