@IsUUID

Валидация UUID используется в системах, где идентификаторы должны соответствовать строгому формату, обеспечивающему глобальную уникальность и структурную предсказуемость. В экосистеме Class-validator для этих целей применяется декоратор проверки UUID, обеспечивающий контроль соответствия строки стандартам RFC 4122.

UUID представляет собой 128-битный идентификатор, обычно отображаемый в виде строки формата xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, где каждая группа символов имеет строго определённую длину и набор допустимых значений. Нарушение структуры приводит к невалидности значения независимо от его семантического содержания.

UUID делится на несколько версий, различающихся способом генерации:

  • v1 — основан на времени и MAC-адресе узла
  • v3 — namespace + MD5
  • v4 — случайная генерация
  • v5 — namespace + SHA-1

Каждая версия сохраняет общий формат, но отличается внутренней логикой формирования. Валидатор UUID в Class-validator учитывает не только общий формат, но и возможность ограничения конкретной версии.

Декоратор IsUUID и его назначение

Декоратор @IsUUID используется для проверки того, что строковое значение соответствует формату UUID. Базовая задача заключается в строгой валидации структуры строки без анализа её семантики.

Основной синтаксис:

import { IsUUID } from 'class-validator';

class UserDto {
  @IsUUID()
  id: string;
}

В этом случае любое значение id, не соответствующее стандарту UUID, будет отклонено в процессе валидации.

Проверка конкретной версии UUID

Валидация может быть ограничена конкретной версией UUID. Это особенно важно в системах, где формат идентификатора влияет на архитектурные гарантии.

import { IsUUID } from 'class-validator';

class UserDto {
  @IsUUID('4')
  id: string;
}

Поддерживаемые значения версии:

  • "3"
  • "4"
  • "5"
  • "all" (по умолчанию)

При указании версии происходит дополнительная проверка соответствующих битовых полей UUID, включая вариант и версионный октет.

Поведение валидатора при различных входных данных

Валидация UUID проверяет несколько уровней:

  1. Формат строки

    • наличие 36 символов с дефисами
    • корректные позиции разделителей

  2. Допустимые символы

    • только шестнадцатеричные символы 0-9, a-f, A-F

  3. Версионная структура

    • проверка позиции версии (13-й символ UUID)
    • проверка варианта (17-й символ)

Примеры значений:

  • валидный UUID v4: 550e8400-e29b-41d4-a716-446655440000
  • невалидный формат: 550e8400e29b41d4a716446655440000
  • неверные символы: 550e8400-e29b-41d4-a716-44665544ZZZZ

Интеграция с validation pipeline

В Class-validator декораторы работают в связке с функцией validate или validateOrReject. Проверка UUID становится частью общей схемы валидации DTO-объекта.

import { validate } from 'class-validator';
import { IsUUID } from 'class-validator';

class OrderDto {
  @IsUUID('4')
  orderId: string;
}

const dto = new OrderDto();
dto.orderId = 'invalid-id';

validate(dto).then(errors => {
  console.log(errors);
});

При нарушении правил возвращается массив ошибок, каждая из которых содержит метаданные о проваленной проверке.

Использование в REST DTO

UUID часто применяется как идентификатор сущностей в API. Валидатор обеспечивает защиту слоя контроллеров от некорректных входных данных.

import { IsUUID, IsString } from 'class-validator';

class UpdateProductDto {
  @IsUUID('4')
  productId: string;

  @IsString()
  name: string;
}

Такая структура гарантирует, что идентификатор продукта соответствует строгому формату до попадания в бизнес-логику.

Strict mode и особенности поведения

При использовании строгих схем сериализации важно учитывать, что @IsUUID не выполняет преобразование типов. Значение должно быть строкой до момента валидации. При передаче числовых или объектных значений проверка будет завершаться ошибкой независимо от их потенциальной сериализуемости.

Особенность заключается в том, что валидатор не пытается «исправлять» входные данные, а только проверяет их соответствие стандарту.

Кастомизация через ValidationOptions

Поведение декоратора может быть расширено через стандартные опции:

import { IsUUID } from 'class-validator';

class SessionDto {
  @IsUUID('4', {
    message: 'sessionId должен быть UUID версии 4'
  })
  sessionId: string;
}

Доступные параметры:

  • message — пользовательское сообщение ошибки
  • groups — группировка валидации
  • each — проверка элементов массива

Валидация массивов UUID

При необходимости проверки коллекций идентификаторов используется параметр each.

import { IsUUID } from 'class-validator';

class BatchRequestDto {
  @IsUUID('4', { each: true })
  ids: string[];
}

В этом случае каждый элемент массива проверяется независимо, а ошибка локализуется на уровне конкретного индекса.

Поведение при наследовании классов

В архитектурах с наследованием DTO валидаторы сохраняют своё поведение. Если базовый класс содержит UUID-поле, декоратор продолжает работать без необходимости повторного объявления.

class BaseEntityDto {
  @IsUUID('all')
  id: string;
}

class CommentDto extends BaseEntityDto {
  text: string;
}

Производительность проверки UUID

Проверка UUID реализована как регулярное выражение с дополнительной логикой анализа версии. Производительность остаётся стабильной даже при массовой валидации объектов, так как операция имеет константную сложность относительно длины строки.

В типичных сценариях API нагрузка от @IsUUID пренебрежимо мала по сравнению с другими слоями обработки запроса.

Совместимость с трансформацией данных

В связке с class-transformer часто используется предварительное преобразование входных данных перед валидацией. Однако @IsUUID не зависит от трансформации и работает исключительно с итоговым значением поля.

При включённом transform валидация UUID остаётся детерминированной и не изменяет входную строку.

Типовые ошибки при использовании

На практике чаще всего встречаются следующие проблемы:

  • передача UUID без дефисов
  • использование строк неправильной длины
  • несоответствие версии UUID указанному ограничению
  • попытка валидации уже сериализованных объектов с потерей строкового типа

Каждая из этих ситуаций приводит к отклонению значения на уровне декоратора без дальнейшей обработки.

Контекст применения в архитектуре сервисов

UUID используется как ключевой идентификатор в распределённых системах, где требуется отсутствие коллизий без централизованной генерации. Валидация на уровне DTO предотвращает проникновение некорректных идентификаторов в доменный слой.

В связке с ORM и слоями репозиториев UUID становится стандартом идентификации сущностей, особенно при работе с микросервисной архитектурой и внешними API-интеграциями.

Оглавление