Кратко — модульная, тестируемая и расширяемая архитектура строится по принципам «чистая/шестиугольная» (Ports & Adapters) + слоистая организация: Domain (ядро) → Application (use-cases / сервисы) → Adapters/Infrastructure (БД, внешние сервисы) → API / UI. Это даёт явное разделение ответственности, простую заменяемость реализаций и удобную инъекцию зависимостей.
Структура модулей и ответственности
- Domain (ядро, pure business logic)
- Сущности/агрегаты, value objects, доменные исключения, доменные события.
- Интерфейсы (порт) для репозиториев и внешних сервисов (например IAuthProvider, IUserRepository).
- Никаких зависимостей от инфраструктуры/UI.
- Application (use-cases)
- Сервисы / интеракторы: реализуют бизнес-логики операции (регистрация, логин, CRUD).
- DTO/порт-объекты для входа/выхода, валидаторы.
- Комбинируют Domain и порты (используют интерфейсы репозиториев/сервисов).
- Infrastructure / Adapters
- Реализации репозиториев (SQL/NoSQL), почтовых/файловых адаптеров, OAuth провайдеров.
- Веб/ORM адаптеры, миграции, реализация интерфейсов портов.
- Конфигурация DI контейнера связывает интерфейсы с реализациями.
- API (REST/GraphQL) / Controllers
- Тонкие контроллеры: принимают HTTP → преобразуют в DTO → вызывают use-case → возвращают ответ.
- Middleware для аутентификации/логирования/валидации.
- UI (SPA / Server-side)
- SPA: Flux/Redux архитектура (предсказуемый state, разделение view/state/actions).
- SSR/MVC: thin controllers + view templates, логика в приложении/use-cases.
Применяемые паттерны и почему
- Ports & Adapters (Hexagonal / Clean)
- Разделяет ядро от инфраструктуры; упрощает тестирование (моки для портов).
- Repository
- Абстрагирует доступ к данным; упрощает замену БД и unit-тесты.
- Dependency Injection (Constructor Injection)
- Инверсия зависимостей (Dependency Inversion из SOLID). Позволяет подменять реализации в тестах.
- Service / Use-Case (Application Services)
- Инкапсулируют единичную бизнес-операцию; соблюдают SRP.
- DTO / Mappers
- Отделяют внутренние доменные объекты от внешних контрактов API.
- Strategy
- Для выбора способов аутентификации (JWT, OAuth, Session) или внешних провайдеров.
- Adapter / Facade
- Для интеграции с внешними API (email, платежи) и упрощения интерфейсов.
- Unit of Work (при необходимости)
- Если нужна атомарность нескольких репозиторных операций; полезно при транзакциях.
- Observer / Event Bus (Domain Events)
- Асинхронные реакции на изменения в домене (отправка письма после регистрации).
- MVC (серверный) или Flux/Redux (клиент)
- MVC для простых серверных рендеров; Flux/Redux для SPA с предсказуемой логикой UI.
Как это реализует принципы SOLID
- Single Responsibility: отдельные модули для domain, use-cases, infra, API, UI.
- Open/Closed: добавление новых адаптеров/провайдеров без изменения кода ядра (через порты).
- Liskov: интерфейсы портов позволяют подставлять реализации, сохраняющие контракт.
- Interface Segregation: узкие специализированные интерфейсы (IUserRepo.ReadOnly, IUserRepo.Write).
- Dependency Inversion: high-level модули зависят от абстракций, не от конкретных библиотек.
Тестируемость — что и как тестировать
- Unit tests
- Тестировать домен и use-cases с моками для репозиториев/адаптеров.
- Контролируемые чистые функции — быстрые.
- Integration tests
- Контроллеры + реальные адаптеры к БД (in-memory/SQLite / testcontainers).
- Проверить транзакции, миграции, маршруты, middleware.
- Contract/API tests
- Проверять контракты API (например, Pact) между фронтом и бекендом.
- E2E tests
- Cypress / Playwright для полного потока (UI → API → БД).
- Component tests (UI)
- Тесты компонентов React/Redux с подменой стора и мокированием сервисов.
- Мок/Stub реализация портов для unit-тестов (через DI).
Пример потоков (схематично)
- Регистрация:
- API Controller принимает запрос → валидатор → Application service RegisterUser(use-case) → использует IUserRepository и IPasswordHasher → сохраняет, публикует DomainEvent(UserRegistered) → EventHandler (инфраструктура) отправляет письмо.
- Аутентификация:
- Auth middleware использует IAuthService (Strategy: JWT или Session). Контроллеры получают текущего пользователя через ICurrentUserPort.
Пример контрактов/интерфейсов (псевдо)
- interface IUserRepository { findById(id): User | null; findByEmail(email): User | null; save(user): void; }
- class RegisterUserUseCase { constructor(userRepo: IUserRepository, passwordHasher: IPasswordHasher) { ... } }
- Controller { constructor(registerUseCase: RegisterUserUseCase) { ... } }
Практический минимальный layout (пример)
- src/
- domain/
- entities/, valueObjects/, events/, ports/
- application/
- usecases/, dtos/, validators/
- infrastructure/
- db/, repos/, email/, authProviders/
- api/
- controllers/, middleware/, routes/
- ui/
- webapp/ (React + redux) или views/
- di/ (конфигурация контейнера)
- tests/ (unit, integration, e2e)
Дополнительные рекомендации
- Придерживаться контрактов (DTO, OpenAPI) — облегчает mock/генерацию кода.
- Логирование и мониторинг через отдельный adapter (не смешивать с бизнес-логикой).
- Не держать бизнес-правила в контроллерах/компонентах UI.
- Для маленького приложения можно не вводить CQRS/ES до тех пор, пока не появится сложность чтения/записи; начать с простых репозиториев и domain models.
Итого: используйте Clean/Hexagonal как опорную структуру, Repository + DI для доступа/замены реализаций, Service/Use-case слой для бизнес-логики, Flux/Redux для SPA UI, EventBus/Observers для асинхронных побочных эффектов. Это соблюдает SOLID, разделяет ответственности и обеспечивает удобное тестирование.