Кастомные pipe и стадия трансформации

Что такое pipe на самом деле

Pipe — это класс, реализующий PipeTransform<T, R>: один метод, transform(value: T, metadata: ArgumentMetadata): R. Nest запускает его на одном аргументе хендлера, прямо перед тем, как хендлер выполнится, — после guards и pre-фазы интерсепторов, но это последнее, что трогает аргумент на входе. У pipe ровно две работы: трансформация (вернуть приведённое значение, например "42" → 42) и валидация (выбросить, чтобы отклонить запрос, что Nest превратит в 400). Он либо возвращает (возможно, преобразованное) значение, либо выбрасывает; третьего исхода нет.

import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';

// A hand-written equivalent of ParseIntPipe: this is all a built-in pipe is.
@Injectable()
export class ParseIntPipeManual implements PipeTransform<string, number> {
  transform(value: string, _metadata: ArgumentMetadata): number {
    const n = Number(value);
    if (!Number.isInteger(n)) {
      throw new BadRequestException(`Validation failed: "${value}" is not an integer`);
    }
    return n; // the handler now receives a number, not a string
  }
}

Второй аргумент, metadata: ArgumentMetadata, — это то, что делает pipe больше, чем тупым конвертером. Он несёт { type, metatype, data }:

• type — откуда пришёл этот аргумент: 'body', 'query', 'param' или 'custom'.
• metatype — объявленный класс аргумента (CreateUserDto, Number, String…). Именно так ValidationPipe узнаёт, против какого DTO валидировать — он читает metatype с аннотации типа параметра через reflect-metadata.
• data — строка, переданная в декоратор, например @Param('id') → data === 'id'.

Встроенные — ParseIntPipe, ParseBoolPipe, ParseUUIDPipe, ParseArrayPipe, DefaultValuePipe — не более чем реализации PipeTransform, которые парсят и выбрасывают BadRequestException при провале. Ты привязываешь их прямо у параметра:

@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
  // id is a number here, or the request already 400'd before we got called
  return this.users.findOne(id);
}

Стадия трансформации: transform:true делает настоящий DTO

По умолчанию ValidationPipe валидирует входящий объект и оставляет его обычным объектом. Параметр типизирован как CreateUserDto, но в рантайме это просто {} со строковыми полями — body instanceof CreateUserDto равно false, любые геттеры или методы DTO не существуют, а поле, объявленное Date, всё ещё string. Аннотация типа — это вымысел времени компиляции, который рантайм никогда не уважал.

Установка { transform: true } это меняет. Pipe запускает plainToInstance(metatype, value) из class-transformer и отдаёт хендлеру настоящий экземпляр класса DTO:

import { ValidationPipe } from '@nestjs/common';

app.useGlobalPipes(
  new ValidationPipe({
    transform: true, // plainToInstance(CreateUserDto, body) -> a real DTO instance
    whitelist: true,
  }),
);

export class CreateOrderDto {
  @Type(() => Number) // tells class-transformer to coerce this field to a number
  quantity: number;

  @Type(() => ShippingDto) // nested conversion: the child is built as a ShippingDto too
  shipping: ShippingDto;

  get total(): number {
    return this.quantity * UNIT_PRICE; // only callable because it's a REAL instance
  }
}

Только под transform: true работают две вещи: instanceof теперь истинно (так что значение — подлинный CreateOrderDto, а его геттеры/методы вроде total вызываемы), и декораторы @Type() отрабатывают — что и приводит quantity к number и пересобирает вложенный shipping как настоящий ShippingDto. Без transform: true @Type() бездействует, и твои вложенные объекты остаются обычными.

Footgun enableImplicitConversion — скрытая ловушка удобства

Писать @Type(() => Number) на каждом числовом поле утомительно, поэтому class-transformer предлагает срезку: transformOptions: { enableImplicitConversion: true }. С ней class-transformer приводит примитивы по объявленному TypeScript-типу каждого поля — @Type() не нужен. Поле типа number получает Number(value); поле типа boolean прогоняется через приведение к булеву; и так далее, по всему приложению, из одного флага.

new ValidationPipe({
  transform: true,
  transformOptions: { enableImplicitConversion: true }, // one flag, changes coercion everywhere
});

export class UserFilterDto {
  active: boolean; // no @Type needed now... but watch what "false" becomes
  page: number;
}

Вот ловушка, в трёх конкретных случаях:

• ?active=false на поле boolean → class-transformer приводит строку "false", а непустая строка истинна, так что ты получаешь true. Твой фильтр «показать деактивированных пользователей» теперь показывает активных. Это и есть тот production-инцидент дословно.
• ?page= (пустая строка) на поле number → Number("") это 0, а ?page= с мусором вроде 12abc → Number("12abc") это NaN, тихо переданный в твой запрос.
• ?ids= на поле-массив → приведение угадывает, а «угадай» — ровно то, чего ты не хочешь на границе валидации.

Сеньорская позиция: предпочитай явное, по-полевое приведение — @Type(() => Number) для числовых, @Transform(...) для случаев вроде булевых, где важно значение, — а не сплошной enableImplicitConversion. Если ты всё же включаешь implicit conversion, сопровождай каждое приводимое поле валидатором (@IsBoolean(), @IsInt()), чтобы результат приведения проверялся, а не принимался на веру. Флаг меняет несколько декораторов на поверхность тихого приведения по всему приложению; это плохой обмен на границе валидации.

Кастомный pipe: альтернатива на Zod

Кастомный pipe позволяет заменить всю машинерию class-validator. Здесь Zod-схема — единственный источник истины: она выводит TypeScript-тип, и валидирует, и трансформирует, в одном safeParse:

import { PipeTransform, ArgumentMetadata, BadRequestException } from '@nestjs/common';
import { ZodSchema } from 'zod';

export class ZodValidationPipe implements PipeTransform {
  constructor(private readonly schema: ZodSchema) {}

  transform(value: unknown, _metadata: ArgumentMetadata) {
    const result = this.schema.safeParse(value);
    if (!result.success) {
      throw new BadRequestException(result.error.format()); // reject -> 400
    }
    return result.data; // parsed AND coerced: one source of truth, no @Type, no reflect-metadata
  }
}

// usage: @Body(new ZodValidationPipe(createUserSchema)) — the schema infers the body type

Компромисс реален и идёт в обе стороны. Class-validator DI-нативен, идиоматичен для Nest, а его декораторы заодно служат источником для API-доков @nestjs/swagger — один набор декораторов питает и валидацию, и OpenAPI-схему. Zod даёт выведенные типы (нет дублирования декораторов/reflect-metadata) и куда лучшую композируемость (.refine, .transform, юнионы), но pipe ты проводишь сам и теряешь декораторную интеграцию со Swagger. Выбирай по ограничению: Swagger-first и тяжёлый DI → class-validator; вывод-типов-first и композируемость → Zod-pipe.