Capstone: типизированный, защищённый, протестированный API

Скелет: feature-модули поверх типизированного core

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

В сервисе, о котором можно рассуждать, два рода модулей. Feature-модули (OrdersModule, UsersModule) владеют одним срезом домена и следуют одной внутренней форме: Controller (HTTP-граница, без логики), Service (бизнес-операции, единственное место, где живут правила) и Repository (персистентность, типизированный Repository<T>). Единственный core-модуль владеет всем сквозным: типизированным ConfigModule, глобальным ValidationPipe, глобальным логирующим interceptor, глобальным exception filter, auth-guard и health-контроллером. Feature-модули импортируют core; ничто не импортирует внутренности feature-модуля.

Core-модуль — это место, где lifecycle привязывается один раз, через DI-осведомлённые токены-провайдеры, чтобы guard/filter/interceptor могли сами инжектить зависимости:

import { Module } from '@nestjs/common';
import { APP_GUARD, APP_PIPE, APP_FILTER, APP_INTERCEPTOR } from '@nestjs/core';
import { ConfigModule } from '@nestjs/config';
import { ValidationPipe } from '@nestjs/common';
import { JwtAuthGuard } from './auth/jwt-auth.guard';
import { AllExceptionsFilter } from './filters/all-exceptions.filter';
import { TransformInterceptor } from './interceptors/transform.interceptor';
import { validateEnv } from './config/env.validation';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true, validate: validateEnv }), // fail-fast на boot
  ],
  providers: [
    { provide: APP_GUARD, useClass: JwtAuthGuard },                  // authn на каждом маршруте
    {
      provide: APP_PIPE,
      useValue: new ValidationPipe({ whitelist: true, transform: true }),
    },
    { provide: APP_INTERCEPTOR, useClass: TransformInterceptor },     // конверт + тайминг
    { provide: APP_FILTER, useClass: AllExceptionsFilter },           // одна форма ошибки
  ],
})
export class CoreModule {}

whitelist: true срезает свойства без DTO-декоратора (защита от mass-assignment — атаки, при которой клиент передаёт лишние поля и перезаписывает данные, которые не должен трогать); transform: true превращает обычное JSON-тело в настоящий инстанс DTO и приводит примитивы. Привязка через токены APP_* — а не через app.useGlobalGuards() — держит эти глобалы внутри DI-контейнера, так что guard может инжектить Reflector, а filter — твой Logger.

Один запрос, фиксированный lifecycle как хребет

Каждый запрос проходит ту же цепочку, что ты выучил раньше, — теперь читай её как хребет всего дизайна. JwtAuthGuard (аутентификация) выполняется первым и читает метаданные @Public(), чтобы /health и /login могли отписаться. RolesGuard (авторизация) читает @Roles() и решает доступ — улажено до того, как разобрано любое тело. ValidationPipe заводит типизированный DTO внутрь. Хендлер тонкий: он зовёт сервис и возвращает. Service выполняет бизнес-операцию внутри dataSource.transaction, разделяя транзакционный EntityManager, так что каждая запись коммитится или откатывается вместе. Interceptor оборачивает ответ в конверт и снимает тайминг на выходе. AllExceptionsFilter формирует всё, что выброшено на любом этапе.

// orders.controller.ts — тонкая граница, без бизнес-логики
@Controller('orders')
export class OrdersController {
  constructor(private readonly orders: OrdersService) {}

  @Post()
  @Roles('customer')
  create(@Body() dto: CreateOrderDto, @CurrentUser() user: AuthUser) {
    return this.orders.place(dto, user.id); // DTO уже валидирован глобальным pipe
  }
}

// orders.service.ts — правила живут здесь, персистентность — в одной транзакции
@Injectable()
export class OrdersService {
  constructor(private readonly dataSource: DataSource) {}

  place(dto: CreateOrderDto, userId: string): Promise<OrderView> {
    return this.dataSource.transaction(async (manager) => {
      const repo = manager.getRepository(Order);                 // типизированный Repository<Order>
      const stock = await manager.findOne(Product, { where: { id: dto.productId } });
      if (!stock || stock.qty < dto.quantity) throw new ConflictException('out of stock');
      const order = repo.create({ userId, ...dto });
      await repo.save(order);                                    // та же tx, что и чтение остатка
      return toOrderView(order);                                 // domain -> response DTO
    });
  }
}

Хендлер никогда не видит ни транзакции, ни проверки роли, ни формы ошибки — они живут в своих слотах lifecycle. Сервис никогда не видит HTTP. В этом разделении весь смысл: каждый этап ссылается на нужный прежний урок — guards для authz, pipe для валидации, общий транзакционный менеджер для персистентности, interceptor для конверта, filter для ошибок.

Типы на границах, fail-fast на boot

Контракт этого сервиса — его типы, проверяемые там, где данные пересекают границу. Три DTO, не один: request DTO (валидированный вход), доменная сущность (то, что держит база) и response DTO (то, что видят вызывающие, — никогда не утекай сущностью). Конфиг тоже типизирован: registerAs плюс ConfigType даёт сервису строго типизированный срез вместо stringly-typed обращений к process.env, а validate отвергает плохое окружение на boot, а не при первом использовании.

// config/database.config.ts
import { registerAs, ConfigType } from '@nestjs/config';

export const databaseConfig = registerAs('db', () => ({
  url: process.env.DATABASE_URL!,
  poolSize: Number(process.env.DB_POOL_SIZE ?? 10),
}));
export type DatabaseConfig = ConfigType<typeof databaseConfig>;

// где-то в провайдере:
constructor(@Inject(databaseConfig.KEY) private readonly db: DatabaseConfig) {}
// db.poolSize — number, db.url — string — без `as`, без `process.env` на местах вызова

Чек-лист production-готовности — то сеньорское суждение, что отделяет «компилируется» от «доверяю на дежурстве»:

Все шесть пунктов образуют единую стратегию раннего падения: чем раньше проявляется неправильная конфигурация — на boot, а не при чекауте; на балансировщике, а не внутри запущенного пода — тем меньше радиус поражения. Пропустишь любой из них — именно эта ночь будет твоей дежурной.

Стратегия тестирования зеркалит слои: unit-тестируй сервисы с мокнутыми репозиториями — быстро, без БД, проверяя бизнес-правила в изоляции — и e2e-тестируй собранный pipeline (интеграционные тесты поверх реальной инфраструктуры) с реальной тестовой БД и реальным токеном, так что guard, pipe, транзакция, interceptor и filter все отрабатывают ровно как в проде.