DSA

Appearance

Введение ​

DSA — это набор архитектурных правил, который помогает каждый день отвечать на два вопроса:

  1. Кому принадлежит этот код?
  2. В какую сторону может идти зависимость?

Главная цель DSA — не навязать как можно больше библиотек. Наоборот, документация разделяет архитектуру и конкретный проектный стек.

Как устроена эта документация ​

Есть три уровня.

txt
DSA Core
   ↓
Full Stack Guide
   ↓
Example project

1. DSA Core ​

Core описывает правила вокруг:

  • React;
  • React Router;
  • MobX;
  • mobx-react-lite;
  • React Hook Form;
  • Valibot;
  • @hookform/resolvers.

Здесь разбираются слои, зависимости, stores, формы, public API и внешняя граница данных.

2. Full Stack Guide ​

Full Stack Guide показывает, как те же правила реализуются в принятом полном стеке.

Там появляются:

  • Axios;
  • HTTP facade;
  • application adapters;
  • dayjs;
  • clsx;
  • Sass / CSS Modules;
  • EventBus и WebSocket-подобные механизмы;
  • application Error Boundary.

Эти инструменты не превращаются в требования DSA. Они остаются выбранной реализацией.

3. Example project ​

Example project — отдельный блог, где можно увидеть структуру целиком, а не по фрагментам.

Зачем нужна DSA ​

Без явных границ один сценарий быстро размазывается по проекту:

  • React-компонент сам получает данные;
  • там же преобразует внешний ответ;
  • рядом хранит loading;
  • другой компонент повторяет часть логики;
  • форма начинает зависеть от серверного DTO;
  • инфраструктурная библиотека начинает диктовать структуру data.

DSA разделяет эти роли.

txt
внешние данные
     ↓
data: Valibot → mapper → MobX store
     ↓
components: smart React-компонент
     ↓
components/ui: отображение через props
     ↓
pages: композиция экрана
     ↓
app: React Router и корневая композиция

Что такое data-slice ​

data-slice — самостоятельная часть слоя data, у которой есть понятный владелец.

Для блога таким владельцем может быть posts:

txt
data/posts/
  posts.schema.ts
  posts.dto.ts
  posts.mapper.ts
  posts.store.ts
  posts.types.ts
  index.ts

Внутри находятся контракты внешних данных, преобразование, состояние и действия. React-компоненты используют public API slice и не зависят от его внутренних файлов.

Базовые слои ​

txt
app         запуск приложения, Router, корневая композиция
pages       страницы маршрутов
components  переиспользуемый продуктовый UI
data        данные, schemas, mappers, MobX stores
shared      универсальный код без знания домена

Главная идея: владение важнее типа файла.

post.mapper.ts лежит рядом с posts, потому что именно posts владеет этим преобразованием. То, что mapper является «утилитой», не делает его shared.

Один домен для всей документации ​

Все учебные примеры строятся вокруг блога:

  • posts — список и отдельный пост;
  • authors — авторы;
  • comments — комментарии;
  • post-editor — создание и редактирование;
  • /posts/:postId — страница поста.

Так читатель изучает архитектуру, а не новый бизнес-контекст на каждой странице.

В каком порядке читать ​

Для первого знакомства:

  1. Scope Core
  2. Быстрый старт
  3. Обзор слоёв
  4. Контракты и Valibot
  5. MobX stores
  6. Куда класть код
  7. Full Stack Guide
  8. Example project

Как читать правила ​

Если страница находится в Core, формулировка означает:

Это архитектурное правило DSA в рамках заявленного Core scope.

Если страница находится в Full Stack Guide, формулировка означает:

Так правило DSA реализуется в нашем полном стеке.

Это различие важнее конкретных названий папок и библиотек.