GUID, IP-адреса

Валидация идентификаторов глобального уникального типа (GUID/UUID) в схемах данных выполняется через встроенный механизм Joi.string().guid(). Данный метод предназначен для проверки строковых значений, соответствующих формату UUID различных версий, а также GUID, используемых в распределённых системах для однозначной идентификации сущностей.

Основные особенности GUID/UUID

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

xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

где:

  • M обозначает версию UUID
  • N задаёт вариант (variant)
  • остальная часть — случайные или детерминированные данные

Наиболее распространённые версии:

  • версия 1 — основана на времени и MAC-адресе
  • версия 3 — основана на MD5-хеше
  • версия 4 — случайная генерация
  • версия 5 — основана на SHA-1

Базовая валидация UUID

В Joi проверка UUID выполняется следующим образом:

Joi.string().guid()

Данный вариант допускает любой корректный UUID независимо от версии.

Ограничение по версии UUID

Для строгой проверки используется параметр версии:

Joi.string().guid({ version: 'uuidv4' })

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

  • 'uuidv1'
  • 'uuidv3'
  • 'uuidv4'
  • 'uuidv5'
  • 'uuid' — любая версия

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

Валидация строгого формата

Дополнительные настройки позволяют управлять форматом строки:

Joi.string().guid({ version: 'uuidv4', separator: true })

Параметр separator определяет наличие дефисов. В большинстве случаев используется стандартный формат с разделителями, однако возможны сценарии хранения UUID без дефисов:

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

IP-адреса в Joi

Валидация IP-адресов осуществляется через метод Joi.ip(), который поддерживает как IPv4, так и IPv6 форматы.

Общая структура проверки IP

Joi.string().ip()

Данный вариант допускает оба протокола адресации.

Ограничение версии IP

Для уточнения типа адреса используется параметр версии:

Joi.string().ip({ version: ['ipv4'] })

Возможные значения:

  • 'ipv4' — адреса формата IPv4
  • 'ipv6' — адреса формата IPv6
  • массив значений — допускает несколько форматов одновременно

Валидация IPv4

IPv4 представляет собой 32-битный адрес, записанный в виде четырёх октетов:

192.168.0.1

Проверка:

Joi.string().ip({ version: 'ipv4' })

Каждый октет ограничен диапазоном от 0 до 255, что исключает некорректные значения вроде 999.999.999.999.

Валидация IPv6

IPv6 использует 128-битную адресацию и записывается в шестнадцатеричном формате:

2001:0db8:85a3:0000:0000:8a2e:0370:7334

Сокращённые формы также считаются валидными:

2001:db8::8a2e:370:7334

Проверка:

Joi.string().ip({ version: 'ipv6' })

Ограничение использования CIDR

IP-адреса могут включать маску подсети (CIDR):

192.168.0.0/24

Поддержка включается явно:

Joi.string().ip({ cidr: 'optional' })

Режимы:

  • 'optional' — CIDR допускается, но не обязателен
  • 'required' — обязательное наличие маски
  • 'forbidden' — CIDR запрещён

Комплексная проверка IP-адресов

Комбинированные ограничения позволяют формировать строгие правила валидации:

Joi.string().ip({
  version: ['ipv4', 'ipv6'],
  cidr: 'optional'
})

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

Особенности обработки ошибок

При несоответствии формату UUID или IP-адреса Joi формирует объект ошибки, содержащий:

  • тип нарушения (string.guid, string.ip)
  • описание ожидаемого формата
  • фактическое значение

Пример структуры ошибки:

{
  "type": "string.guid",
  "message": "\"id\" must be a valid GUID"
}

или

{
  "type": "string.ip",
  "message": "\"address\" must be a valid ip address"
}

Совместное использование с другими правилами

UUID и IP-адреса часто комбинируются с дополнительными ограничениями Joi:

Joi.object({
  id: Joi.string().guid({ version: 'uuidv4' }).required(),
  ip: Joi.string().ip({ version: 'ipv4' }).required()
})

Дополнительные модификаторы:

  • required() — обязательное поле
  • optional() — допускается отсутствие значения
  • allow() — разрешение специфических значений (например, null)

Нормализация и предобработка

Joi позволяет выполнять предварительную обработку значений перед валидацией:

Joi.string().trim().lowercase().guid()

Для IP-адресов аналогично:

Joi.string().trim().ip()

Такие преобразования уменьшают вероятность ошибок, связанных с пробелами или регистром символов в строке.

Использование в схемах сложных объектов

UUID и IP-адреса часто являются частью сложных структур данных:

const schema = Joi.object({
  userId: Joi.string().guid({ version: 'uuidv4' }),
  session: Joi.object({
    ip: Joi.string().ip({ version: ['ipv4', 'ipv6'] }),
    deviceId: Joi.string().guid()
  })
})

Подобные схемы применяются при валидации сессий, логов доступа, API-запросов и идентификаторов ресурсов в распределённых системах.

Оглавление