[ARCHIVED] Public API абстракции

[azinit]

Дискуссия закрыта, см. выводы по #76

---

---

---

Об экспорте и использовании публичного API модуля (фича/shared/...) и его формате

---

В целом, хочется, чтобы соблюдалось следующее правило:

Каждая абстракция должна быть спроектирована с публичным API для использования и интеграции

- import { actions } from "features/auth/store/slice"      # Для dispatch(actions) (да я редаксоид)
+ import { authStore } from "features/auth"  # dispatch(authStore.actions)

- import { formatDate } from "shared/lib/dates/format"
+ import dates from "shared/lib/dates"

- import { ButtonGroup } from "shared/ui/button/group"
+ import { ButtonGroup } from "shared/ui/button"    # Или Button.Group (привет Compound.Components)

Иными словами - нельзя лезть "в кишки" внутрь модулей, т.к. мы не должны знать деталей реализации модуля для использования
(плюс фича сама должна контролировать то, чем можно пользоваться "извне")

[azinit]

@karina-drummer
Что-то интересное выходит. Наталкивает на мысль что надо притянуть TS и создать специальный тип Feature

[azinit]

@karina-drummer
Хм, будет страдать DCE?
Ну ты судя по всему высказал негативный фидбэк по экспорту и использованию фичи как единого объекта
Вот я и спрашиваю, почему. Проблема в том, что dead code elimination не будет работать

[azinit]

@sergeysova
Есть import * as object
Если хочешь импортнуть одну сущность, то ты предлагаешь не позволять это сделать

[azinit]

@karina-drummer
Какие преимущества может дать импорт конкретной сущности из фичи вместо доступа к этой сущности через dot-notation?

;; btw благодаря твоему совету я таки перестала химичить с константами ( которые я обозвала конфигом ) и стала просто экспортить замороженные объекты. Правда хотелось бы иметь нормальный deepFreeze с выводом типов

[azinit]

@sergeysova
Короткочтение
Иначе все сущности будут с префиксом

[azinit]

@karina-drummer
Кстати, не могу избавиться от чувства, что пишу говнокод, когда делаю import * as smth from "whatever" 😬😖
Так и продолжаю в итоге пока что объекты экспортить.

[azinit]

@sergeysova
Если хочешь импортнуть одну сущность, то ты предлагаешь не позволять это сделать

@martis-git

Ну вот кста да, у нас тоже что-то около таких мыслей было

И пока дошли до того, чтобы публичный API фичи примерно так выглядел:

• экспортил сам компонент (TasksList)
• экспортил store (привет Redux)
• экспортил оставшееся дополнительное что нужно (например те же query-параметры, с которыми работает)

(чаще всего они отдельно используются)

[azinit]

@martis-git
И если надо - где-то идет обращение к внутренним элементам через точку

• Т.е. иногда в один компонент заэкспортить не выходит, и приходится обращаться к дочерним через Compound Components (<TasksList.Toolbar />, <TasksList.Content/> условно)

• Та же шляпа при работе с store - все сущности называются плюс-минус похоже внутри, но префиксы фичи мы даем тольк на верхнем уровне при декларации API фичи

[azinit]

@martis-git
Тип это в целом неплохо себя зарекомендовало вродь, но просто стоит понимать какую проблему решает

А не пихать например и store и UI в один объект)
Ну у нас такое впечатление по опыту сложилось

[azinit]

@karina-drummer
я экспорчу фичи и сущности цельными объектами

[azinit]

@karina-drummer
Собственно почему я решила так и дальше делать: хочу дать своим разрабам возможность импортнуть один раз сущность, написать точечку после её имени и увидеть всё что в сущности есть

[azinit]

@sergeysova
странное…

[azinit]

🔥 Благодаря бурной внутренней дискуссии @sergeysova и @karina-drummer вот какие выводы можем сделать:

---

Требования к Public API [абстракции]

1. Должен обладать анти-хрупкостью

   т.е. не ломаться при каждом изменении реализации / структуры директорий

   "рефакторинг внутренней структуры фичи не должен ломать внешнее апи"

   # Плохо (API представляет из себя структуру, т.е. показывает всю внутрянку)
   # Из-за этого придется каждый раз рефакторить АПИ, когда поменяется внутренняя структура фичи
   - <authForm.components.view.form ... />
   - import { form } from "features/auth-form/components/view/form"
   # Хорошо (API заранее экспортирует только нужное, развязывая руки будущему разработчику фичи)
   + import { AuthForm } from "features/auth-form"
   + <AuthForm ... />

   Пример из react

   - import {useMemo} from 'react/hooks/*/useMemo'
   + import {useMemo} from 'react'

2. Должен быть достаточно гибким и юзабельным

   Наши абстракции - "черный ящик", и публичный API должен позволять не лезть "в кишки", ради ее использования

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

   # Плохо (фича экспортирует из себя все подряд, без заботы о "пользователе" фичи)
   - import { storeActionUpdateUserDetails } from "features/auth-form"
   - dispatch(storeActionUpdateUserDetails(...))
   # Хорошо ("пользователь" фичи может получать доступ к нужным вещам итеративно и гибко)
   + import { authFormStore } from "features/auth-form"
   + dispatch(authFormStore.actions.updateUserDetails(...))

3. Должен решать проблему коллизии имен

   При этом это задача только public API, а не самой реализации (см. ниже)

   # Плохо (будет коллизия)
   - import { store } from "features/auth-form"
   - import { store } from "features/post-form"
   # Хорошо (авторы фичей позаботились об этом заранее)
   + import { authFormStore } from "features/auth-form"
   + import { postFormStore } from "features/post-form"

   Про разрешение коллизий

   Нужно понимать, что коллизии нужно разрешать только на уровне публичного API

   # Плохо (коллизия не должна резолвиться на уровне реализации)
   - export { actions as authFormActions, reducer as authFormReducer } from "./slice"
   -
   - dispatch(authFormActions.foo(...))
   # Хорошо (реализация не думает о коллизиях - это становится заботой только для самой фичи)
   + export { actions, reducer } from "./slice"
   + export * as authFormStore  from "./store"   # Feature EntryPoint
   +
   + dispatch(authFormStore.actions.foo(...))

[azinit]

Думаю также надо обсудить, как разбивать бандлы, если у нас только "одна точка" подключения к фиче

Является ли это трейд-оффом, с которым мы должны смириться (что тянем всю фичу в бандл), или же есть какие-то обходные пути?

[azinit]

@karina-drummer
Ну точнее надо бандлить так, чтобы бандл разрезался по фичам, чтобы это работало

А если разрезать бандл -- нужно либо каждую фичу прописывать в package.json, либо писать точный путь к index.js каждой фичи

[azinit]

@ilyaagarkov
кстати, а что там тришейкигом при реэкспортах? Как то читал что реэкспорты ломают тришейкинг. Это пофиксили? Для фич в том виде в котором они представлены сейчас после всех обсуждений это может и не критично, кажется что фичи все таки будут достаточно минималистычны. А вот entities могут раздуваться весьма прилично.

[azinit]

Нашел тот пост

https://t.me/iamakulov_channel/558