DTO, validation и pipes в NestJS: как не пускать мусор дальше контроллера

•
Опубликовано
•
15 мин чтения

Текст написан с позиции мая 2018 года: так, как тема выглядела тогда, без технологий и событий, появившихся позже.

У любого серверного приложения есть один очень неприятный тип технического долга, который поначалу почти не выглядит опасным. Это момент, когда система начинает слишком доверять входящим данным. Клиент прислал тело запроса — значит, наверное, оно более или менее правильное. Пара полей проверится по дороге, остальные как-нибудь разберутся в сервисе. Если чего-то не хватает, логика ниже по стеку сама это почувствует. Если типы не совпали, то ошибка всплывет уже ближе к реальной операции. На раннем этапе разработки такой подход кажется почти естественным. Хочется быстрее собрать работающий endpoint, не перегружать код лишней формальностью и не расписывать заранее весь контракт входных данных. Но как только приложение растет, именно эта мягкость к мусору на входе начинает разрушать архитектуру изнутри.

Самая вредная реакция на эту тему — услышать слова «DTO» и «валидация» и решить, что речь про бюрократию: лишние классы, декораторы ради декораторов, корпоративную многослойность, которую тащат в проект из привычки. На самом деле проблема не в красоте слоев, а в том, что граница приложения должна быть настоящей границей. Это не вопрос эстетики, а вопрос того, кто отвечает за форму данных в системе.

В NestJS проблема особенно хорошо видна потому, что сам фреймворк очень явно подталкивает к более дисциплинированному устройству сервера. Если уж у нас есть контроллеры, сервисы, модули и dependency injection, то становится странно позволять случайным, непроверенным данным бесконтрольно проходить через всю систему. Контроллер должен быть границей. А любая хорошая граница делает не только маршрутизацию и делегирование, но и санитарную работу. Она решает, что имеет право попасть внутрь приложения, а что должно быть остановлено на входе. Именно здесь DTO, validation и pipes складываются в одну из самых практичных и зрелых архитектурных привычек.

Зафиксируем сразу главную мысль, к которой мы будем возвращаться: задача этого слоя не в том, чтобы сделать код «как в серьезных фреймворках», а в том, чтобы не пускать мусор дальше контроллера. Все остальное — следствие.

DTO — это не лишний слой абстракции, а способ разорвать клубок входных данных

Разговор про DTO в JavaScript и TypeScript-среде у многих поначалу вызывает легкое раздражение. Слово звучит по-корпоративному, как будто из мира, где любят слои абстракции ради самого существования слоев. Хочется спросить: неужели нельзя просто принять req.body, вытащить нужные поля и передать их дальше? Технически, конечно, можно. И в маленьком приложении это даже некоторое время работает. Но проблема в том, что такой стиль очень быстро смешивает несколько разных вещей в одну неоформленную массу. В одном и том же месте у вас оказываются транспортная форма запроса, внутренняя модель данных, частичная валидация, случайные преобразования и неявные предположения о том, что клиент вообще должен был прислать. DTO полезен прежде всего тем, что разрывает этот клубок.

Если говорить просто, DTO — это явное описание формы данных, которую контроллер готов принять или вернуть. То есть не «любой объект с какими-то полями, которые мы потом попробуем использовать», а конкретный контракт на входе. В NestJS это особенно естественно, потому что TypeScript и декораторный стиль уже подталкивают нас мыслить систему как набор хорошо определенных ролей. Контроллер принимает DTO. Сервис получает уже осмысленные данные. Валидация не размазана по бизнес-логике. Pipes выполняют преобразование и фильтрацию на границе. И вся система начинает звучать намного спокойнее: сначала мы проверяем, что к нам пришло, и только потом считаем это входом для прикладной логики.

Именно поэтому хороший контроллер — это не место, где «что-то быстро приняли и передали дальше». Это место, где происходит формализация входа. И DTO здесь полезен не только как тип для редактора или компилятора. Его главная ценность в том, что он заставляет явно ответить на вопрос: какие именно данные этот endpoint принимает, какие поля обязательны, какие нет, какие ограничения должны соблюдаться, и что вообще считается валидным запросом. Как только эта форма описана, вокруг нее уже можно строить validation и pipes. Без этого валидация почти неизбежно становится либо разрозненной, либо декоративной.

Самый дорогой мусор — не тот, что упал сразу, а тот, что прошел чуть дальше границы

Почему это так важно? Потому что самый дорогой мусор — это не мусор, который вызвал ошибку сразу. Самый дорогой мусор — это данные, которые формально прошли чуть дальше, чем следовало, и начали отравлять логику в глубине системы. Например, контроллер принял строку там, где дальше ожидается число. Или пришел пустой email, который никто не отфильтровал на входе, и он дожил до слоя сохранения. Или в запросе оказался лишний флаг, который не должен был приниматься вообще, но тихо проскочил внутрь. Или поле, считавшееся обязательным, на самом деле пропало, а код ниже просто сделал неправильное предположение. Во всех этих случаях проблема уже не в удобстве API, а в том, что граница системы перестала быть границей. Она пропустила шум, и этот шум стал внутренней проблемой приложения.

Очень важно понимать, что DTO — это не внутренняя доменная модель и не полная серверная сущность. Это именно форма передачи данных на конкретной границе. Эта мысль часто недооценивается, и отсюда начинается много архитектурной путаницы. Например, объект пользователя в базе и DTO создания пользователя — это не одно и то же. DTO может содержать только имя, email и пароль. Сущность в базе будет содержать id, служебные поля, дату создания, возможно внутренние признаки и много другого. Если эти уровни смешивать, валидация быстро становится нелепой, а приложение начинает жить так, будто входящий JSON уже почти равен внутреннему состоянию системы. В хорошем NestJS-коде DTO, наоборот, помогает удерживать различие между внешним контрактом и внутренней моделью.

TypeScript описывает форму, но именно validation отвергает мусор в runtime

Validation в этой картине выполняет очень прямую и очень важную работу: она превращает DTO из описания намерения в реальный фильтр на входе. Пока у вас есть только класс или интерфейс, вы формально знаете, какой формы ждете данные, но система еще не обязательно умеет отвергать неверные значения в реальном runtime. А backend живет не в мире идеальных компиляторов, а в мире HTTP-запросов от внешних клиентов, где на вход может прийти все что угодно. Неправильная строка, пустое значение, массив вместо объекта, отрицательное число там, где ожидалось положительное, невалидный email, слишком короткий пароль, поле неожиданного типа, набор лишних свойств. TypeScript сам по себе не защищает от этого, потому что он не проверяет форму входящих сетевых данных на лету. Поэтому валидация на уровне реального запроса — это уже не приятный бонус, а обязательная санитария.

Здесь важно не перепутать два разных мира. TypeScript работает на этапе компиляции и описывает намерение: каким мы хотим видеть вход. Но сетевой запрос приходит уже после того, как все типы стерты, и сервер обязан проверить форму данных заново, на лету. То есть валидация — это не дубликат типов, а единственное место, где намерение действительно становится проверкой. Один уровень говорит, как должно быть; другой обеспечивает, что иначе и не будет.

Pipes делают санитарию входа системной, а не вопросом ручной добросовестности

NestJS особенно хорош тем, что не предлагает решать задачу хаотично в каждом контроллере вручную. Он дает pipes как выделенный слой преобразования и проверки данных, то есть как официальный механизм работы с аргументами контроллера до того, как они попадут внутрь метода. Это очень сильное архитектурное решение. Вместо того чтобы каждый раз вручную парсить, проверять и отбрасывать неправильные значения в теле контроллера, вы получаете место, где эта работа может быть сосредоточена системно. А системность в таких вещах важнее всего. Потому что хаос валидации почти всегда хуже ее отсутствия: в одном endpoint что-то проверяется, в другом — нет, в одном месте строка в число превращается руками, в другом — молча проходит дальше, в третьем — выбрасывается исключение на полпути в сервисе.

Pipes хороши именно тем, что делают подобное поведение предсказуемым. Контроллер начинает получать не сырой мусорный вход, а уже данные, прошедшие определенный набор правил. Это очень напоминает хороший пропускной пункт на границе: если что-то не соответствует договору, оно не едет дальше в глубину страны. Такой подход полезен не только для защиты от ошибок, но и для ясности кода. Сервис уже не обязан думать о том, был ли email вообще строкой, пришло ли поле, не пустое ли оно, можно ли считать параметр id числом, и так далее. Все это должно быть решено раньше. Сервис получает данные, с которыми уже можно работать как с осмысленным вводом, а не как с потенциальным мусором.

Это, кстати, одна из самых важных границ ответственности в NestJS-приложении. Как только валидация начинает проникать глубоко в сервисы, бизнес-логика обрастает посторонней обязанностью. Ей приходится не только решать прикладную задачу, но и постоянно защищаться от некорректного внешнего ввода. В результате сервисы становятся шумными, тесты — сложнее, а логика — менее читаемой. Когда же вход фильтруется на уровне DTO и pipes, бизнес-слой можно держать в гораздо более чистом состоянии. Он по-прежнему должен проверять прикладные инварианты, конечно. Но это уже не та же самая задача, что и санитарная проверка формы входящего HTTP-запроса.

Валидация формы и проверка бизнес-смысла — это не один уровень, а два разных вопроса

Полезно особенно четко различать эти два уровня. Validation на границе отвечает на вопрос: «похоже ли это на корректный запрос нужной формы?» Прикладная логика отвечает на вопрос: «имеет ли эта операция смысл в текущем состоянии системы?» Например, email как строка правильного формата и пароль нужной длины — это задача валидации DTO. А вопрос, можно ли создать пользователя с таким email, если он уже занят, — это уже задача бизнес-логики. Когда эти уровни смешиваются, код начинает звучать неуверенно. А NestJS, наоборот, очень хорошо располагает к тому, чтобы их развести.

Важную роль здесь играет и то, что DTO с validation-декораторами становится не просто внутренней технической деталью, а фактически документацией контракта. Когда разработчик открывает контроллер или DTO-класс, он видит не расплывчатое «ожидается объект с какими-то полями», а конкретную форму входа: здесь строка, здесь обязательное поле, здесь минимальная длина, здесь email, здесь число, здесь, возможно, необязательный параметр. Это полезно и для самой команды, и для будущего сопровождения. Многие проблемы серверного кода начинаются не с отсутствия логики, а с отсутствия ясности на входах. DTO и validation делают эту ясность встроенной частью кода.

Есть и еще один важный архитектурный эффект: как только у вас появляются DTO и pipes, контроллеры начинают естественным образом худеть. Они перестают быть местом ручной обработки каждой мелочи. Не нужно внутри метода проверять длину строки, валидность email, наличие обязательных полей, диапазон числа, парсинг query-параметров и тому подобное. Все это либо уже описано на DTO, либо вынесено в pipe. В результате метод контроллера может звучать почти как декларация сценария: принять проверенные данные, вызвать сервис, вернуть результат. Для фреймворка, который и так делает ставку на структурный порядок, это очень в духе всей архитектуры.

Мусор приходит не только в body — параметры маршрута и query тоже часть границы

Отдельно стоит поговорить о параметрах маршрута и query-параметрах, потому что мусор на входе приходит не только в body. Очень часто именно здесь начинаются мелкие, но неприятные проблемы: id приходит строкой, хотя логика дальше ожидает число; параметр пагинации имеет неожиданное значение; флаг приходит как странный текст; сортировка содержит неподдерживаемое поле. Pipes здесь особенно полезны, потому что позволяют сделать преобразование и проверку входа частью официального жизненного цикла аргументов контроллера.

И это снова тот случай, где структура оказывается лучше ручной добросовестности. Не в том дело, что разработчик ленив или невнимателен, а в том, что любая проверка, которую нужно помнить и повторять руками в каждом методе, рано или поздно будет пропущена. Когда же у команды есть системный способ сказать «этот параметр должен быть числом и не должен пойти дальше, если это не так», качество всей границы перестает зависеть от настроения и спешки конкретного дня. Это не вопрос дисциплины отдельного человека, а вопрос того, заложена ли санитария входа в саму конструкцию.

DTO ради галочки не спасает ничего, а pipe со всей логикой мира ломает всё заново

Здесь важно не свалиться в другую крайность и не считать, что само наличие DTO уже всё решает. Хуже всего превратить DTO и validation в механический ритуал. Команда начинает создавать DTO просто потому, что «в Nest так принято», но реальный контракт по-прежнему остается размазанным. Поля описаны слишком широко, ограничения почти отсутствуют, классы копируют друг друга, а часть важных правил по-прежнему живет где-то в сервисах или вообще в голове разработчика. В таком режиме DTO становятся бюрократией, а не пользой. Настоящий смысл этого слоя появляется только тогда, когда он действительно удерживает мусор на входе и делает форму данных явной. Если DTO создан, но не отражает настоящего контракта, он ничего не спасает.

Есть и противоположная крайность: пытаться затолкать в validation все на свете. Например, проверять там бизнес-правила, обращения к базе или сложные контекстные ограничения, которые зависят от состояния системы. Это тоже плохой путь. DTO и pipes хороши как средство обработки формы и базовой корректности входа. Как только они начинают притворяться полноценным прикладным слоем, архитектура снова размывается. Очень легко начать воспринимать pipe как место, куда можно запихнуть любую подготовительную логику перед контроллером, и в итоге получить второй скрытый сервисный слой. Важно не забывать, что у каждого инструмента здесь своя роль.

То есть цена у подхода есть, и она в дисциплине. DTO не отменяет необходимости думать о контракте — он лишь дает место, где этот контракт можно выразить честно. Слой работает ровно настолько, насколько команда готова держать его в соответствии с реальностью: не шире контракта, но и не глубже своей роли.

Ошибка, пойманная на границе, дешевле ошибки, всплывшей в середине операции

С точки зрения долгой поддержки приложения DTO, validation и pipes приносят еще одну большую пользу: они делают ошибки ближе к их источнику. Если запрос некорректен, это выясняется сразу на границе, а не в середине выполнения прикладной операции. Это очень полезно и для пользователя API, и для самой команды. Ошибка становится более предсказуемой, ее легче интерпретировать, она не маскируется под внутреннюю поломку системы. Сервер просто честно сообщает: вход не соответствует ожидаемому контракту. Такая предсказуемость кажется простой вещью, пока ее нет. Но как только команда привыкает к границе, которая действительно фильтрует мусор, возвращаться к хаотичной обработке входа уже очень не хочется.

NestJS к этому моменту уже начинает восприниматься как выбор для тех, кто хочет не просто поднять API, а строить его в более зрелом стиле. И DTO вместе с validation и pipes — это как раз один из тех участков, где зрелость становится очень практичной. Не в теории про архитектуру, а в ежедневной работе с реальными запросами. Хорошо устроенный backend отличается не только красивой модульностью, но и тем, насколько рано он умеет отличить допустимый вход от мусора. Если это не сделано на уровне контроллера и его окружения, порядок ниже по системе будет даваться намного дороже.

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

Есть и культурный эффект внутри команды. Когда у проекта есть привычка описывать DTO и валидацию явно, обсуждение API становится намного предметнее. Уже нельзя так легко сказать «ну там приходит объект с данными пользователя». Нужно уточнить: какие поля, какие ограничения, что обязательно, что опционально, что допускается на обновлении, а что только на создании, что мы принимаем в query, как парсим параметры маршрута. То есть команда вынуждена лучше думать о контрактах. А это полезно даже тогда, когда речь не только о технической чистоте, но и о качестве самого API.

Очень показательно и то, что этот подход помогает защититься не только от чужих клиентов, но и от ошибок собственной команды. Многие ошибки на сервере приходят не от злонамеренного внешнего мира, а от обычной внутренней несогласованности: фронтенд послал не ту форму, другой сервис обратился по старому контракту, новый разработчик не знал, что поле на самом деле обязательно, тест писал упрощенный payload, который случайно оказался неверным. DTO и validation работают как механическое напоминание о договоре. Они не дают слишком легко притвориться, что «ну, в целом там примерно то, что нужно».

Контроллер — это пропускной пункт, а не открытая дверь

Если подвести итог совсем прямо, то DTO, validation и pipes нужны не ради красивой многослойности и не ради желания сделать код «как в серьезных фреймворках». Они нужны потому, что граница приложения должна быть настоящей границей. Контроллер не должен становиться дверью без охраны, через которую внутрь проходит любой мусор в надежде, что его потом кто-нибудь разберет глубже в системе. DTO делает контракт явным. Validation проверяет, что вход действительно ему соответствует. Pipes превращают эту проверку и преобразование в системную часть жизненного цикла запроса.

Это не революция и не магическое решение всех проблем сервера — это сдвиг в том, где именно проходит ответственность за форму данных. Чем раньше приложение начинает относиться к своей границе серьезно, тем меньше хаоса попадает внутрь, тем чище остаются сервисы, тем спокойнее поддерживаются контракты, тем понятнее ведут себя ошибки и тем меньше у команды соблазна разбираться с мусором в тех слоях, где его уже не должно быть.

Главный практический вывод: санитария входа на NestJS — это не факультативная аккуратность и не дань моде на DTO, а базовая архитектурная привычка; зрелый backend узнается не по красоте слоев, а по тому, что мусор останавливается на контроллере и дальше не идет.

Автор

Senior Principal JavaScript Developer, Tech Lead. Пишет о React, TypeScript, React Native, архитектуре фронтенда и бэкенда и о том, как AI меняет работу разработчика.

Обновлено

Читайте также