Модули, контроллеры, провайдеры

Контроллеры: тонкие обработчики запросов

Controller — это HTTP-фасад приложения. Декоратор @Controller('users') объявляет префикс route; декораторы методов вроде @Get(), @Post(), @Patch(':id'), @Delete(':id') сопоставляют обработчики с глаголами и под-путями. Параметрические декораторы достают вход из запроса: @Param('id') — сегменты пути, @Query() — query-строку, @Body() — распарсенный JSON-пейлоад. Что бы обработчик ни вернул, становится телом ответа, сериализованным за тебя.

Дисциплина, отделяющая junior-controller от senior-варианта, — тонкость. Controller должен переводить HTTP в вызов метода и переводить результат обратно в HTTP — и не более. Валидация, бизнес-правила, персистентность, оркестрация — всё это принадлежит provider-у. Когда controller начинает гонять запросы к базе или ветвиться на бизнес-состоянии, он перестаёт быть адаптером и становится god-объектом, который нельзя переиспользовать вне HTTP и нельзя протестировать без поднятия всего пайплайна запроса.

import { Controller, Get, Post, Param, Body } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';

@Controller('users')
export class UsersController {
  // Сервис инжектится, а не конструируется. Controller никогда не делает new.
  constructor(private readonly usersService: UsersService) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(id); // делегируй, верни, всё
  }

  @Post()
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
}

Провайдеры: логика, которую инжектят

Зачем не класть бизнес-логику прямо в controller? Потому что тогда ты теряешь возможность тестировать её без HTTP, переиспользовать из consumer очереди и подменять в тестах на фейк. Injectable provider-ы решают все три проблемы сразу.

Provider — это любой класс, который Nest может инстанцировать и выдать тому, кто его просит. Декоратор @Injectable() помечает класс как кандидата для контейнера dependency injection (DI). Самый частый provider — это сервис с бизнес-логикой, но репозитории, фабрики, HTTP-клиенты и config-объекты тоже provider-ы. Определяющая черта в том, что ты никогда не вызываешь new UsersService() сам — ты объявляешь зависимость в конструкторе, а Nest разрешает и поставляет её.

Именно это делает controller выше тестируемым: в unit-тесте ты инстанцируешь UsersController с фейковым UsersService, без HTTP и без базы. DI-контейнер читает типы параметров конструктора, находит подходящий provider в области видимости и инжектит единственный общий инстанс (provider-ы по умолчанию синглтоны в своей области).

import { Injectable, NotFoundException } from '@nestjs/common';

@Injectable()
export class UsersService {
  private readonly users = new Map<string, { id: string; name: string }>();

  findOne(id: string) {
    const user = this.users.get(id);
    if (!user) throw new NotFoundException(`User ${id} not found`);
    return user;
  }

  create(dto: { name: string }) {
    const id = crypto.randomUUID();
    const user = { id, name: dto.name };
    this.users.set(id, user);
    return user;
  }
}

Модули: группировка и граница инкапсуляции

Module — это организующая единица. Декоратор @Module() принимает четыре массива: controllers (объявленные здесь), providers (инстанцируемые и доступные внутри этого module), imports (другие module-и, чьи exports этот module хочет использовать) и exports (то подмножество provider-ов этого module, которое другим module-ам разрешено потреблять). У каждого Nest-приложения есть корневой AppModule; всё остальное — feature-модули, которые ты в него ввязываешь.

import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService], // <-- без этого ни один другой module не сможет инжектить UsersService
})
export class UsersModule {}

Вот правило, которое нарушил хук, прямым текстом: provider приватен для своего module, если он не указан в exports. Объявление UsersService в providers делает его инжектируемым в UsersController внутри UsersModule — и больше нигде. Если OrdersModule хочет UsersService, должны быть истинны две вещи: UsersModule обязан export его, а OrdersModule обязан import UsersModule. Промахнись хоть в одной половине — и получишь ошибку Nest can't resolve dependencies. Фикс — никогда не пере-перечислять provider в потребляющем module (это создаёт второй, отдельный инстанс и тихо ломает общее состояние) — а экспортировать из владельца и импортировать владельца.

Это даёт тебе два вида module-ей, которые ты будешь строить постоянно. Feature-модуль владеет одним срезом домена (users, orders, billing) и экспортирует только то, что другим действительно нужно. Shared-модуль упаковывает сквозные provider-ы — соединение с базой, логгер, config-сервис — и экспортирует их, чтобы многие feature-модули импортировали одну и ту же обвязку. Когда shared-provider нужен почти везде, можно пометить его module как @Global(), но это осознанный аварийный выход, а не дефолт: глобализировать всё — значит выбросить ту инкапсуляцию, ради которой ты пришёл.