[ARCHIVED] Абстракции методологии, их цели и нейминг

[azinit]

Дискуссия закрыта, расписывается по #61

---

---

---

Пока что похоже, на такую картину (но надо придти к одному неймингу по итогу):

См. что писал про абстракции разного уровня

Что имеем?

High-level abstractions

Основные, располагаются на высшем уровне, от наиболее "знающих" к наименее (app => shared)

• app - логика инициализации приложения + глобальные стили + провайдеры
• processes - надстраничные процессы (авторизация, оформление заказа, ...), контролируют все что ниже
• pages - страницы (максимально просты, композируют фичи внутри себя)
• features - конкретная функциональность, представляющая собой бизнес-ценность
• entities - сущности БЛ, на которых строится логика фич и абстракций повыше (ч-з компоненты, либы и т.д.)
• 🔥 shared (vs lib vs common) - общеиспользуемые сущности, решающие чисто инфраструктурные проблемы, отстранены от БЛ

Middle-level abstractions

Вкладываются в high-level абстракции, чаще всего служат "подпорным материалом" в реализации логики, равнозначны - каждый выполняет свою роль

• 🔥 ui (или components) - UIKit / компоненты данной абстракции ("образ" функциональности)
• 🔥 models (или store) - Data-слой абстракции для работы со стейтом / событиями - на что могут опираться более высокоуровневые абстракции ("идея" функциональности")
• lib - структурированный набор хелперов набор функций и инфраструктурных решений для решения конкретной проблемы (например для работы с датами, но зависит от абстракции-родителя)
• api - логика работы с API (либо общие, либо конкретные для данной фичи/страницы/...)

Что хотим?

• Понять, точно ли мы понимаем одинаково абстракции

  Есть ли лишние/недостающие, Так ли выстроены связи, Все ли так - как описано выше вообще

• Определиться с единым неймингом

  Пока что у нас конфликтуют (где-то взять одно, где-то подобрать общий синоним)

  • ui vs components
    1. @karina-drummer , @sergeysova, @binjospookie
    2. @martis-git , @niyazm524
  • models vs store
    1. @karina-drummer , @sergeysova, @binjospookie
    2. @martis-git , @niyazm524
  • shared vs lib vs common vs ui/lib(s) (оба на верхнем уровне)
    1. @sergeysova , @martis-git , @niyazm524 , @binjospookie
    2. ???
    3. @karina-drummer
    4. @ilyaagarkov

---

См. пример из нашей текущей доки

Q: А почему я не могу настраивать нейминг как хочу?
A: См. топик Адаптивность нейминга

[azinit]

@ilyaagarkov натолкнул своими вопросами на классную мысль (см. #23 (reply in thread) )

*AAA - значит опционально

UPD: components ~ ui; store ~ models

by types Раньше (давно-давно) мы делили по типам

• Сначала components, store, api, lib
• Потом (внутри каждого) tasks, users, posts

by domains Теперь же мы делим по фичам (или доменам)

• Сначала app, *processes, pages, features, *entities, shared
• Потом (внутри каждого) components, *store, *api, *lib

Иными словами....

High/middle абстракции можно понимать следующим образом:

• High-level-abstraction: абстракция "по функциональности" (методология сначала разбивает по ним)
• Middle-level-abstraction: абстракция "по типам" (то как делили раньше, но теперь у нас каждая абстракция делится по типам, и вроде выглядит логично)

[azinit]

Опять же это про "торт" и Separation of Concerns:

• Мы либо сначала разрезаем по фичам, а потом по типам (чаще всего лучше)
• Либо разрезаем сначала по типам, а потом по фичам (вложенность ниже, но понимание - стремится к нулю)

[azinit]

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

Т.е. можно это представить как такой двойной select:

1. BY-DOMAIN Выберите назначение модуля по функциональности

• app
• processes
• pages
• features
• entities
• shared

2. BY-TYPE Выберите назначение модуля по типу

• ui (или components)
• models (или store)
• lib
• api

3. Fullname вашего модуля (условно):

• {BY-DOMAIN}/{BY-TYPE}

[azinit]

Примеры "Хорошо"/"Плохо"

- features/auth/features/by-google
- shared/**/entities
- ui/feature/auth
- ui/auth
+ features/auth/by-google
+ shared/ui/button
+ entities/skins/ui

[azinit]

Хотя бывают и случаи, когда модуль разрастается по логике, и приходится нарезать повторно в том числе и его

Но не исключено, что это значит только то, что модуль должен сменить свой BY-DOMAIN атрибут

Пример:

# Какой-нибудь сложный компонент, в силу своей сложности - вынужден разрезаться еще раз "по типам"
# Т.к. иначе логика смешается
# Хотя возможно, что в таком случае - компонент уже становиться entity/features/...?
- shared/components
      - smth-difficult-popup
           -  components/
                - source/ ...
                - target/ ...
           -  context/
                - hooks
                - provider
                - index.ts

[azinit]

Вот тут хорошо описано, поч мы поняли, что "нарезать надо по-другому"

https://ryanlanciaux.com/blog/2017/08/20/a-feature-based-approach-to-react-development/

[binjospookie]

Почему мне не нравится shared:
При первом прочтении появляется желание засунуть туда всё, что может быть переиспользовано. Те же самые entities.

Lib -- менее абстрактный неймнинг, кмк, достигающий оригинальную цель (если же правильно её понимаю).

[binjospookie]

Не обязательно:

lib/api
lib/config
lib/service/currency
lib/service/username
lib/service/validations
lib/ui

[sergeysova]

Второй фактор: мы имеем некоторую фрактальную структуру, когда структура shared может повторяться в features и entities:

src/
  features/
    <feat-name>/
      api/
      lib/
      ui/
  entities/
    <entity>/
      api/
      lib/
      ui/
  shared/
    api/
    lib/
    ui/

То есть мы четко обозначаем что мы можем "шарить" в приложении, что достаточно "глобальное" и абстрактное, а что имеет привязку к конкретной сущности или функциональности.

Чтобы не образовывалась свалка в shared нужно четко обозначить, что туда можно положить и мб даже задать структуру директорий.

[sergeysova]

@binjospookie

lib/api
lib/config
lib/service/currency
lib/service/username
lib/service/validations
lib/ui

Это НЕ сервисы, это методы работы с какими-то данными, могут быть весьма разрозненными.
Название service в любом случае вводит в заблуждение.

А любое другое название просто поменяет именование {shared}/{lib}, и убьет назначение "разделяемое"

[sergeysova]

Почему не класть ui внутрь lib?

Во первых, мы часто используем библиотеки из lib при реализации компонентов ui kit, а значит, они уже не могут быть на одном уровне абстракции.
Во вторых, это категорически разные типы библиотек, и при этом имеют очень разное внутреннее устройство.

Тогда как shared/lib пытаются быть максимально гранулированными и простыми, shared/ui будет устроен совсем по другому и попытается реализовать все необходимые базовые компоненты проекта, даже может использовать AtomicDesign

[binjospookie]

Соглашусь с тобой.

[ilyaagarkov]

У меня еще появились сомнения по поводу нейминга папки ui. (именно той которая "главная")
Ведь по сути там лежит набор самых базовых компонентов, то есть это не ui, а именно ui-kit

[azinit]

должно ли? Все таки базовые компоненты из ui-kit и компоненты напрямую связанные с бизнес логикой это в корне разные вещи.

Ну смотри, какая структура, по-твоему покажется понятней тебе и в целом обширному кругу разрабов

1. Стул 1

- entities/user
   - components/
   - lib/
- shared/
   - components/
   - lib/

2. Стул 2 (утрированно, но хорошо суть отображает)

- entities/user
   - components/
   - libs/
- shared/
   - ui/
   - core-lib/

[azinit]

но тут конечно ломается описание про High-level-abstraction и Middle-level-abstraction и что High-level может иметь свои собственные Middle-level .

Кстати, Middle-level как бы подразумевает что есть еще Low-level. Если в итоге все таки придерживаться данной идет то может лучше High-level и Low-Level?

А я там выше написал же, что это не оч определение

В данном случае у нас просто два вида абстракций:

• ТИПЫ: components, api, lib, store
• ФИЧИ: app, processes, pages, features, entities, shared

И если сравнивать наши проекты с тортом - то мы можем разрезать их двумя способами (см. опять же выше пост про это)

• Сначала по типам, потом по фичам (все легаси проекты, стродаем от распыления логики)
• Сначала по фичам, потом по типам (это и есть наш feature-sliced)

[ilyaagarkov]

я видимо сел бы где-то мимо стульев, при этом уронив стол =)

- entities
  - /user
     - components/
     - libs/
- ui-kit/
- libs/

В даном случее я так же вижу, что ui-kit и components это вообще о разном. У разработчиков тоже должно что-то щелкать когда они выбирают куда что положить.

C одной стороны, да - это дополнтельное усложнении. С другой, архитектура это всегда сложно

[sergeysova]

Я крайне плохо отношусь к разным названием одного и того же в проекте.

кнопки/инпуты и прочие обезличенные компоненты это ui-kit, а вот компоненты отображающие конкретные сущности или процессы это уже components

На самом деле нет, разницы нет никакой. Это просто компоненты, которые что-то отображают или делают. Мы уже разделили их по назначению разместив в разных директориях: shared и features/entities.

Нет никакого смысла, на мой взгляд увеличивать и без того высокую ментальную нагрузку добавлением разных имён, потому что это вызовет закономерные вопросы "а почему там components, а тут ui?" или "а если мне надо теперь в feature создать компонент, куда его положить components, ui-ki, ui или core-components?"

Чтобы разработчикам не пришлось отвечать на эти вопросы, мы должны решить эту проблему. И смею заметить мы её уже решили: добавив by types и by features.

Если мы договоримся везде именовать components я не против, но мне важно, чтобы было консистентно.

[Lehakos]

Мне кажется components более обширное понятие, потому как компоненты могут быть не только на отображение чего-то. В Реакте, например, компоненты могут и другие цели выполнять. А вот ui это как-будто просто про отображение

[carina-akaia]

Я вернулась в тот лагерь, который за "ui" и никаких "components". Раньше глобальные ui / lib у нас не лежали в shared ( aka common aka core ), а значит было некоторой нагрузкой отличать /ui от /features/sample-name/ui, но теперь у нас есть явный префикс "shared" в первом случае

[azinit]

Я думал ты и до этого топила всегда за ui))

[carina-akaia]

Наткнулась на кейс, который намекает на то, что "ui" лучше чем "components" Стоит задача сделать из wysiwyg фичу. На данный момент это отдельный пакет, в котором переопределяется и дополняется плагинами third-party редактор ckeditor5. Проблема в том, что в данном примере `view/dialog.js` это не компонент, но имеет отношение к UI, и более того, внутри даже происходит импорт из пакета "@ckeditor/ckeditor5-ui"

[azinit]

А поч кста тогда ты не назвала ui/dialog.js?

[azinit]

Или для тебя ui и view равноценны +-?

[carina-akaia]

А поч кста тогда ты не назвала ui/dialog.js?

не я писала, да и коду кучу лет уже

[azinit]

Готе таки попробуем проголосовать

• 👍 За
• 👎 Против
• 👀 Воздерживаюсь

1. Также пишите свои предложения, если не находятся из имеющихся

2. Описание каждого варианта (и его основные сторонники) - есть в основном посте выше

3. Опрос здесь, а не в тг-чате, т.к. здесь же есть и место для дискуссий, и описание каждой сущности во всей полноте

   Пришлось в github, сорь за формат, но пришлось, т.к. в тг не самое подходящее

4. В опросе расписаны только "конфликтные" варианты, чтобы не засорять лишним

   По остальным моментам +- сходимся, но если не согласны с тем - что написано в основном посте - пишите)

[azinit]

Инициализирующая логика приложения

Предпочитаю все хранить в src/index.tsx а нужные файлы для инициализации располагать рядом

[azinit]

Data-логика, стейт, события абстракции

Предпочитаю state

[azinit]

Data-логика, стейт, события абстракции

Бывает, выношу логику в hooks / effects - и тогда стейт вообще не нужен (как отдельная сущность)

[carina-akaia]

Директория для инфраструктурных и переиспользуемых модулей

Мои варианты:

• basic
• elements
• essentials
• ingredients
• units
• kit
• packages

[ilyaagarkov]

Директория для инфраструктурных и переиспользуемых модулей

general

[azinit]

models vs store

---

UPD: Дискуссия под конец уехала сюда

---

@martis-git
А можешь еще раз напомнить - слайсы у тебя это отдельная модель (store) в фиче/entity или слайс == конкретная фича/entity?

@karina-drummer
Слайс -- это feature / entity, да
Модель я так моделью и называю, она лишь часть слайса

@martis-git
Вот почему спрашиваю прост)

Привет редаксоидам и redux-toolkit

Т.е. слайс - это не всегда только про абстракцию, для нас редуксоидов - это значит и кое-что другое

https://redux-toolkit.js.org/api/createSlice

[azinit]

• Есть скорее ощущение что фраза "model == бизнес-логика" в контексте MVC - еще кажется логичной вполне
• Но когда мы погружаемся в дремучую разработку, где есть модели с API и другие термины (не только с MVC) - такое решение кажется уже не очень очевидным
  • Потому, например, слово view на фронте приходится использовать крайне редко

[binjospookie]

А если не model и не store, а struct?

Просто набрасываю

[azinit]

В вашей интерпретации, как дифференцировать работу с данными на инфраструктурный код (круд - тоже инфраструктура), бизнес-логику, UI логику и вспомогательные хелперы какие-то, к-ые идут как сквозные зависимости

Мы пока плюс-минус единогласно понимаем, что каждая абстракция-домен (app, pages, features, ...) может в себе содержать:

• api - логика запросов к API и возможно кеширования данных
• ui - логика отображения, обычно отображает и подписывается на изменение данных
• lib - логика инфраструктурная, необходимая для построения БЛ в других аспектах
• models - логика бизнеса, реализующая функционал через стейт, эффекты, реактивность и т.д.

Думаю сейчас все мы в core-team понимаем какие абстракции нужны в методологии и как их "разрезать"
Но по неймингу... Все еще пытаемся подобрать удачные названия, чтоб возникало меньше таких обширных тредов и вопросов
(я до сих пор не могу сказать что "за models", но при прочих равных скорее "не так уж и плохо")

[azinit]

Просто набрасываю

@binjospookie так победим)

Я вот тож хз уже какое название взять для модулей с "бизнес-логикой" (aka data-layer?)
#31 (comment)

[azinit]

Снова сцепились

@martis-git:
Если вот начистоту - то меня почти убедили касаемо ui (c коллегами тоже обсуждали, но там это не так критично)
И чуть поменьше убедили касаемо models - но там скорее "понимаю почему так, но хотелось бы получше название"

Мне бы наверное даже и зашло models, если бы только у нас еще своих моделей на фронте с БЛ не было

@karina-drummer
Модель это контекстонезависимая абстракция, которая одинаково используется как в бл, так и в чисто логике приложения
https://ru.wikipedia.org/wiki/Модель_данных

@martis-git

1. модель == аспект, отвечающий за логику в системе (MVC)
2. модель == ~сущность из бизнес-логики системы (БЛ)

вот эта коллизия меня наверн больше всего и убивает

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

@martis-git
Это как назвать папку "logic"
Очевидно, что будут абстракции, которые порождаются этим понятием
И из-за этого теряются наши относительные "явность", "очевидность", "простота"

[azinit]

shared vs common

[azinit]

Недавно пришлось поработать плотно с UNIX системами, и вспомнил - что даже там понятие shared используется гораздо чаще, когда мы говорим про "общие переиспользуемые ресурсы"

Само собой, речь даже не только про UNIX, а в целом про администрирование ресурсов и доступа

https://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.pdf

[azinit]

Нужно ли жестко фиксировать наименование для работы с данными?

models, store, state, data, ...

[azinit]

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

[azinit]

Хотелось бы, чтобы была одна папка {DATA_LAYER_NAME} со всей логикой домена, а в ней уже нужные абстракции, привязанные к реализации стейт-менеджмента и к тому- как это видит разработчик/архитектор:

- feature/auth-form
    - ui/
    - {DATA_LAYER_NAME}/
         -  index.ts
         -  *thunks
         -  *effects
         -  *slice
         -  *actions
         -  *controllers
         -  *epics
         -  *context
         -  ...

[sergeysova]

Так пусть она называется model?

- feature/auth-form
    - ui/
    - model/
         -  index.ts
         -  *thunks
         -  *effects
         -  *slice
         -  *actions
         -  *controllers
         -  *epics
         -  *context
         -  ...

[azinit]

@sergeysova вот почему)