@IsURL

Декоратор @IsURL в библиотеке class-validator используется для проверки строковых значений на соответствие формату URL. В основе проверки лежит функциональность библиотеки validator.js, поэтому поведение декоратора напрямую зависит от набора правил и опций, поддерживаемых валидатором URL.

Основное назначение декоратора — валидация данных DTO-моделей, особенно в приложениях, построенных на NestJS или любых архитектурах, где входные данные проходят через классы с аннотациями.

Проверка URL включает анализ следующих компонентов:

  • протокол (например, http, https, ftp)
  • доменное имя или IP-адрес
  • путь
  • параметры запроса
  • фрагмент (hash)

Минимально допустимая строка может выглядеть как:

  • https://example.com
  • http://localhost:3000
  • ftp://192.168.0.1/resource

Базовое использование @IsURL

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

import { IsURL } from 'class-validator';

export class CreateUserDto {
  @IsURL()
  website: string;
}

В этом случае используется стандартный набор правил validator.js, где проверяются базовые требования к корректности URL.

Поведение по умолчанию

При отсутствии параметров:

  • допускаются стандартные протоколы http, https, ftp
  • требуется наличие домена или IP
  • допускается порт
  • требуется корректная структура URL
  • запрещены строки без протокола (например, example.com будет невалидным)

Параметры IsURL

Декоратор поддерживает объект конфигурации IsURLOptions, который позволяет гибко управлять проверкой.

Основные опции

require_protocol

Определяет необходимость наличия протокола.

@IsURL({ require_protocol: true })
website: string;

Поведение:

  • https://example.com — валидно
  • example.com — невалидно

require_tld

Требует наличие доменной зоны верхнего уровня.

@IsURL({ require_tld: true })
website: string;

Поведение:

  • https://example.com — валидно
  • https://localhost — невалидно

allow_underscores

Разрешает использование символа _ в доменной части.

@IsURL({ allow_underscores: true })
website: string;

Поведение:

  • http://my_site.com — валидно при включённой опции
  • http://my_site.com — невалидно по умолчанию

allow_trailing_dot

Разрешает завершающую точку в домене.

@IsURL({ allow_trailing_dot: true })
website: string;

Поведение:

  • https://example.com. — валидно при включённой опции
  • https://example.com. — невалидно по умолчанию

allow_protocol_relative_urls

Разрешает URL без указания протокола, начинающиеся с //.

@IsURL({ allow_protocol_relative_urls: true })
website: string;

Поведение:

  • //example.com/path — валидно
  • https://example.com/path — валидно
  • example.com/path — невалидно

protocols

Позволяет ограничить список допустимых протоколов.

@IsURL({
  protocols: ['https'],
})
website: string;

Поведение:

  • https://example.com — валидно
  • http://example.com — невалидно

require_host

Требует наличие хоста.

@IsURL({ require_host: true })
website: string;

Поведение:

  • https://example.com — валидно
  • file:///folder/file.txt — невалидно

Комбинирование параметров

Опции могут использоваться совместно, формируя строгие правила валидации.

@IsURL({
  require_protocol: true,
  require_tld: true,
  protocols: ['https'],
  allow_underscores: false,
})
website: string;

В этом случае допустимыми будут только HTTPS-ссылки с полноценным доменом и без подчёркиваний.

Валидация URL в DTO-моделях

При использовании в структурах данных декоратор интегрируется в цепочку валидации:

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

export class UpdateProfileDto {
  @IsString()
  username: string;

  @IsURL({
    require_protocol: true,
    protocols: ['https', 'http'],
  })
  avatarUrl: string;
}

В процессе обработки запроса:

  1. создаётся экземпляр DTO
  2. выполняется трансформация входных данных
  3. запускается проверка всех декораторов
  4. при нарушении правил формируется список ошибок

Особенности проверки локальных адресов

URL вроде:

  • http://localhost:3000
  • http://127.0.0.1

могут считаться валидными или невалидными в зависимости от опций:

  • require_tld: false — позволяет использовать localhost
  • require_tld: true — блокирует локальные адреса

Отличия от IsFQDN и IsDomainName

Хотя проверка пересекается с валидацией доменов, @IsURL отличается тем, что:

  • анализирует всю структуру URL
  • включает протокол и путь
  • учитывает query string и hash
  • не ограничивается только доменной частью

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

Отсутствие протокола

@IsURL()
website: string;

Значение example.com будет отклонено, поскольку протокол обязателен по умолчанию.

Слишком строгие настройки

Комбинация:

@IsURL({
  require_tld: true,
  require_protocol: true,
  protocols: ['https'],
})

может привести к отклонению локальных адресов и HTTP-ресурсов, что критично в средах разработки.

Неправильное ожидание валидации путей

Строка:

  • /path/to/resource

не является URL и всегда будет считаться невалидной.

Влияние validator.js

Все проверки основаны на validator.isURL, поэтому:

  • обновления validator.js меняют поведение
  • различия версий могут влиять на допустимые форматы
  • часть опций может быть устаревшей или изменённой в новых релизах

Практическое использование в сложных схемах

В DTO с большим количеством URL-полей часто комбинируются разные стратегии валидации:

export class LinkSetDto {
  @IsURL({ require_protocol: true })
  website: string;

  @IsURL({ require_protocol: false, allow_protocol_relative_urls: true })
  cdnUrl: string;

  @IsURL({ protocols: ['https'] })
  secureResource: string;
}

Такая структура позволяет разделять требования к внешним и внутренним ресурсам.

Поведение при пустых значениях

Декоратор @IsURL не проверяет обязательность поля. Для разрешения пустых значений обычно используется дополнительная аннотация:

  • @IsOptional()
@IsOptional()
@IsURL()
website?: string;

Без @IsOptional() пустое значение будет проходить валидацию как undefined, что может быть обработано отдельно в логике DTO.

Совместимость с трансформацией типов

При использовании class-transformer важно учитывать:

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