Кросс-импорты
Кросс-импорт означает импорт между разными слайсами одного слоя.
Например:
- импорт из
features/productвfeatures/cart - импорт из
widgets/sidebarвwidgets/header
Кросс-импорты считаются признаком проблем в коде (code smell): они указывают на то, что слайсы становятся зависимыми друг от друга. В некоторых ситуациях избежать их непросто, но такие зависимости всегда должны быть осознанными. Их нужно либо документировать, либо обсуждать с командой проекта.
Почему это признак проблем в коде?
Заголовок раздела «Почему это признак проблем в коде?»Кросс-импорты не просто вопрос стиля. Их обычно считают признаком проблем в коде, потому что они размывают границы между доменами и создают неявные зависимости.
Рассмотрим ситуацию, когда слайс cart напрямую зависит от бизнес-логики product. На первый взгляд это может показаться удобным, но такой подход создаёт несколько проблем:
-
Неясные границы ответственности. Когда
cartимпортирует код изproduct, становится непонятно, какой слайс отвечает за общую логику. Если команда, работающая надproduct, изменит его внутреннюю реализацию, она может незаметно для себя нарушить работуcart. Из-за этой неоднозначности сложнее разбираться в кодовой базе и определять, кто отвечает за исправление ошибок или развитие функциональности. -
Снижение изоляции и усложнение тестирования. Одно из главных преимуществ архитектуры со слайсами в том, что каждый слайс можно разрабатывать, тестировать и развёртывать независимо. Кросс-импорты нарушают эту изоляцию: для тестирования
cartтеперь нужно подготовить иproduct, а изменения в одном слайсе могут неожиданно привести к падению тестов в другом. -
Рост когнитивной нагрузки. При работе над
cartприходится учитывать устройство и поведениеproduct. Чем больше кросс-импортов, тем больше кода в разных слайсах нужно изучить, чтобы оценить последствия изменений. Даже небольшие правки требуют держать в голове больше контекста. -
Риск циклических зависимостей. Кросс-импорты часто начинаются с односторонних зависимостей, но со временем могут стать двусторонними: A импортирует B, а B импортирует A. Это тесно связывает слайсы, усложняет разделение зависимостей и со временем повышает стоимость рефакторинга.
Чёткие границы доменов нужны для того, чтобы каждый слайс решал свою задачу и мог изменяться в пределах своей ответственности. При слабой связанности проще предсказать последствия изменений и ограничить объём проверки кода и тестирования. Кросс-импорты ослабляют это разделение: изменения затрагивают больше кода, а рефакторинг со временем становится дороже. Поэтому их считают признаком проблем в коде, который не стоит игнорировать.
Ниже мы рассмотрим, как эти проблемы обычно проявляются в реальных проектах и какие стратегии помогают их решить.
Кросс-импорты на слое Entities
Заголовок раздела «Кросс-импорты на слое Entities»Кросс-импорты в entities часто возникают из-за слишком мелкого разделения сущностей. Прежде чем использовать @x нотацию, подумайте, не стоит ли объединить слайсы.
Некоторые команды используют @x как отдельный интерфейс для кросс-импортов в entities. Однако это крайняя мера и вынужденный компромисс, а не рекомендуемый подход.
Рассматривайте @x как явную точку доступа для неизбежных связей между доменами, а не как универсальный механизм переиспользования кода. Чрезмерное использование этой нотации тесно связывает сущности и со временем повышает стоимость рефакторинга.
Подробнее о @x читайте в документации по публичному API.
Примеры взаимных ссылок между бизнес-сущностями:
Features и Widgets: несколько стратегий
Заголовок раздела «Features и Widgets: несколько стратегий»На слоях features и widgets обычно практичнее рассматривать несколько стратегий работы с кросс-импортами, чем объявлять их безусловно запрещёнными. В этом разделе мы сосредоточимся не столько на коде, сколько на подходах, которые можно выбрать с учётом особенностей команды и продукта.
Стратегия A: объединение слайсов
Заголовок раздела «Стратегия A: объединение слайсов»Если два слайса не являются по-настоящему независимыми и всегда изменяются вместе, объедините их в один более крупный слайс.
Пример до объединения:
features/profilefeatures/profileSettings
Если эти слайсы постоянно импортируют код друг из друга и фактически развиваются как единое целое, скорее всего, на практике это одна фича. В таком случае объединить их в features/profile часто будет проще и логичнее.
Стратегия B: перенос общих бизнес-сценариев в entities (только доменная логика)
Заголовок раздела «Стратегия B: перенос общих бизнес-сценариев в entities (только доменная логика)»Если несколько фич используют общий бизнес-сценарий, перенесите его в слайс соответствующего домена на слое entities, например в entities/session.
Основные принципы:
- в
entitiesразмещаются только доменные типы и доменная логика - пользовательский интерфейс остаётся в
features/widgets - фичи импортируют и используют доменную логику из
entities
Например, если и features/auth, и features/profile нужна проверка сессии, разместите доменные функции для работы с сессией в entities/session и используйте их в обеих фичах.
Подробнее читайте в справочнике по слоям, в разделе Entities.
Стратегия C: композиция на вышележащем слое (pages / app)
Заголовок раздела «Стратегия C: композиция на вышележащем слое (pages / app)»Вместо того чтобы связывать слайсы одного слоя кросс-импортами, объединяйте их на более высоком уровне (pages / app). Этот подход использует паттерны инверсии управления (Inversion of Control, IoC): слайсы не знают друг о друге, а вышележащий слой собирает и связывает их.
Распространённые способы реализации IoC:
- Render props (React): передавайте компоненты или функции рендеринга через пропсы
- Слоты (Vue): используйте именованные слоты, чтобы передавать содержимое из родительских компонентов
- Внедрение зависимостей: передавайте зависимости через пропсы или контекст
Простой пример композиции (React)
Заголовок раздела «Простой пример композиции (React)»export { UserProfilePanel } from './ui/UserProfilePanel';export { ActivityFeed } from './ui/ActivityFeed';import React from 'react';import { UserProfilePanel } from '@/features/userProfile';import { ActivityFeed } from '@/features/activityFeed';
export function UserDashboardPage() { return ( <div> <UserProfilePanel /> <ActivityFeed /> </div> );}При такой структуре features/userProfile и features/activityFeed не знают друг о друге. Страница pages/UserDashboardPage объединяет их в полноценный экран.
Пример с render props (React)
Заголовок раздела «Пример с render props (React)»Если одной фиче нужно отобразить содержимое другой, используйте render props для инверсии зависимости:
interface CommentListProps { comments: Comment[]; renderUserAvatar?: (userId: string) => React.ReactNode;}
export function CommentList({ comments, renderUserAvatar }: CommentListProps) { return ( <ul> {comments.map(comment => ( <li key={comment.id}> {renderUserAvatar?.(comment.userId)} <span>{comment.text}</span> </li> ))} </ul> );}import { CommentList } from '@/features/commentList';import { UserAvatar } from '@/features/userProfile';
export function PostPage() { return ( <CommentList comments={comments} renderUserAvatar={(userId) => <UserAvatar userId={userId} />} /> );}Теперь CommentList не импортирует код из userProfile: страница передаёт компонент аватара через пропс.
Пример со слотами (Vue)
Заголовок раздела «Пример со слотами (Vue)»Система слотов Vue позволяет удобно объединять фичи без кросс-импортов:
<template> <ul> <li v-for="comment in comments" :key="comment.id"> <slot name="avatar" :userId="comment.userId" /> <span>{{ comment.text }}</span> </li> </ul></template>
<script setup lang="ts">defineProps<{ comments: Comment[];}>();</script><template> <CommentList :comments="comments"> <template #avatar="{ userId }"> <UserAvatar :userId="userId" /> </template> </CommentList></template>
<script setup lang="ts">import { CommentList } from '@/features/commentList';import { UserAvatar } from '@/features/userProfile';</script>Фича CommentList остаётся независимой от userProfile. Страница объединяет их с помощью слотов.
Стратегия D: переиспользование кода между фичами только через публичный API
Заголовок раздела «Стратегия D: переиспользование кода между фичами только через публичный API»Если предыдущие стратегии не подходят и переиспользования кода между фичами действительно не избежать, допускайте его только через явно определённый публичный API, например экспортируемые хуки или UI-компоненты. Не обращайтесь напрямую к store/model другого слайса или деталям его внутренней реализации.
В отличие от стратегий A, B и C, которые направлены на устранение кросс-импортов, эта стратегия допускает их, но снижает риски за счёт строгих границ.
Пример кода
Заголовок раздела «Пример кода»export { useAuth } from './model/useAuth';export { AuthButton } from './ui/AuthButton';import React from 'react';import { useAuth, AuthButton } from '@/features/auth';
export function ProfileMenu() { const { user } = useAuth();
if (!user) { return <AuthButton />; }
return <div>{user.name}</div>;}Например, запретите features/profile импортировать код по путям вроде features/auth/model/internal/*. Разрешите использовать только то, что features/auth явно предоставляет через свой публичный API.
Когда кросс-импорты становятся проблемой?
Заголовок раздела «Когда кросс-импорты становятся проблемой?»После знакомства с этими стратегиями возникает закономерный вопрос:
Когда кросс-импорт допустимо оставить, а когда его следует считать признаком проблем в коде и устранить с помощью рефакторинга?
Типичные тревожные признаки:
- прямая зависимость от хранилища, модели или бизнес-логики другого слайса
- импорты напрямую из внутренних файлов другого слайса
- двусторонние зависимости: A импортирует B, а B импортирует A
- изменения в одном слайсе часто нарушают работу другого
- сценарии, которые должны собираться на слоях
pages/app, вместо этого реализуются через кросс-импорты в пределах одного слоя
Если вы замечаете такие признаки, считайте кросс-импорт признаком проблем в коде и рассмотрите хотя бы одну из описанных выше стратегий.
Степень строгости определяет команда проекта
Заголовок раздела «Степень строгости определяет команда проекта»Насколько строго соблюдать эти правила, зависит от команды и проекта.
Например:
- В продуктах на ранней стадии, где активно экспериментируют, некоторые кросс-импорты могут быть разумным компромиссом ради скорости разработки.
- В системах с длительным сроком эксплуатации или строгими регуляторными требованиями, например в финтехе или крупных сервисах, более строгие границы часто окупаются за счёт удобства сопровождения и стабильности.
Здесь нет безусловного запрета на кросс-импорты. Это зависимости, которых обычно лучше избегать, но которые иногда используют осознанно.
Если вы всё же добавляете кросс-импорт:
- рассматривайте его как осознанное архитектурное решение
- документируйте причины
- периодически пересматривайте это решение по мере развития системы
Команде стоит договориться:
- какой уровень строгости ей нужен
- как отразить его в правилах линтера, проверке кода и документации
- когда и как пересматривать существующие кросс-импорты
