@IsFQDN

Валидационный декоратор @IsFQDN из библиотеки class-validator предназначен для проверки строкового значения на соответствие формату FQDN (Fully Qualified Domain Name) — полностью квалифицированного доменного имени. Поддерживается использование в DTO-моделях, схемах валидации и слоях входных данных, где требуется строгая проверка доменных имён.

FQDN представляет собой полное доменное имя, включающее все уровни доменной иерархии, включая домен верхнего уровня.

Примеры корректных FQDN:

  • example.com
  • api.example.com
  • sub.domain.co.uk

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

  • localhost
  • example
  • http://example.com
  • example..com

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

Синтаксис декоратора

import { IsFQDN } from 'class-validator';

class CreateServiceDto {
  @IsFQDN()
  domain: string;
}

В базовой форме декоратор не принимает параметров и использует стандартные правила валидации FQDN.

Поведение валидации

При применении @IsFQDN выполняется проверка:

  • строка должна быть валидным доменным именем;
  • допускаются только корректные DNS-символы;
  • запрещены протоколы (http://, https://);
  • запрещены пробелы и специальные символы вне DNS-стандарта;
  • каждая метка домена должна соответствовать правилам RFC.

Валидация работает только с типом string. Значения других типов автоматически считаются некорректными.

Опции конфигурации

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

require_tld

@IsFQDN({ require_tld: false })
domain: string;

Определяет, обязателен ли домен верхнего уровня.

  • true (по умолчанию): требуется наличие TLD (.com, .org, .ru)
  • false: допускаются значения без TLD, например localhost или внутренние домены

Используется в корпоративных сетях и тестовых окружениях.

allow_underscores

@IsFQDN({ allow_underscores: true })
domain: string;

Разрешает использование символа _ в доменных метках.

Обычно DNS-стандарты не рекомендуют подчёркивания, однако они встречаются в:

  • старых внутренних системах;
  • некоторых SRV-записях;
  • нестандартных инфраструктурах.

По умолчанию значение false.

allow_trailing_dot

@IsFQDN({ allow_trailing_dot: true })
domain: string;

Позволяет наличие завершающей точки в домене:

  • example.com.

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

По умолчанию завершающая точка запрещена.

Комбинирование опций

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

@IsFQDN({
  require_tld: true,
  allow_underscores: false,
  allow_trailing_dot: true,
})
domain: string;

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

Использование в DTO-моделях

Типичный сценарий — валидация входных данных в сервисах API.

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

class UpdateConfigDto {
  @IsString()
  name: string;

  @IsFQDN({
    require_tld: true,
  })
  endpoint: string;
}

В этом примере поле endpoint гарантированно содержит корректное доменное имя без протокола и лишних символов.

Поведение при вложенных структурах

При работе с вложенными объектами @IsFQDN сохраняет локальность валидации и применяется только к конкретному полю:

class DatabaseConfig {
  @IsFQDN()
  host: string;
}

class AppConfig {
  database: DatabaseConfig;
}

Валидация host выполняется независимо от остальной структуры.

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

Передача URL вместо домена

Ошибка:

host: "https://example.com"

Причина: наличие протокола делает строку невалидным FQDN.

Корректное значение:

host: "example.com"

Использование IP-адресов

host: "192.168.0.1"

IP-адреса не являются FQDN и не проходят проверку.

Для таких случаев используется @IsIP.

Пустые строки

host: ""

Пустая строка не удовлетворяет требованиям DNS-имени.

Наличие пробелов

host: "exa mple.com"

Любые пробелы автоматически приводят к провалу валидации.

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

Валидация FQDN часто используется в следующих слоях:

  • конфигурационные сервисы;
  • системы multi-tenant архитектуры;
  • настройки обратных прокси;
  • описание внешних API endpoint-ов;
  • email-домены (частично).

В инфраструктурных приложениях @IsFQDN помогает исключить некорректные DNS-значения на этапе поступления данных, снижая вероятность ошибок на уровне сетевых запросов.

Отличие от схожих валидаторов

@IsUrl

  • проверяет полный URL;
  • требует протокол;
  • допускает путь, параметры и якоря.

@IsDomainName (в некоторых реализациях)

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

@IsFQDN

  • работает только с доменом;
  • не допускает протокол;
  • не включает путь или порт;
  • ориентирован на DNS-уровень.

Поведение при сериализации и трансформации

В связке с трансформерами (например, class-transformer) важно учитывать, что @IsFQDN не выполняет преобразование данных, а только проверку.

import { Transform } from 'class-transformer';

class Dto {
  @Transform(({ value }) => value?.trim())
  @IsFQDN()
  domain: string;
}

Здесь предварительная очистка строки повышает вероятность успешной валидации.

Практическая роль в архитектуре

Использование @IsFQDN обычно связано с концепцией строгой типизации входных данных на уровне API. Это снижает вероятность:

  • DNS-ошибок при обращениях к внешним сервисам;
  • некорректных конфигураций окружений;
  • уязвимостей, связанных с подменой доменных значений;
  • логических ошибок при маршрутизации запросов.

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

Оглавление