Публичный API директории
Индексный файл директории — ее публичный API и единственная разрешенная точка входа для внешнего кода. Такой файл также называют баррелем (barrel): он содержит реэкспорты из содержимого директории.
Наличие индексного файла означает, что директория является самостоятельной границей: внешний код может обращаться к ее содержимому только через этот файл.
Таким образом, index.ts — это не просто сокращение импортов. Он явно отделяет публичный интерфейс директории от ее внутренней реализации.
Это справедливо для любой директории в проекте:
- модуля;
- слоя;
- сложного компонента, состоящего из нескольких файлов.
Какую проблему решает
Без четкой границы потребители импортируют внутренние файлы напрямую, превращая детали реализации в публичный контракт. В результате любой рефакторинг может затронуть весь проект.
Правила
Чтобы баррель работал как инструмент архитектурного контроля, необходимо соблюдать три правила:
Осознанное расширение API
Каждая строка в барреле — это публичное обещание поддерживать имя. Добавлять экспорт нужно только тогда, когда он действительно нужен потребителям сегодня. Экспортировать «на будущее» или «всё, что лежит в папке» создает ненужные обязательства.
Запрет импорта из своего или вышестоящего барреля
Импорт через свои и родительские баррели запрещен — это спасает от циклических зависимостей.
Это касается только продуктового кода
Для тестов, сторибука, моков и подобных вспомогательных файлов допустимо импортировать через баррель. Это снижает зависимость от деталей внутренней реализации, при этом опасность циклических зависимостей минимальна — такие файлы сами не импортируются продуктовым кодом.
Разделение потоков импортов
- Снаружи: Внешний код импортирует сущность строго через ее баррель.
- Внутри: Файлы внутри сущности импортируют друг друга напрямую, используя только относительные пути, Это дает мгновенную визуальную проверку: если внутри файла сущности появляется абсолютный импорт этой же сущности — это прямое нарушение границы и риск циклической зависимости.
Почему
Соблюдение этих правил дает конкретные практические выгоды:
Прозрачность на ревью
Расширение публичного API — это правка одной строки в одном файле. Ревьюер сразу видит, что контракт изменился. Это исключает ситуации, когда новый
exportтихо появляется где-то в глубине сущности.Безопасный рефакторинг
Пока публичные экспорты и их контракт сохраняются, потребители не зависят от расположения внутренних файлов. Внешний код этого не заметит.
Правильно
Явный баррель сущности:
// src/modules/order/entities/index.ts
export { OrderCard } from './ui/order-card';
export { Order, OrderStatus } from './model/types';Внутренний импорт (напрямую, относительный путь):
// src/modules/order/entities/ui/order-card.tsx
import { Order } from '../model/types';Внешний импорт (строго через баррель):
// src/pages/order/order-page.tsx
import { OrderCard, Order } from '@/modules/order/entities';Неправильно
Не контролируемый публичный API:
// src/modules/order/entities/index.ts
export * from './ui/order-card'; // ❌
export * from './model/types'; // ❌Импорт собственного барреля (риск циклических ссылок):
// src/modules/order/entities/ui/order-card.tsx
import { Order } from '..'; // ❌
import { Order } from '@/modules/order/entities/model'; // ❌Импорт в обход публичного API:
// src/pages/order/order-page.tsx
import { OrderCard } from '@/modules/order/entities/ui/order-card'; // ❌Рекомендации
Явный интерфейс, а не зеркало
Баррель должен содержать явный список именованных реэкспортов. Использование
export * from './...'нежелательно. Оно превращает границу в автоматическое зеркало, где любой внутреннийexportслучайно становится публичным контрактом.Реэкспорт из вложенного барреля
Использование
export * from './subdir'допустимо только в том случае, еслиsubdirуже имеет свой собственныйindexфайл. В этом случае вложенная директория уже имеет свой контролируемый публичный API, и мы не экспортируем «всё подряд», а делегируем контроль известной границе.Отсутствие side effects
Баррель должен содержать исключительно инструкции реэкспорта. Никаких импортов стилей, оборачивания компонентов в HOCи, инициализации глобального состояния или вызовов функций. Если в барреле нет исполняемого кода, у бандлера будет больше возможности безопасно вырезать неиспользуемый код.