Архитектура проекта

01Слои: у каждой части одна задача

Представьте ресторан. Официант принимает заказ (HTTP-слой), шеф решает, как его готовить (бизнес-слой), на складе хранятся продукты (слой данных). Официант никогда не готовит, а шеф никогда не общается с гостями. В коде: контроллеры или обработчики маршрутов разбирают запрос и возвращают ответ; сервисы или use cases применяют бизнес-правила; репозитории или ORM-модели читают и пишут данные. Зависимости направлены внутрь: контроллер знает о сервисе, сервис знает о слое данных, но бизнес-логика ничего не знает про HTTP. Благодаря этому одну и ту же логику можно переиспользовать из API, CLI-команды, задачи в очереди или теста.

• Presentation: контроллеры, валидация запросов, форматирование ответов.
• Application: сервисы или use cases, которые оркестрируют задачу (PlaceOrder, RefundPayment).
• Domain: сущности, value objects и правила (Money, переходы OrderStatus).
• Infrastructure: база данных, очереди, платёжные шлюзы, почтовые провайдеры.

02Сервисы, use cases и DTO

Сервис объединяет связанные операции одного домена (OrderService). Use case, или экшен, — это одна операция с понятным названием (PlaceOrder). Оба принимают простой ввод и возвращают простой результат. Этот ввод — DTO, Data Transfer Object: небольшой типизированный объект, который описывает ровно те поля, которые принимает операция. DTO не дают сырым массивам из запроса просочиться в бизнес-логику и делают контракт очевидным. Валидируйте на границах: проверяйте форму и типы там, где данные входят в систему (HTTP-запрос, вебхук, импорт CSV, сообщение из очереди), а внутри доверяйте DTO. Бизнес-правила вроде «отменённый заказ нельзя оплатить» всё равно живут в домене, потому что они не про форму ввода.

1// Edge: validate and map to a DTO
2export const CreateOrderSchema = z.object({
3  branchId: z.string().uuid(),
4  items: z.array(z.object({ productId: z.string().uuid(), qty: z.number().int().min(1) })).min(1),
5});
6export type CreateOrderDto = z.infer<typeof CreateOrderSchema>;
7 
8// Use case: business logic only, no HTTP
9export class PlaceOrder {
10  constructor(private orders: OrderRepository, private pricing: PricingService) {}
11 
12  async execute(companyId: string, dto: CreateOrderDto) {
13    const quote = await this.pricing.quote(companyId, dto.items);
14    return this.orders.create({ companyId, branchId: dto.branchId, ...quote });
15  }
16}

03Структура папок: по доменам, а не по типам файлов

Небольшие приложения можно группировать по типу: все контроллеры в одной папке, все модели — в другой. Когда фич становится больше двадцати, это начинает мешать: одно изменение затрагивает пять далёких друг от друга папок. Группировка по доменам — её ещё называют feature-папками или модулями — держит всё, что касается заказов, вместе. Каждый модуль открывает наружу небольшой публичный интерфейс (сервис, несколько типов) и скрывает остальное. Общий сквозной код (авторизация, логирование, хелперы для денег) кладётся в папку shared или core. В Laravel можно сохранить стандартные папки фреймворка и добавить доменные подпапки внутри Models и Services; в NestJS модули естественно ложатся на эту схему.

1src/
2  modules/
3    orders/
4      orders.controller.ts
5      orders.service.ts
6      dto/create-order.dto.ts
7      orders.module.ts
8    menu/
9    loyalty/
10  shared/
11    auth/  logging/  money/
12  config/
13    env.ts

04Отдельные API для веба, мобильного приложения и админки

У одного бэкенда часто три аудитории. Публичному сайту, мобильному приложению и админке нужны разные формы ответов, разная авторизация (сессия на cookie, токен, вход для персонала с 2FA), разные лимиты запросов и разные циклы релизов: версия мобильного приложения может прожить на телефонах год, поэтому его API должен сохранять обратную совместимость. Хороший паттерн — отдельные группы маршрутов или контроллеры для каждого канала, которые вызывают одни и те же сервисы. Клиентские фичи, одинаковые для веба и мобильного приложения, можно описать один раз и смонтировать под обоими префиксами. Эндпоинты админки живут в своей группе со строгими правами и аудит-логом. Версионируйте мобильный API явно (v1, v2), чтобы безопасно его развивать.

05Монорепозитории, конфиг и окружение

Монорепозиторий хранит несколько приложений и пакетов в одном репозитории: api, web, admin, mobile, а также общие пакеты — типы, API-клиент, UI-компоненты или конфиг ESLint. pnpm workspaces связывают пакеты локально, а Turborepo (или Nx) запускает задачи в порядке зависимостей с кэшированием, так что пересобирается и тестируется только то, что изменилось. Конфигурация должна следовать правилу twelve-factor: код везде одинаковый, различается окружение. Читайте переменные окружения один раз при старте, валидируйте их по схеме и падайте сразу, если чего-то не хватает. Никогда не коммитьте .env-файлы; вместо этого коммитьте .env.example с плейсхолдерами.

1# pnpm-workspace.yaml
2packages:
3  - "apps/*"
4  - "packages/*"
5 
6# turbo.json
7{
8  "tasks": {
9    "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] },
10    "test": { "dependsOn": ["^build"] },
11    "lint": {}
12  }
13}

06Как сохранить архитектуру здоровой со временем

Архитектура разрушается по одному «срезанному углу» за раз. Защищайте её правилами, которые проверяют инструменты: lint-правила или dependency-cruiser, запрещающие одному модулю импортировать внутренности другого, strict-режим TypeScript и тесты на уровне сервисов. Когда принимаете крупное решение, пишите короткую архитектурную заметку (ADR, Architecture Decision Record), чтобы следующий человек понимал, почему так. Начинайте с модульного монолита: одно деплоящееся приложение с чёткими границами модулей. Разделить его на сервисы позже легко, если границы чистые, и почти невозможно, если нет. Рефакторьте постоянно и маленькими шагами, а не планируйте одно большое переписывание.

07Границы закрепляются инструментами, а не благими намерениями

Диаграмма в вики не остановит уставшего разработчика в 6 вечера от импорта внутреннего репозитория чужого модуля. Упавшая проверка в CI — остановит. В TypeScript dependency-cruiser проверяет правила импортов по всему проекту, а в Nx есть lint-правило enforce-module-boundaries для воркспейсов. В PHP Deptrac описывает слои и разрешённые зависимости, а архитектурные тесты Pest выражают правила как тесты, например «контроллеры не могут использовать фасад DB». Хороший первый набор правил небольшой: модули могут импортировать только публичный входной файл другого модуля; доменный код не может импортировать HTTP- и фреймворковые классы; общий код не может импортировать из модулей. Добавьте правила в CI в режиме предупреждений, исправьте существующие нарушения, затем переключите на ошибки. Каждое новое правило должно описывать реальную проблему, которая у вас была, а не теоретическую цель чистоты.

1// .dependency-cruiser.cjs
2module.exports = {
3  forbidden: [
4    {
5      name: 'no-cross-module-internals',
6      comment: 'Import other modules only through their index.ts',
7      severity: 'error',
8      from: { path: '^src/modules/([^/]+)/' },
9      to: {
10        path: '^src/modules/[^/]+/',
11        pathNot: ['^src/modules/$1/', '^src/modules/[^/]+/index[.]ts$'],
12      },
13    },
14    { name: 'shared-stays-generic', severity: 'error', from: { path: '^src/shared/' }, to: { path: '^src/modules/' } },
15  ],
16};

08Моделирование домена: инварианты, агрегаты и машины состояний

Инвариант — правило, которое всегда должно быть истинным: сумма заказа равна сумме его строк, возвращённый заказ нельзя оплатить. Агрегат — группа объектов, которая вместе защищает такие правила, например заказ со своими строками, и меняется он только через собственные методы, никогда через прямое редактирование строки откуда-то извне. Поля статусов — место, где прячется большинство багов, поэтому моделируйте их как явные машины состояний: таблица разрешённых переходов и одна функция, которая их применяет. Тогда на вопрос «можно ли вернуть деньги за отменённый заказ?» есть один ответ в одном месте, и можно протестировать каждую пару. Добавьте к этому value objects для денег (целые минорные единицы плюс валюта) и количеств — и многие классы багов, например ошибки округления float или отрицательные остатки, исчезают по построению.

1type OrderStatus = 'draft' | 'placed' | 'paid' | 'fulfilled' | 'cancelled' | 'refunded';
2 
3const allowed: Record<OrderStatus, OrderStatus[]> = {
4  draft: ['placed', 'cancelled'],
5  placed: ['paid', 'cancelled'],
6  paid: ['fulfilled', 'refunded'],
7  fulfilled: ['refunded'],
8  cancelled: [],
9  refunded: [],
10};
11 
12export function transition(order: Order, to: OrderStatus): Order {
13  if (!allowed[order.status].includes(to)) {
14    throw new DomainError('Cannot move order from ' + order.status + ' to ' + to);
15  }
16  return { ...order, status: to, version: order.version + 1 };
17}

09Как общаются модули: прямые вызовы, события и read models

Модули должны сотрудничать, не зная внутренностей друг друга. Используйте прямой вызов публичного сервиса другого модуля, когда ответ нужен сейчас, например checkout запрашивает у pricing расчёт цены. Используйте доменное событие, когда что-то произошло и другие могут отреагировать, например OrderPaid запускает начисление бонусных баллов, письмо с чеком и движение остатков; модулю заказов не нужно знать, кто слушает. Внутри одного процесса события можно отправлять после коммита; как только слушатели живут в другом процессе, записывайте их в outbox в той же транзакции. Избегайте ситуации, когда два модуля пишут в одну таблицу, потому что тогда ни один из них не владеет правилами. Отчёты, которым нужны данные многих модулей, — особый случай: стройте read model, денормализованную таблицу, обновляемую из событий или ночной задачей, вместо одного гигантского запроса, соединяющего таблицы всех модулей.

• Команда: «сделай это» одному владельцу, может не выполниться, требует ответа.
• Событие: «это произошло», ноль или больше слушателей, название в прошедшем времени.
• Read model: копия, оптимизированная под запросы, согласованная в конечном счёте и пересобираемая из источника истины.

10Изменение легаси-систем: швы, strangler fig и anti-corruption layers

Переписывания «большим взрывом» обычно проваливаются: старая система продолжает меняться, а новая за ней гонится. Паттерн strangler fig заменяет систему по частям. Поставьте впереди слой маршрутизации, например reverse proxy или роутер нового приложения, переносите по одному эндпоинту или экрану за раз, а остальное отправляйте в старый код, пока от него ничего не останется. Прежде чем трогать рискованный код, напишите characterization tests, которые фиксируют, что он делает сегодня, даже если это поведение выглядит неправильным, чтобы рефакторинг менял структуру, а не результаты. Когда новому коду нужно общаться с легаси-моделью или внешней ERP со странными названиями и правилами, поставьте между ними anti-corruption layer: переводчик, который отображает их понятия в ваши, чтобы их беспорядок не протекал в ваш домен. Feature flags позволяют переключать трафик постепенно и мгновенно откатываться.