Методы isUUID

Метод isUUID в Validator.js предназначен для проверки строки на соответствие формату UUID (Universally Unique Identifier). UUID широко используется в распределённых системах, базах данных, API и микросервисной архитектуре для уникальной идентификации сущностей без централизованной координации.

UUID представляет собой 128-битное значение, обычно записываемое в текстовом виде в формате:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

где каждая x — шестнадцатеричный символ.

Сигнатура метода

isUUID(str [, version])

Параметры

  • str — проверяемая строка

  • version — (необязательный параметр) определяет версию UUID:

    • "3" — UUID версии 3 (MD5 namespace)
    • "4" — UUID версии 4 (случайная генерация)
    • "5" — UUID версии 5 (SHA-1 namespace)
    • "all" — любая валидная версия UUID

Общий принцип работы

Метод выполняет строгую проверку строки на соответствие структуре UUID с учётом:

  • количества символов (32 шестнадцатеричных символа)
  • наличия дефисов в корректных позициях
  • допустимых значений версии (если указана)
  • допустимого варианта варианта (variant bits RFC 4122)

Внутри Validator.js используется регулярное выражение, адаптированное под RFC 4122, с дополнительной фильтрацией по версии.

Проверка UUID без указания версии

При вызове без второго параметра:

isUUID(str)

проверяются все стандартные версии UUID (3, 4, 5), соответствующие RFC 4122.

Пример:

validator.isUUID("550e8400-e29b-41d4-a716-446655440000"); // true
validator.isUUID("not-a-uuid"); // false

UUID версии 1–5 и особенности проверки

Хотя UUID существует в нескольких версиях, метод isUUID в Validator.js фокусируется на наиболее распространённых:

UUID v3

Основан на MD5-хэше namespace.

validator.isUUID("c1a5298f-a0a2-3e1c-8a2c-3d6f9f7e9b10", "3");

Проверка гарантирует, что третий сегмент начинается с 3.

UUID v4

Наиболее часто используемый вариант, основанный на случайных числах.

validator.isUUID("550e8400-e29b-41d4-a716-446655440000", "4");

Ключевая особенность:

  • 13-й символ должен быть 4
  • 17-й символ должен соответствовать варианту RFC (8, 9, a, b)

UUID v5

Основан на SHA-1 и namespace.

validator.isUUID("886313e1-3b8a-5372-9b90-0c9aee199e5d", "5");

Проверка всех версий

validator.isUUID(str, "all");

Используется, когда версия UUID не критична, но требуется соответствие формату RFC.

Строгая структура UUID

UUID всегда состоит из пяти групп:

8-4-4-4-12

Пример:

123e4567-e89b-12d3-a456-426614174000

Метод проверяет:

  • длину строки (36 символов с дефисами)
  • позицию дефисов
  • допустимые символы [0-9a-fA-F]
  • корректность битов версии и варианта

Чувствительность к формату

Метод не допускает отклонений от стандарта:

Недопустимые варианты:

{550e8400-e29b-41d4-a716-446655440000}
550e8400e29b41d4a716446655440000
urn:uuid:550e8400-e29b-41d4-a716-446655440000

Все они вернут false, так как:

  • фигурные скобки не допускаются
  • отсутствие дефисов нарушает формат
  • префикс urn:uuid: не поддерживается

Регистр символов

UUID может содержать как строчные, так и заглавные символы:

validator.isUUID("550E8400-E29B-41D4-A716-446655440000"); // true

Проверка регистронезависима, так как сравнение выполняется через регулярное выражение с флагом i.

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

1. Проверка “похожих” идентификаторов

UUID часто путают с другими идентификаторами:

  • MongoDB ObjectId (24 hex символа)
  • hash SHA-1 / SHA-256
  • custom GUID форматы

Все они будут возвращать false.

2. Передача чисел вместо строки

validator.isUUID(12345); // false

Метод ожидает строку. Любое нестроковое значение приводит к отрицательному результату.

3. Неправильная версия UUID

validator.isUUID(uuid, "4");

Если UUID не соответствует версии 4, результат будет false, даже если формат в целом корректен.

Внутренняя логика проверки

Хотя реализация скрыта в библиотеке, логика основана на:

  • строгой регулярной проверке структуры
  • побитовом анализе версии (13-й символ)
  • проверке варианта RFC 4122 (17-й символ)

Упрощённо:

/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i

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

isUUID относится к быстрым проверкам:

  • сложность O(n), где n = 36 символов
  • регулярное выражение фиксированной длины
  • минимальные накладные расходы

Метод подходит для массовой валидации данных в API и потоковой обработке.

Практические сценарии использования

Проверка идентификаторов API

UUID часто используется как публичный идентификатор ресурсов:

GET /users/:id

Проверка:

if (!validator.isUUID(req.params.id, "4")) {
  throw new Error("Invalid user id");
}

Валидация входных данных

При приёме JSON:

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}
validator.isUUID(body.requestId);

Фильтрация данных в базе

Перед сохранением:

if (validator.isUUID(record.parentId)) {
  save(record);
}

Особенности поведения при неопределённом значении версии

Если версия указана как "all", проверка включает все допустимые версии RFC 4122, но не расширенные или кастомные форматы UUID.

Ограничения метода

  • не поддерживает UUID v6–v8 (новые экспериментальные стандарты)
  • не принимает URN-форматы
  • не нормализует строку (только проверка)
  • не исправляет формат автоматически

Совместимость и стандарты

Метод ориентирован на RFC 4122, что обеспечивает совместимость с:

  • PostgreSQL UUID type
  • MongoDB UUID representation
  • REST API идентификаторами
  • распределёнными системами идентификации
Оглавление