Перейти к содержимому

Кросс-импорты

Кросс-импорт означает импорт между разными слайсами одного слоя.

Например:

  • импорт из features/product в features/cart
  • импорт из widgets/sidebar в widgets/header

Кросс-импорты считаются признаком проблем в коде (code smell): они указывают на то, что слайсы становятся зависимыми друг от друга. В некоторых ситуациях избежать их непросто, но такие зависимости всегда должны быть осознанными. Их нужно либо документировать, либо обсуждать с командой проекта.

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

Рассмотрим ситуацию, когда слайс cart напрямую зависит от бизнес-логики product. На первый взгляд это может показаться удобным, но такой подход создаёт несколько проблем:

  1. Неясные границы ответственности. Когда cart импортирует код из product, становится непонятно, какой слайс отвечает за общую логику. Если команда, работающая над product, изменит его внутреннюю реализацию, она может незаметно для себя нарушить работу cart. Из-за этой неоднозначности сложнее разбираться в кодовой базе и определять, кто отвечает за исправление ошибок или развитие функциональности.

  2. Снижение изоляции и усложнение тестирования. Одно из главных преимуществ архитектуры со слайсами в том, что каждый слайс можно разрабатывать, тестировать и развёртывать независимо. Кросс-импорты нарушают эту изоляцию: для тестирования cart теперь нужно подготовить и product, а изменения в одном слайсе могут неожиданно привести к падению тестов в другом.

  3. Рост когнитивной нагрузки. При работе над cart приходится учитывать устройство и поведение product. Чем больше кросс-импортов, тем больше кода в разных слайсах нужно изучить, чтобы оценить последствия изменений. Даже небольшие правки требуют держать в голове больше контекста.

  4. Риск циклических зависимостей. Кросс-импорты часто начинаются с односторонних зависимостей, но со временем могут стать двусторонними: A импортирует B, а B импортирует A. Это тесно связывает слайсы, усложняет разделение зависимостей и со временем повышает стоимость рефакторинга.

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

Ниже мы рассмотрим, как эти проблемы обычно проявляются в реальных проектах и какие стратегии помогают их решить.

Кросс-импорты в entities часто возникают из-за слишком мелкого разделения сущностей. Прежде чем использовать @x нотацию, подумайте, не стоит ли объединить слайсы. Некоторые команды используют @x как отдельный интерфейс для кросс-импортов в entities. Однако это крайняя мера и вынужденный компромисс, а не рекомендуемый подход.

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

Подробнее о @x читайте в документации по публичному API.

Примеры взаимных ссылок между бизнес-сущностями:

На слоях features и widgets обычно практичнее рассматривать несколько стратегий работы с кросс-импортами, чем объявлять их безусловно запрещёнными. В этом разделе мы сосредоточимся не столько на коде, сколько на подходах, которые можно выбрать с учётом особенностей команды и продукта.

Если два слайса не являются по-настоящему независимыми и всегда изменяются вместе, объедините их в один более крупный слайс.

Пример до объединения:

  • features/profile
  • features/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): используйте именованные слоты, чтобы передавать содержимое из родительских компонентов
  • Внедрение зависимостей: передавайте зависимости через пропсы или контекст
features/userProfile/index.ts
export { UserProfilePanel } from './ui/UserProfilePanel';
features/activityFeed/index.ts
export { ActivityFeed } from './ui/ActivityFeed';
pages/UserDashboardPage.tsx
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 для инверсии зависимости:

features/commentList/ui/CommentList.tsx
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>
);
}
pages/PostPage.tsx
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 позволяет удобно объединять фичи без кросс-импортов:

features/commentList/ui/CommentList.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>
pages/PostPage.vue
<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, которые направлены на устранение кросс-импортов, эта стратегия допускает их, но снижает риски за счёт строгих границ.

features/auth/index.ts
export { useAuth } from './model/useAuth';
export { AuthButton } from './ui/AuthButton';
features/profile/ui/ProfileMenu.tsx
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, вместо этого реализуются через кросс-импорты в пределах одного слоя

Если вы замечаете такие признаки, считайте кросс-импорт признаком проблем в коде и рассмотрите хотя бы одну из описанных выше стратегий.

Степень строгости определяет команда проекта

Заголовок раздела «Степень строгости определяет команда проекта»

Насколько строго соблюдать эти правила, зависит от команды и проекта.

Например:

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

Здесь нет безусловного запрета на кросс-импорты. Это зависимости, которых обычно лучше избегать, но которые иногда используют осознанно.

Если вы всё же добавляете кросс-импорт:

  • рассматривайте его как осознанное архитектурное решение
  • документируйте причины
  • периодически пересматривайте это решение по мере развития системы

Команде стоит договориться:

  • какой уровень строгости ей нужен
  • как отразить его в правилах линтера, проверке кода и документации
  • когда и как пересматривать существующие кросс-импорты