Кастомные и асинхронные валидаторы (и их ловушки)

Два способа написать кастомный constraint

class-validator даёт две формы для кастомного правила. Первая — класс constraint: класс, помеченный @ValidatorConstraint, реализующий ValidatorConstraintInterface. Ты пишешь validate() (возвращает boolean или Promise<boolean>) и defaultMessage(), затем прикрепляешь его к свойству через @Validate(MyConstraint).

import {
  ValidatorConstraint,
  ValidatorConstraintInterface,
  ValidationArguments,
  Validate,
} from 'class-validator';

// A synchronous rule — no I/O, just logic over the value
@ValidatorConstraint({ name: 'isStrongPassword', async: false })
export class IsStrongPasswordConstraint implements ValidatorConstraintInterface {
  validate(value: string): boolean {
    return typeof value === 'string'
      && value.length >= 12
      && /[a-z]/.test(value)
      && /[A-Z]/.test(value)
      && /[0-9]/.test(value);
  }
  defaultMessage(args: ValidationArguments): string {
    return `${args.property} must be ≥12 chars with upper, lower, and a digit`;
  }
}

export class SignupDto {
  @Validate(IsStrongPasswordConstraint)
  password: string;
}

Вторая форма — фабрика декоратора на базе registerDecorator. За ней тянешься, когда хочешь переиспользуемый @IsEmailUnique(), который можно ронять на любое свойство — она оборачивает тот же интерфейс constraint в функцию, регистрирующую его против target и property:

import { registerDecorator, ValidationOptions } from 'class-validator';

// Переиспользуемый декоратор: @IsEmailUnique() — оборачивает constraint через registerDecorator
export function IsEmailUnique(options?: ValidationOptions) {
  return function (target: object, propertyName: string) {
    registerDecorator({
      name: 'isEmailUnique',
      target: target.constructor,
      propertyName,
      options,
      validator: IsEmailUniqueConstraint, // the @Injectable() class below
    });
  };
}

В любом случае правило живёт в классе constraint. Фабрика декоратора — лишь эргономичная упаковка, чтобы место вызова читалось как @IsEmailUnique(), а не @Validate(IsEmailUniqueConstraint).

Асинхронные валидаторы и ловушка DI

Проверка уникальности обязана говорить с базой, так что её validate() возвращает Promise<boolean>, а constraint помечен async: true. Чтобы запросить, ему нужен repository пользователей — поэтому ты инжектишь его, как любой другой сервис Nest:

@ValidatorConstraint({ name: 'isEmailUnique', async: true })
@Injectable()
export class IsEmailUniqueConstraint implements ValidatorConstraintInterface {
  constructor(private readonly users: UsersRepository) {} // injected dep

  async validate(email: string): Promise<boolean> {
    // true = valid = email is NOT taken
    return !(await this.users.exists({ email }));
  }
  defaultMessage(): string {
    return 'email already taken';
  }
}

Это компилируется, а затем падает в рантайме: Cannot read properties of undefined (reading 'exists'). Причина — та самая ловушка. class-validator инстанцирует классы constraint сам, вне DI-контейнера Nest — он просто делает new IsEmailUniqueConstraint(), не имея понятия, что твой конструктор хотел repository. Так что this.users — undefined. В зависимости от того, как ты написал защиту, это либо краш, либо — хуже — валидатор, который молча всегда проходит, потому что await на undefined выбрасывает, а исключение проглатывается.

Фикс в одну строку живёт в main.ts. useContainer (экспортируется из class-validator) говорит ему резолвить constraint через контейнер Nest вместо того, чтобы new-ить их самому:

import { useContainer } from 'class-validator';
import { AppModule } from './app.module';

const app = await NestFactory.create(AppModule);
// Инстанцирование constraint через DI Nest, чтобы @Injectable() зависимости резолвились
useContainer(app.select(AppModule), { fallbackOnErrors: true });

Теперь IsEmailUniqueConstraint строится Nest, получает свой UsersRepository, и this.users реален. fallbackOnErrors: true важен: встроенные constraint class-validator (@IsEmail, @IsString, …) — не провайдеры Nest, так что Nest не может их зарезолвить — fallbackOnErrors позволяет class-validator откатиться на свой собственный new для них вместо того, чтобы выбросить. Без него каждый встроенный валидатор станет ошибкой «provider not found».

Три ловушки, и почему индекс — настоящий фикс

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

(1) DI — та, что выше: забыл useContainer — и инжектированный repository undefined. Краш в день деплоя, легко найти, как только знаешь, что он существует.

(2) Производительность и enumeration — валидация теперь выполняет запрос на каждый запрос к этому эндпоинту, до хендлера, включая некорректные и злонамеренные. Это DB round trip на запрос, и хуже того, отличимое сообщение "email already taken" превращает эндпоинт в оракул user-enumeration: атакующий скриптует его, чтобы узнать, у каких email есть аккаунты. Митигируй rate limiting и сообщением, которое не подтверждает существование.

(3) Гонка TOCTOU — настоящий урок. Это и есть прод-инцидент. Проверка уникальности — это read-then-write, так что при конкуренции две регистрации обе проходят валидатор и обе вставляют. Исход — либо две строки с одинаковым email (нет constraint), либо сырое нарушение уникальности Postgres, всплывающее как 500 (constraint есть, не обработан). Фикс — перестать притворяться, что валидация — это constraint:

// 1) The DATABASE is the source of truth — a UNIQUE index serializes inserts
//    e.g. CREATE UNIQUE INDEX users_email_key ON users (lower(email));

// 2) Catch the unique-violation and map it to a clean 409 — Postgres code 23505
try {
  return await this.users.insert(dto);
} catch (e) {
  if (e.code === '23505') {           // unique_violation
    throw new ConflictException('email already taken'); // 409, not 500
  }
  throw e;
}

Валидация — это не constraint. Оставь асинхронный @IsEmailUnique() — он даёт общему случаю дружелюбный 400 без stack trace. Но UNIQUE-индекс — источник истины: он единственное, что сериализует две конкурентные вставки, и отлов 23505 превращает проигравшего в этой гонке в чистый 409 вместо утёкшего 500. Валидатор — это UX; индекс — это гарантия.