Устаревшие методы

В библиотеке Validator.js часть методов со временем помечается как устаревшая (deprecated). Причины появления устаревших API обычно связаны со следующими факторами:

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

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

Понятие deprecated API

Устаревший метод — это функция, которая:

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

Пример типичного предупреждения:

Deprecated: use isTaxID() instead

При обновлении проекта до новых версий Validator.js подобные методы становятся источником ошибок и несовместимости.

Основные признаки устаревших методов

Наличие пометки deprecated в документации

В документации Validator.js устаревшие методы обычно сопровождаются:

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

Пример:

Deprecated since version 13.x

Предупреждения линтера

Современные инструменты анализа кода способны выявлять deprecated API.

Пример:

validator.oldMethod(value);

ESLint может сообщить:

'oldMethod' is deprecated

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

Некоторые методы устаревают из-за несовместимости с современными требованиями:

Unicode;
IDN-домены;
IPv6;
RFC-стандарты;
современные email-форматы.

Устаревшие подходы в Validator.js

Старые методы проверки email

Ранние версии Validator.js содержали менее строгие механизмы проверки email.

Пример проблем:

validator.isEmail("test@localhost");

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

Устаревшие параметры опций

Некоторые методы изменяли формат параметров.

Старый вариант:

validator.isEmail(email, true);

Новый вариант:

validator.isEmail(email, {
    allow_display_name: true
});

Причины отказа от позиционных аргументов

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

плохая читаемость;
сложность поддержки;
ошибки порядка аргументов;
трудности расширения API.

Deprecated-подходы при работе с URL

Старые проверки URL

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

validator.isURL(url, false);

Современный вариант:

validator.isURL(url, {
    require_protocol: true
});

Проблемы старого API

Старые проверки URL часто:

неверно обрабатывали Unicode;
не поддерживали современные TLD;
некорректно валидировали query-параметры;
игнорировали безопасность протоколов.

Устаревшие методы очистки данных

removeNullBytes

Ранее библиотека содержала методы очистки строк, ориентированные на старые уязвимости.

Пример:

validator.removeNullBytes(str);

Подобные методы постепенно теряют актуальность, поскольку:

современные среды безопаснее;
часть защиты перенесена в платформу;
используются другие механизмы sanitization.

Устаревшие sanitizer-методы

normalizeEmail со старыми опциями

Поведение normalizeEmail() со временем менялось.

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

validator.normalizeEmail(email, {
    remove_dots: false
});

Новые версии могут:

иначе трактовать Gmail-адреса;
менять правила для Outlook;
изменять обработку subaddressing.

Причины удаления методов

Небезопасная логика

Иногда метод удаляется из-за потенциальной уязвимости.

Пример проблем:

ReDoS-атаки через регулярные выражения;
неправильная обработка Unicode;
обход валидации.

Непредсказуемое поведение

Метод может работать по-разному в разных средах:

validator.isFloat("1,5");

Проблема:

локализация;
региональные настройки;
различия десятичного разделителя.

Избыточность API

Некоторые методы дублируют функциональность JavaScript.

Пример:

validator.toInt(value);

Вместо этого часто используется:

Number.parseInt(value, 10);

Типичные deprecated-методы старых версий

toDate

В старых версиях:

validator.toDate(value);

Проблемы:

зависимость от Date.parse;
различия браузеров;
неоднозначный парсинг дат.

Современный подход:

new Date(value);

или специализированные библиотеки:

date-fns;
Luxon;
Day.js.

toFloat

Пример:

validator.toFloat(value);

Замена:

Number.parseFloat(value);

Причины отказа:

дублирование стандартного API;
отсутствие дополнительных преимуществ.

Изменение поведения методов

Строгая валидация вместо мягкой

Старые версии Validator.js были более «мягкими».

Пример:

validator.isURL("example.com");

Современные версии часто требуют:

validator.isURL("https://example.com");

с опцией:

{
    require_protocol: true
}

Усиление RFC-совместимости

Email-проверки постепенно приближались к RFC-стандартам.

Изменения касались:

длины локальной части;
Unicode-символов;
quoted strings;
display names.

Обратная совместимость

Почему deprecated API не удаляют сразу

Мгновенное удаление функций приводит к:

поломке старых проектов;
несовместимости зависимостей;
ошибкам production-систем.

Поэтому применяется жизненный цикл:

Метод объявляется deprecated.
Появляется предупреждение.
Документация обновляется.
Выпускаются промежуточные версии.
Метод удаляется полностью.

Проверка deprecated API в проекте

Поиск через grep

Linux/macOS:

grep -rn "toFloat" ./src

Поиск через IDE

Современные IDE умеют:

подсвечивать deprecated API;
предлагать автоматическую замену;
показывать документацию.

Анализ changelog

При обновлении Validator.js необходимо изучать changelog.

Особое внимание уделяется разделам:

Deprecated;
Breaking Changes;
Migration Guide.

Миграция со старых методов

Пример миграции isURL

Старый код:

validator.isURL(url, true);

Новый код:

validator.isURL(url, {
    require_protocol: true
});

Пример миграции isEmail

Старый вариант:

validator.isEmail(email, true);

Новый вариант:

validator.isEmail(email, {
    allow_display_name: true
});

Проблемы при обновлении Validator.js

Изменение результатов валидации

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

Причины:

новые RFC-ограничения;
усиление регулярных выражений;
изменение опций по умолчанию.

Изменение normalizeEmail

Пример:

validator.normalizeEmail("user.name@gmail.com");

Разные версии могут возвращать:

username@gmail.com

или

user.name@gmail.com

в зависимости от конфигурации.

Стратегии безопасной миграции

Фиксация версии

Временная защита:

{
  "validator": "13.9.0"
}

или:

{
  "validator": "^13.9.0"
}

Пошаговое обновление

Опасно:

npm install validator@latest

Предпочтительно:

npm install validator@14

с последующим тестированием.

Регрессионные тесты

Перед обновлением полезно покрывать тестами:

email;
URL;
UUID;
IP;
даты;
локализованные числа.

Антипаттерны при использовании deprecated API

Игнорирование предупреждений

Плохая практика:

// TODO: fix later
validator.toFloat(value);

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

Смешивание старого и нового API

Проблемный пример:

validator.isEmail(email, true);

validator.isURL(url, {
    require_protocol: true
});

В кодовой базе появляются разные стили использования.

Обновление без тестирования

Даже минорные изменения Validator.js способны изменить результаты проверки.

Особенно чувствительны:

международные email;
сложные URL;
Unicode;
домены верхнего уровня.

Современные рекомендации

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

Предпочтительно:

validator.isURL(url, {
    protocols: ["http", "https"],
    require_protocol: true,
    require_host: true
});

Минимизация sanitizer-функций

Часть преобразований лучше выполнять стандартными средствами Jav * aScript:

String(value).trim();

Number.parseFloat(value);

Контроль версии библиотеки

Рекомендуется:

фиксировать major-версию;
читать release notes;
проверять breaking changes;
запускать CI-тесты после обновлений.

Влияние deprecated API на архитектуру

Рост технического долга

Старые методы:

усложняют поддержку;
увеличивают риск ошибок;
мешают обновлению зависимостей.

Проблемы безопасности

Устаревшие проверки могут:

пропускать вредоносные данные;
допускать обход валидации;
быть уязвимыми к ReDoS.

Снижение переносимости кода

Код со старыми API хуже адаптируется:

к новым версиям Node.js;
к современным сборщикам;
к TypeScript;
к ESM-модулям.

Практический пример полной миграции

Старый код

const validator = require("validator");

function validate(data) {
    return validator.isEmail(data.email, true) &&
           validator.isURL(data.site, true);
}

Обновлённый код

const validator = require("validator");

function validate(data) {
    return validator.isEmail(data.email, {
        allow_display_name: true
    }) &&
    validator.isURL(data.site, {
        require_protocol: true
    });
}

Совместимость с TypeScript

Устаревшие методы особенно проблемны в TypeScript-проектах.

Причины:

deprecated-метки в typings;
ошибки типов;
удаление старых сигнатур;
несовместимость перегрузок.

Пример предупреждения:

'toFloat' is deprecated.

Автоматизация миграции

ESLint

Плагины способны:

запрещать deprecated API;
автоматически исправлять код;
контролировать стиль вызовов.

Codemods

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

validator.isEmail(email, true);

→

validator.isEmail(email, {
    allow_display_name: true
});

Подходы к поддержке legacy-кода

Адаптерный слой

Иногда создаётся совместимый API:

function validateEmail(email, allowDisplayName) {
    return validator.isEmail(email, {
        allow_display_name: allowDisplayName
    });
}

Постепенная замена

В больших проектах миграция выполняется:

модуль за модулем;
через feature branches;
с параллельной поддержкой старого API.

Особенности deprecated API в разных версиях

Validator.js 9–10

Характерные особенности:

активное использование позиционных параметров;
менее строгие проверки;
ограниченная Unicode-поддержка.

Validator.js 11–13

Изменения:

переход к объектам опций;
усиление RFC-совместимости;
улучшение TypeScript-типов;
удаление неоднозначных методов.

Современные версии

Тенденции:

строгая типизация;
безопасные регулярные выражения;
улучшенная Unicode-валидация;
минимизация legacy API.