Проверка UUID

Формат UUID и требования стандарта

UUID (Universally Unique Identifier) представляет собой 128-битный идентификатор, используемый для уникальной идентификации объектов в распределённых системах. Стандарт RFC 4122 определяет каноническое строковое представление UUID в виде:

xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

где:

  • x — шестнадцатеричный символ (0–9, a–f)
  • M — версия UUID
  • N — вариант (variant)

Стандартный формат включает 36 символов, включая четыре дефиса. Пример корректного UUID:

550e8400-e29b-41d4-a716-446655440000

Ключевые особенности:

  • строго фиксированная структура из 5 групп
  • допустимы только шестнадцатеричные символы
  • регистр символов не имеет значения
  • версия UUID определяется третьей группой

Поддержка UUID в Validator.js

Библиотека Validator.js предоставляет функцию isUUID, предназначенную для проверки строк на соответствие формату UUID.

Сигнатура функции:

validator.isUUID(str [, version])

Параметры:

  • str — проверяемая строка
  • version — необязательный параметр, задающий версию UUID

Возвращаемое значение:

  • true — строка соответствует UUID
  • false — строка не является UUID

Базовая проверка UUID

Стандартная проверка без указания версии допускает любой валидный UUID (v1–v5):

import validator from 'validator';

validator.isUUID('550e8400-e29b-41d4-a716-446655440000');
// true

При передаче строки, не соответствующей структуре, результат будет отрицательным:

validator.isUUID('invalid-uuid-string');
// false

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

UUID существует в нескольких версиях, каждая из которых имеет собственную семантику генерации.

Validator.js поддерживает строгую проверку версий:

validator.isUUID(str, version);

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

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

Примеры:

validator.isUUID('550e8400-e29b-41d4-a716-446655440000', '4');
// true или false в зависимости от версии

validator.isUUID('3f47ac10-b5c7-11e0-962b-0800200c9a66', '1');
// false (несоответствие версии)

Версия UUID определяется третьей группой:

  • первый символ этой группы кодирует версию

Пример:

xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx
             ↑
          версия 4

Структурная проверка UUID

Функция isUUID выполняет несколько уровней проверки:

  1. Проверка длины строки (36 символов с дефисами)
  2. Проверка позиции дефисов (8-4-4-4-12)
  3. Проверка допустимых символов (hex)
  4. Проверка версии (если указана)
  5. Проверка варианта (RFC 4122 variant bits)

Недопустимые отклонения:

  • отсутствие дефисов
  • лишние символы
  • использование не-hex символов (например, g, z)
  • неверная позиция версии
  • добавление скобок или префиксов

Примеры некорректных значений:

validator.isUUID('550e8400e29b41d4a716446655440000'); // нет дефисов
validator.isUUID('550e8400-e29b-41d4-a716-44665544000z'); // недопустимый символ
validator.isUUID('{550e8400-e29b-41d4-a716-446655440000}'); // лишние символы

Нормализация регистра

UUID может содержать символы в верхнем или нижнем регистре. Validator.js рассматривает оба варианта как равнозначные:

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

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

Nil UUID

Специальное значение UUID — nil UUID, представляющее нулевой идентификатор:

00000000-0000-0000-0000-000000000000

Validator.js поддерживает его как валидный UUID:

validator.isUUID('00000000-0000-0000-0000-000000000000');
// true

Использование валидации в прикладных сценариях

UUID часто применяется в следующих областях:

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

Валидация через isUUID используется для предотвращения:

  • SQL-инъекций через подставные идентификаторы
  • ошибок при парсинге API-запросов
  • некорректных ссылок на ресурсы

Пример проверки входных данных:

function validateRequest(params) {
  if (!validator.isUUID(params.userId, '4')) {
    return false;
  }

  if (!validator.isUUID(params.sessionId)) {
    return false;
  }

  return true;
}

Ограничения проверки

Функция isUUID выполняет синтаксическую проверку и не определяет:

  • фактическую уникальность значения
  • принадлежность к конкретному namespace
  • криптографическую корректность генерации
  • семантический контекст использования

UUID, прошедший проверку, может оставаться несуществующим в системе данных.

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

Проверка UUID в Validator.js основана на регулярных выражениях с предопределёнными шаблонами. Операция имеет константную сложность O(1), так как длина строки фиксирована.

Оптимизации включают:

  • предварительно скомпилированные regex-шаблоны
  • минимальное количество операций сравнения
  • ранний выход при несоответствии длины

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

Распространённые ошибки при работе с UUID:

Использование UUID без дефисов

validator.isUUID('550e8400e29b41d4a716446655440000'); // false

Проверка только длины строки

str.length === 36 // недостаточно для валидации

Игнорирование версии UUID Некоторые системы требуют строго UUID v4, однако проверка без указания версии допускает любые варианты.

Попытка кастомной валидации через regex Самописные регулярные выражения часто содержат ошибки в обработке версии и варианта.

Сравнение строгой и общей проверки

Режим проверки Поведение
isUUID(str) любой валидный UUID
isUUID(str, '4') только UUID v4
isUUID(str, '5') только UUID v5

Строгая проверка используется при необходимости гарантировать источник генерации идентификатора.

Особенности RFC 4122 варианта

UUID имеет поле variant, определяющее схему интерпретации. В RFC 4122 используется вариант, где старшие биты 8-й группы соответствуют шаблону 10xx.

Validator.js учитывает этот аспект при проверке, исключая UUID, не соответствующие стандарту.

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

При обработке HTTP-запросов UUID часто используется как параметр маршрута:

app.get('/users/:id', (req, res) => {
  if (!validator.isUUID(req.params.id, '4')) {
    return res.status(400).send('Invalid ID');
  }

  // дальнейшая обработка
});

Валидация на уровне входных данных снижает нагрузку на бизнес-логику и предотвращает некорректные обращения к базе данных.

Обработка нестандартных форматов

Некоторые системы используют модифицированные UUID:

  • без дефисов
  • в фигурных скобках
  • в base64 представлении

Validator.js не поддерживает такие форматы, так как ориентирован на RFC 4122.

Взаимодействие с другими функциями Validator.js

UUID-проверка часто комбинируется с другими методами:

validator.isUUID(str) && validator.isAlphanumeric(str.replace(/-/g, ''));

или валидацией входных DTO:

  • isUUID
  • isLength
  • isEmpty
  • isLowercase

Такая композиция позволяет формировать строгие схемы проверки данных.

Поведение при null и undefined

Передача нестроковых значений приводит к возврату false:

validator.isUUID(null); // false
validator.isUUID(undefined); // false
validator.isUUID(123); // false

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

Оглавление