DDD против реальности: распространённые ловушки и их решение в NestJS

Когда в команду приходят начинающие разработчики, а проект уже строился на архитектурных принципах, таких как Domain-Driven Design (DDD), иногда возникают сложности с их применением на практике. Даже при самых лучших намерениях результат может получиться далёким от идеала.

Мне не раз доводилось работать с проектами на NestJS, где DDD был задуман, но реализация оставляла вопросы: бизнес-логика оказывалась в контроллерах, сущности отвечали за доступ к базе данных, а Value Objects использовались скорее как формальность, без значимой роли в проекте.

На основе своего опыта я решил собрать несколько наиболее распространённых ошибок и дать простые рекомендации, которые помогут избежать подобных ситуаций. Моя цель — показать, как можно использовать подходы DDD в сочетании с архитектурой NestJS, сохраняя код ясным, структурированным и удобным для изменений.

«Domain-Driven Design» (DDD) — это подход к проектированию программного обеспечения, в центре которого находится предметная область (домен) и бизнес-логика. Суть DDD в том, чтобы создавать архитектуру, отражающую реальные бизнес-процессы, использовать единый язык общения со стейкхолдерами и структурировать код так, чтобы изменения в бизнес-требованиях минимально влияли на разработку.

В контексте JavaScript/TypeScript и фреймворков вроде NestJS (на бэкенде) у начинающих разработчиков часто возникает путаница: какие слои создавать, как выделять сущности, где хранить логику и как правильно организовать репозитории. В результате код либо чрезмерно усложнен, либо нарушает фундаментальные принципы DDD.

В этой статье мы:

• Разберем ключевые DDD-концепции (слои, сущности, Value Objects, доменные сервисы, репозитории) применительно к TypeScript-проектам.

• Покажем частые ошибки, которые совершают джуны при внедрении DDD в NestJS.

• Расскажем, как этих ошибок избежать, демонстрируя на простых примерах.

Основные концепции DDD для JS/TS-разработчиков

Ниже приведён краткий обзор ключевых концепций, которые используются при построении архитектуры в духе Domain-Driven Design.

Слои (Layers)

В классическом DDD традиционно выделяют несколько слоёв. Для JavaScript/TypeScript-проектов (на Node.js/NestJS) их можно представить так:

• Domain

  • Хранит доменные модели (Entities, Value Objects) и бизнес-логику (Domain Services).

  • Здесь описываются правила, которыми руководствуется бизнес, и основные операции над сущностями.

  • Обычно это набор классов (или функций), которые не зависят от инфраструктурных деталей (БД, внешние сервисы и т.п.).

• Application (Use Cases)

  • Использует объекты Domain и работает с инфраструктурой (репозиторией, внешними сервисами) для достижения конкретных целей (Use Cases).

  • В NestJS это могут быть сервисы/провайдеры, которые знают, как вызвать нужный репозиторий, как orchestrate несколько операций.

• Infrastructure

  • Отвечает за реализацию взаимодействия с базой данных, внешними сервисами (шлюз платежей, почтовые сервисы и т. д.).

  • Хранит конкретные реализации репозиториев, клиентов для HTTP-запросов и прочую низкоуровневую логику.

• Interface (или Presentation)

  • Слой, который отвечает за взаимодействие с пользователем: UI-компоненты во фронтенде, REST-роуты или GraphQL-резольверы на бэкенде.

  • В NestJS это контроллеры (@Controller())

Важная идея: каждый слой имеет свою зону ответственности и по возможности не пересекается напрямую с другими слоями. Таким образом, вы можете менять детали инфраструктуры (например, перейти с MongoDB на PostgreSQL) без глобального рефакторинга бизнес-логики.

Entities и Value Objects

• Entity — объект, у которого есть уникальный идентификатор (например, id). Его состояние может меняться со временем (например, заказ может изменять статус).

• Value Object — объект без уникального идентификатора; он ценен своими значениями, а не личностью. Пример: Email, Money, Discount. Если в Email меняется одно из полей (например, адрес), мы обычно создаём новый объект Email, а не меняем старый.

В TypeScript мы можем оформлять Entity и Value Object как обычные классы. Например:

// Пример сущности (Entity) class Order {   private id: string;   private status: OrderStatus;   private items: OrderItem[]; // OrderItem - может быть Value Object    constructor(id: string) {     this.id = id;     this.status = OrderStatus.DRAFT;     this.items = [];   }    // Бизнес-методы, меняющие состояние   addItem(item: OrderItem) { /* ... */ }   pay() { /* ... */ } }  // Пример Value Object class OrderItem {   constructor(     private readonly productId: string,     private readonly quantity: number,     private readonly price: number   ) {     if (quantity <= 0) {       throw new Error('Quantity must be positive');     }   }    get total(): number {     return this.quantity * this.price;   } } 

Domain Services

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

class CommissionService {   calculateCommission(user: User, transaction: Transaction): number {     // сложные бизнес-правила     return /* ... */;   } } 

Repository

Это посредник между доменными моделями и базой данных (или другими хранилищами). В DDD часто используют интерфейс репозитория в доменном слое, а реальную реализацию помещают в инфраструктурный слой.

// Domain (интерфейс репозитория) export interface OrderRepository {   save(order: Order): void;   findById(id: string): Order | null; }  // Infrastructure (реальная реализация) @Injectable() export class InMemoryOrderRepository implements OrderRepository {   private storage: Record<string, string> = {};    save(order: Order): void {     this.storage[order.getId()] = JSON.stringify(order);   }    findById(id: string): Order | null {     const data = this.storage[id];     return data ? JSON.parse(data) : null;   } } 

Частые ошибки новичков при внедрении DDD

Ниже перечислены некоторые распространённые ошибки, с которыми сталкиваются начинающие специалисты, пытаясь интегрировать DDD в NestJS-проекты.

Избыточная абстракция

Симптом: разработчик стремится по всем канонам оформить свой код, в итоге появляются десятки модулей, слоёв, классов и интерфейсов, которые лишь запутывают логику и усложняют поддержку.

Почему это происходит:

• Желание сделать всё по учебнику без учёта реальных требований.

• Непонимание, какие элементы DDD действительно нужны проекту, а какие нет.

Как проявляется в NestJS:

• Создание слишком большого количества модулей, даже когда бизнес-домен очень небольшой.

• Чрезмерное дробление сервисов (вместо одного Domain Service — три-четыре мелких).

• Выделение Value Object там, где достаточно примитивных типов.

Нарушение принципа единственной ответственности (SRP)

Симптом: класс (будь то Entity или Service) начинает выполнять сразу несколько задач. Например, и осуществляет доступ к базе, и проверяет входные данные, и реализует бизнес-логику.

Почему это происходит:

• Путают Application Layer (или Service в NestJS) с Domain Service.

• Не умеют чётко разделить обязанности между слоями.

Как проявляется в NestJS:

• Контроллер начинает содержать и бизнес-логику, и валидацию, и вызовы к базе данных напрямую.

• Сервис смешивает в себе методы для чтения/записи (репозиторий) и бизнес-логику (доменные операции), превращаясь в комбайн.

Неправильная (или отсутствующая) граница контекста

Симптом: весь код складывается в один глобальный модуль, и никакого намёка на Bounded Context нет. В результате трудно понять, какой код к чему относится, и как части системы взаимодействуют.

Почему это происходит:

• Неудобство или непонимание, как распределять функциональность по контекстам.

• Желание упростить структуру, чтобы не городить огород из нескольких модулей.

Как проявляется в NestJS:

• Есть один-единственный модуль AppModule, в котором лежит вся логика, даже если предметная область комплексная.

• Отсутствуют чёткие границы между разными модулями, отвечающими за разные поддомены.

Использование DDD чисто для галочки

Симптом: файл domain.ts, в котором вроде бы описаны Entities, а по факту там класс ради класса. Или Value Object, который не содержит никакой логики, а просто один кортеж полей.

Почему это происходит:

• При желании выглядеть хорошо в глазах руководства или коллег, разработчик механически создаёт доменные классы, не вникая, нужна ли там реальная бизнес-логика.

Как проявляется в NestJS:

• Мнимый DomainModule, где всё сводится к DTO для контроллеров и пустым классам вместо настоящих Entities.

Складывание всей логики в контроллер

Симптом: пытаясь быстро выдать результат или не понимая, как распределить слои, джун начинает лепить всю логику прямо в контроллеры: валидацию, вычисления, взаимодействие с базой, конвертацию данных, бизнес-правила.

Почему это происходит:

• Недостаток опыта в построении многослойной архитектуры.

• Стремление сразу всё сделать в одном месте.

Как проявляется в NestJS:

• Логика обработки запроса, проверки прав пользователя и даже работа с базой — всё в одном методе @Controller().

Отсутствие языка домена

Симптом: разработчик не общается с бизнес-экспертами, не уточняет терминологию. Как итог, названия классов, методов, модулей не совпадают с реальными терминами предметной области и запутывают всех вокруг.

Почему это происходит:

• Желание закодить побыстрее, без глубокой проработки бизнес-логики.

• Недопонимание важности Ubiquitous Language.

Как проявляется в NestJS:

• Сущности называются EntityOne, EntityTwo вместо Order, Product. Или модули ModuleA, ModuleB — непонятно, что в них лежит.

Как избежать этих ошибок, используя возможности NestJS

Ниже приведены рекомендации, которые помогут вам сделать код более аккуратным и соответствующим принципам DDD.

• Грамотная организация модулей. Делите приложение на модули, отражающие разные бизнес-контексты (если домен достаточно велик). Например, OrdersModule, PaymentsModule, UsersModule. NestJS-модуль служит естественной границей для Bounded Context или поддомена. Это упрощает масштабирование и поддержку кода, так как каждая область ответственности изолирована.

• Разделяйте слои приложения

  • Контроллеры (Controllers) — принимают запрос, вызывают соответствующий сервис, возвращают ответ.

  • Сервисы приложения (Application Services) — обеспечивают поток данных между внешним миром (API, UI) и доменным слоем. Здесь могут решаться задачи оркестрации (вызывают несколько доменных сервисов или репозиториев последовательно).

  • Доменный слой (Domain Layer) — хранит в себе Entities, Value Objects, Domain Services (бизнес-операции, связанные с несколькими сущностями).

  • Инфраструктурный слой (Infrastructure Layer) — реализация конкретных репозиториев (доступ к базе данных, сторонним API и т. п.), провайдеры, интеграция с другими системами.

• Используйте Value Objects там, где есть реальный смысл. Если в вашем коде есть сложный тип, такой как денежная сумма (валюта + значение), и вам необходимы операции преобразования, округления или проверки валидности, создайте для этого Value Object. Не используйте Value Object для простых типов, например, имени пользователя, если там нет особой логики проверки.

• Соблюдайте принцип единой ответственности (SRP). Каждый класс должен выполнять одну задачу и выполнять её хорошо. Например, Entity отвечает за данные, Domain Service — за бизнес-логику, а Infrastructure Service — за взаимодействие с внешними системами. Используйте Dependency Injection в NestJS для четкого разделения обязанностей между провайдерами.

• Поддерживайте единый язык домена. Работайте в тесном взаимодействии с бизнес-командой, чтобы понять, как называются сущности и какую функциональность они ожидают. Присваивайте классам, методам и модулям понятные и осмысленные названия, чтобы они были понятны не только разработчикам, но и доменным экспертам.

• Не усложняйте сверх меры. Если ваш проект небольшой или является MVP, избегайте избыточной сложности в виде множества слоёв и паттернов. Добавляйте элементы DDD постепенно, по мере роста и усложнения доменной области, чтобы не перегружать архитектуру.

Небольшой пример структуры в NestJS

Рассмотрим упрощённую структуру модуля Заказы (OrdersModule), демонстрирующую организацию слоёв по DDD-принципам.

orders ├── application │   └── order.service.ts         # OrderApplicationService ├── domain │   ├── entities │   │   └── order.entity.ts      # Order Entity │   ├── services │   │   └── order.domain-service.ts  # (опционально) логика, не привязанная к конкретной сущности │   └── value-objects │       └── order-item.vo.ts     # Пример Value Object ├── infrastructure │   └── order.repository.ts      # Реализация репозитория ├── interfaces │   └── order.controller.ts      # Контроллер для Orders └── orders.module.ts

Пример Entity и Value Object

// domain/entities/order.entity.ts export class Order {   private status: OrderStatus;   private items: OrderItem[];    constructor(private readonly id: string) {     this.status = OrderStatus.DRAFT;     this.items = [];   }    addItem(item: OrderItem) {     if (this.status !== OrderStatus.DRAFT) {       throw new Error('Cannot add items to a non-draft order');     }     this.items.push(item);   }    pay() {     if (this.items.length === 0) {       throw new Error('Cannot pay for an empty order');     }     this.status = OrderStatus.PAID;   }    // ... другие бизнес-методы } 

// domain/value-objects/order-item.vo.ts export class OrderItem {   constructor(     readonly productId: string,     readonly quantity: number,     readonly price: number,   ) {     if (quantity <= 0) {       throw new Error('Quantity must be positive');     }   }    get total(): number {     return this.quantity * this.price;   } } 

Пример репозитория и сервиса приложения

// infrastructure/order.repository.ts import { Injectable } from '@nestjs/common'; import { Order } from '../domain/entities/order.entity';  @Injectable() export class OrderRepository {   private storage: Record<string, string> = {};    save(order: Order) {     this.storage[order['id']] = JSON.stringify(order);   }    findById(id: string): Order | null {     const data = this.storage[id];     return data ? JSON.parse(data) : null;   } } 

// application/order.service.ts import { Injectable } from '@nestjs/common'; import { OrderRepository } from '../infrastructure/order.repository'; import { Order } from '../domain/entities/order.entity'; import { OrderItem } from '../domain/value-objects/order-item.vo';  @Injectable() export class OrderService {   constructor(private readonly orderRepository: OrderRepository) {}    createOrder(orderId: string): Order {     const order = new Order(orderId);     this.orderRepository.save(order);     return order;   }    addItem(orderId: string, productId: string, quantity: number, price: number): Order {     const order = this.orderRepository.findById(orderId);     if (!order) throw new Error('Order not found');     order.addItem(new OrderItem(productId, quantity, price));     this.orderRepository.save(order);     return order;   }    payOrder(orderId: string): Order {     const order = this.orderRepository.findById(orderId);     if (!order) throw new Error('Order not found');     order.pay();     this.orderRepository.save(order);     return order;   } } 

Контроллер (Interface Layer)

// interfaces/order.controller.ts import { Controller, Post, Param, Body } from '@nestjs/common'; import { OrderService } from '../application/order.service';  @Controller('orders') export class OrderController {   constructor(private readonly orderService: OrderService) {}    @Post('create/:id')   createOrder(@Param('id') orderId: string) {     return this.orderService.createOrder(orderId);   }    @Post(':id/add-item')   addItem(     @Param('id') orderId: string,     @Body() body: { productId: string; quantity: number; price: number },   ) {     return this.orderService.addItem(orderId, body.productId, body.quantity, body.price);   }    @Post(':id/pay')   payOrder(@Param('id') orderId: string) {     return this.orderService.payOrder(orderId);   } } 

Модуль

// orders.module.ts import { Module } from '@nestjs/common'; import { OrderService } from './application/order.service'; import { OrderController } from './interfaces/order.controller'; import { OrderRepository } from './infrastructure/order.repository';  @Module({   controllers: [OrderController],   providers: [OrderService, OrderRepository], }) export class OrdersModule {} 

Такой подход позволяет чётко определить роли разных компонентов и упростить сопровождение. При необходимости вы можете заменять OrderRepository на более сложную реализацию (SQL, MongoDB, внешние API), не меняя код доменных сущностей.

Советы для упрощения внедрения DDD в NestJS

• Не пытайтесь внедрить все паттерны из книги Эрика Эванса сразу. Начинайте с малого! Пусть архитектура растёт вместе с бизнес-требованиями.

• Используйте чистые сущности. Доменные классы (Entities, Value Objects) желательно делать независимыми от фреймворка NestJS. Это упростит тестирование и переиспользование.

• Чётко разделяйте слои! NestJS уже подталкивает к модульному разделению кода, пользуйтесь этим. Разделяйте Application Services и Domain Services, а также храните репозитории в инфраструктуре.

• Согласовывайте термины с бизнес-экспертами и используйте эти же названия в коде. Следуйте Ubiquitous Language.

• Проводите рефакторинг по мере роста. Требования и понимание домена будут меняться — будьте готовы адаптировать архитектуру.

• Не стесняйтесь задавать вопросы❗️ Спрашивайте коллег, участвуйте в обсуждениях архитектуры, ищите подходящие решения под ваши конкретные задачи.

Итог

DDD — это не серебряная пуля, а набор гибких принципов, которые помогают сконцентрироваться на сути бизнеса и строить код, отражающий реальные процессы. В сочетании с NestJS, предоставляющим удобный механизм модулей, контроллеров и сервисов, можно выстроить логичную и поддерживаемую архитектуру.

Однако при неправильном или чрезмерно формальном подходе DDD может обернуться избыточными абстракциями, нарушением принципов SRP и хаосом в коде. Следуйте рекомендациям описанным в статье и тогда ваша кодовая база будет гибкой, расширяемой и понятной, а любые изменения в бизнес-требованиях обернутся лишь локальными правками в соответствующих областях системы.

Удачи в освоении Domain-Driven Design в NestJS!🚀