NestJS + WebSockets: как проектировать real-time функциональность без лапши
Текст написан с позиции мая 2020 года: так, как тема выглядела тогда, без технологий и событий, появившихся позже.
К маю 2020 года real-time уже перестал быть экзотикой. Пользователь давно привык, что новые сообщения появляются без перезагрузки страницы, статус собеседника меняется на лету, а административная панель обновляет цифры сама, словно кто-то невидимый нажимает кнопку refresh каждую секунду. Но именно в этот момент многие backend-разработчики попадают в довольно знакомую ловушку: первая демонстрация работает отлично, второй экран тоже живет, а через пару недель проект превращается в клубок событий, комнат, обработчиков и странных условий, где никто уже не понимает, почему один и тот же пользователь получает уведомление трижды, а другой — не получает вовсе.
NestJS в этом смысле интересен тем, что он с самого начала предлагает структуру. Если в обычном Node.js-проекте WebSocket-слой нередко вырастает как пристройка сбоку, поверх уже существующего HTTP API, то в NestJS возникает соблазн сделать все аккуратно: завести gateway, разложить логику по сервисам, развести ответственность между транспортом и предметной областью. И это правильный соблазн. Потому что главная проблема real-time функциональности почти никогда не в том, как открыть соединение. Самая вредная реакция на эту задачу — услышать слово «WebSockets» и решить, что весь вопрос сводится к выбору библиотеки и паре строк в обработчике. Главная проблема в другом: как не превратить приложение в хаос после того, как соединений станет много, событий станет еще больше, а бизнес-логика начнет ветвиться.
Когда разработчик впервые берет в руки WebSockets, он часто мыслит очень прямолинейно. Есть событие на клиенте, есть обработчик на сервере, внутри обработчика можно что-то проверить, что-то записать в базу, а потом тут же разослать результат всем нужным клиентам. На маленьком примере это выглядит даже красиво. Но по мере роста системы внутрь gateway начинают стекаться проверки прав, валидация, доступ к репозиториям, выборка связанных сущностей, принятие решений о маршрутизации сообщений, логирование, повторные попытки и особые условия для разных типов клиентов. В этот момент gateway перестает быть транспортным адаптером и становится местом, где живет все приложение. А когда все приложение живет в одном месте, порядок заканчивается очень быстро.
Поэтому первое и, пожалуй, самое важное правило проектирования real-time в NestJS звучит так: WebSocket gateway не должен быть центром бизнес-логики. Речь не о том, что gateway плох сам по себе, — плоха ситуация, когда вся ответственность стекается в одну точку. Gateway должен быть входом и выходом. Он принимает событие, извлекает из него данные, передает управление в сервисы предметной области и затем отправляет ответ обратно — конкретному сокету, комнате или группе клиентов. Как только gateway начинает «знать» слишком много о сущностях приложения, о правилах доступа, о последовательности изменения состояния, вы уже на пути к той самой лапше, от которой потом тяжело избавиться.
Почему лапша появляется именно в real-time
С обычным REST API многие команды уже научились жить дисциплинированно. Есть контроллер, есть DTO, есть сервис, есть слой доступа к данным. Даже если реализация неидеальна, форма приложения более или менее предсказуема. С WebSockets соблазн нарушить эту дисциплину гораздо сильнее. Причина проста: соединение длительное, обмен сообщениями двусторонний, сценарии событий выглядят «живыми», и разработчик начинает мыслить не запросами к системе, а реакциями на поток действий. Это психологически подталкивает писать код кусками: «если пришло вот это событие — делаем то, потом это, потом еще отправим вот сюда».
Вторая причина — отсутствие естественной границы, которую в HTTP задает сам протокол. В запросе есть начало и конец. В WebSocket-соединении все продолжается бесконечно долго. Пользователь подключился, авторизовался, вошел в несколько комнат, получил часть данных, поменял роль в организации, потерял доступ к части сущностей, потом снова что-то запросил. Если архитектура не продумана заранее, состояние соединения начинает смешиваться с состоянием бизнес-объектов, а события — выполнять сразу и транспортную, и предметную роль. Так появляются конструкции, в которых одно событие и «обновляет чат», и «валидирует права», и «пересчитывает счетчик», и «решает, надо ли уведомить еще кого-то».
Третья причина — иллюзия скорости разработки. Пока проект небольшой, кажется, что писать прямо в gateway даже выгодно: меньше файлов, быстрее результат, меньше абстракций. Но real-time особенно коварен тем, что проблемы структуры проявляются не сразу. Сначала все работает. Потом нужно добавить еще один тип уведомлений. Потом появляется второй клиент, которому нужен похожий, но не идентичный поток событий. Потом приходится подключить горизонтальное масштабирование или хотя бы несколько процессов. И вот тогда код, который выглядел «прагматично», внезапно становится неподъемным.
Начинать стоит с предметной модели, а не с сокетов
Хороший подход — сначала вообще забыть, что у вас WebSockets, и описать предметную модель. Что именно происходит в системе? Какие действия инициирует пользователь? Какие сущности меняются? Какие события важны для других участников системы? Условно говоря, не «клиент отправил socket event send_message», а «пользователь отправил сообщение в комнату». Не «сервер эмитит online_users_changed», а «состав присутствующих в контексте изменился».
Это не словесная игра. Как только вы формулируете действия на языке предметной области, а не на языке транспорта, проектирование становится гораздо яснее. Gateway тогда превращается в переводчика: он принимает транспортное сообщение, маппит его на команду уровня приложения, вызывает сервис, получает результат и затем публикует необходимые события обратно в транспорт. При такой схеме HTTP и WebSockets перестают конкурировать друг с другом и начинают жить как два способа доступа к одной и той же логике.
Например, если у вас есть модуль чатов, полезно мыслить не в терминах «чатовый gateway», который делает все подряд, а в терминах сервисов: сервис отправки сообщения, сервис управления участниками, сервис чтения истории, сервис формирования уведомлений. Gateway лишь принимает команду от сокета. Если потом часть тех же сценариев понадобится из REST-контроллера, мобильного API или фоновой задачи, вы не окажетесь в ситуации, когда бизнес-логика заперта внутри обработчика WebSocket-события.
Gateway — это адаптер, а не сердце приложения
В NestJS gateway очень удобно выглядит как место, где «естественно» писать логику. Есть декораторы, есть доступ к клиенту, есть возможность подписываться на события подключения и отключения, можно легко работать с rooms, особенно если используется Socket.IO. Но именно из-за этого удобства стоит быть особенно осторожным.
Идеальный gateway отвечает на три вопроса. Первое: кто подключился и можно ли ему разрешить соединение? Второе: как преобразовать входящее событие в вызов сервиса? Третье: кому и в каком виде отдать результат? Все остальное должно происходить за его пределами. Проверка прав доступа к сущности — в сервисах или guards. Валидация входных данных — в DTO и pipes. Работа с базой — в репозиториях или провайдерах доступа к данным. Доменные решения о том, кого уведомлять и почему, — в отдельном слое приложения.
Если держать эту границу, код остается управляемым даже при росте функциональности. Если нет — каждая новая фича начинает «немного дописывать» gateway, и довольно скоро любой обработчик события превращается в десятки строк условий, вызовов и побочных эффектов.
Команды внутрь, события наружу
Одна из самых полезных ментальных моделей для real-time — разделять команды и события. Команда — это запрос на изменение состояния. Событие — это факт, что что-то уже произошло. Пользователь отправляет команду «создать сообщение», «пометить уведомление прочитанным», «войти в комнату». Система после успешной обработки публикует события: «сообщение создано», «уведомление помечено прочитанным», «пользователь присоединился».
На практике это дисциплинирует код сильнее, чем кажется. Когда входящие сообщения от клиента воспринимаются как команды, вы перестаете рассылать данные «на полпути», до принятия решения. А когда исходящие сообщения воспринимаются как события уже свершившегося факта, становится проще обеспечить согласованность между базой и тем, что видят клиенты.
Это особенно важно для сценариев, где есть несколько участников. Скажем, в чате нельзя сначала разослать всем сообщение, а потом надеяться, что запись в базу пройдет успешно. Иначе клиенты увидят одно, а история сообщений сохранит другое. Намного надежнее сначала завершить действие на уровне приложения, а затем публиковать результат как событие.
Даже если вы не внедряете формально CQRS и не строите сложную шину событий, само разделение по смыслу уже помогает. Gateway принимает команды. Сервисы меняют состояние. После этого публикуются события для транспорта.
Не привязывайте бизнес-логику к Socket.IO API
В NestJS WebSocket-слой часто строится поверх Socket.IO, и это удобно. Есть комнаты, acknowledgements, встроенная модель именованных событий. Для большинства веб-приложений это практичный выбор. Но именно здесь многие делают архитектурную ошибку: позволяют особенностям Socket.IO просочиться глубоко в код приложения. И проблема не в том, что Socket.IO плох, а в том, что любой неконтролируемый транспортный слой, проросший сквозь предметную логику, рано или поздно становится дорогим.
Если ваши сервисы начинают принимать объект сокета, сами вызывать join, leave, emit и разруливать комнаты, вы привязываете предметную логику к конкретному транспортному механизму. В короткой перспективе это кажется удобным. В длинной — делает код хрупким. Любое изменение схемы доставки сообщений, появление второго транспорта или необходимость тестировать доменную логику без поднятого сокет-сервера превращаются в проблему.
Гораздо здоровее, когда сервисы оперируют собственными понятиями: пользователь, канал, подписка, получатели, событие предметной области. А слой доставки уже решает, в какую комнату Socket.IO это перевести, каким именем события отправить и кому именно транслировать. Такая развязка не только улучшает тестируемость, но и помогает мыслить системой, а не библиотекой.
Авторизованный сокет — не пожизненный пропуск
Один из самых недооцененных вопросов — что именно означает «авторизованный сокет». В HTTP все привычно: запрос пришел, токен проверили, права определили, ответ вернули. В WebSockets соединение живет долго, а значит, контекст пользователя тоже должен жить долго. Возникает соблазн положить в сокет все, что известно о пользователе, и затем полагаться на это в дальнейших обработчиках.
Частично это разумно. Идентификатор пользователя, базовые данные сессии, список ролей на момент подключения — все это может быть сохранено в контексте соединения. Но здесь важно не перейти грань. Чем больше mutable-состояния вы храните внутри соединения, тем выше риск рассинхронизации. Пользователь мог потерять доступ к организации после подключения. Роль могла измениться. Участие в комнате могло быть отозвано. Поэтому нельзя считать сокет самодостаточным источником истины о правах доступа на весь срок жизни соединения.
Практический вывод простой: в контексте соединения храните минимум, необходимый для идентификации и базовой маршрутизации. Все чувствительные проверки доступа к конкретным сущностям выполняйте в сервисах в момент обработки команды. Иначе вы однажды обнаружите, что давно отозванный пользователь все еще видит свежие события просто потому, что когда-то успешно подключился.
Комнаты — это механизм доставки, а не модель предметной области
Rooms в Socket.IO очень полезны, но ими легко злоупотребить. Как только комнаты появляются, хочется моделировать через них буквально все. Комната проекта, комната команды, комната приватного чата, комната уведомлений, комната для конкретной карточки, комната для счетчиков, комната для админов конкретного клиента. Через месяц названия комнат начинают напоминать внутренний язык системы, который никто толком не документировал.
Проблема в том, что комната — это всего лишь удобный способ групповой доставки сообщений. Это не полноценная бизнес-сущность и не гарант целостности доступа. Если разработчик начинает мыслить «пользователь в комнате, значит, он имеет право получать все из этой комнаты», архитектура становится опасной. Членство в комнате должно быть производным от правил доступа, а не заменять их.
Хорошая практика — иметь четкую стратегию именования комнат и четкое понимание, кто отвечает за присоединение и выход. Лучше, если присоединение к комнате проходит через понятный слой приложения: пользователь подписывается на сущность, сервис проверяет право, и только затем транспортный слой выполняет join. Тогда комната остается механизмом, а не источником правды.
Не смешивайте запрос-ответ и push без необходимости
WebSockets создают ощущение, что теперь любой обмен данными можно строить только через события. Но это не всегда хороший путь. В реальном приложении есть как минимум два разных сценария. Первый — клиент хочет инициировать действие и получить подтверждение или ошибку. Второй — сервер сам должен сообщить клиенту о внешнем изменении. Эти сценарии похожи технически, но различаются по смыслу.
Если все свалить в единый поток «событий», клиентская логика быстро усложняется. Начинаются запутанные ожидания ответа на событие, отдельные таймауты, дублирующие обработчики, попытки понять, что из пришедшего является реакцией на собственное действие пользователя, а что — независимым push-обновлением. Поэтому полезно проектировать протокол так, чтобы команда пользователя имела явный результат, а push-события были отдельным, семантически чистым каналом доставки изменений.
Иными словами, «создать сообщение» — это инициируемое действие с валидируемым входом и явным исходом. А «сообщение добавлено в комнату» — уже событие, которое может прийти всем подписанным участникам, в том числе отправителю. Когда эти роли не смешаны, клиент и сервер живут гораздо спокойнее.
Любое действие однажды придет дважды
Сегодня уже вполне очевидно, что мобильные сети нестабильны, вкладки браузера дублируются, клиентский код может ретраить действия, а пользователь — нажимать одну кнопку несколько раз. В WebSocket-мире это приводит к неприятным эффектам: одно сообщение создается дважды, одно уведомление уходит нескольким каналам, один и тот же счетчик увеличивается больше чем нужно.
Поэтому real-time функциональность нельзя проектировать так, будто каждое действие происходит ровно один раз. Если операция критична, ей нужен способ защиты от дублей. Иногда это клиентский request id, который сервер учитывает при обработке. Иногда — уникальный бизнес-ключ. Иногда — транзакционная проверка на уровне базы. Конкретный механизм зависит от сценария, но игнорировать проблему нельзя.
Это как раз тот случай, где «просто отправим событие и посмотрим» быстро ломается в боевых условиях. Реальное приложение почти всегда живет в среде повторов, гонок и нестабильных соединений.
О масштабировании стоит думать раньше, чем кажется
Многие backend-разработчики откладывают вопрос масштабирования WebSockets до «потом». На одном процессе все ведь и так работает. Но архитектурные решения, которые кажутся безобидными в монолите на одном экземпляре, могут очень больно ударить, когда приложение потребуется запускать в нескольких процессах или на нескольких серверах.
Классический пример — хранение критического состояния только в памяти процесса: кто на что подписан, какие пользователи онлайн, какие transient-флаги установлены для маршрутизации. На одной ноде это удобно. На нескольких — мгновенно превращается в источник несогласованности. Один пользователь подключен к процессу A, событие обрабатывается процессом B, а информация об активных подписках есть только в памяти A.
Это не значит, что любое состояние надо немедленно выносить наружу. Но важно заранее различать: что является чисто транспортным локальным состоянием, а что нужно системе в целом. Если система должна знать присутствие пользователя глобально, одного хранения в памяти gateway недостаточно. Если событие должно быть доставлено клиентам, подключенным к разным экземплярам приложения, нужна межпроцессная координация. В экосистеме Node.js для этого часто используют Redis как брокер для адаптеров и синхронизации распространения событий. Даже если вы не внедряете это с первого дня, проектировать стоит так, чтобы такая возможность не ломала весь код.
Real-time — способ доставки, а не отдельный модуль
NestJS особенно хорош там, где у вас есть четкие модули. И real-time здесь не исключение. Ошибка многих проектов в том, что они создают один большой realtime-модуль, куда складывают все gateway и сопутствующие сервисы. Формально это удобно, но логически вредно. Потому что real-time — это не отдельная предметная область. Это способ доставки и взаимодействия, который должен быть встроен в существующие доменные модули.
Если у вас есть модуль чатов, он и должен владеть логикой чатов, в том числе real-time аспектом. Если есть модуль уведомлений — он должен определять правила уведомлений. Gateway может жить рядом с модулем, но не должен становиться надстройкой, через которую проходят все сущности системы. Иначе вы незаметно строите второй параллельный backend, только на сокетах.
Хорошая модульность в NestJS дает еще одно преимущество: проще тестировать и проще заменять транспорт. Логика остается внутри модулей, а gateway лишь подключается к ней как адаптер.
Протокол сообщений тоже должен быть контрактом
Еще один источник лапши — неформальный протокол сообщений. Пока команда маленькая, все договорились «на словах», что событие room:join приходит с полем roomId, а событие message:create — с text и roomId. Но без явной валидации и формализации это знание начинает расползаться. Один клиент отправляет число, другой строку, третий вообще забывает обязательное поле. В обработчиках появляются защитные if, возвраты ошибок в произвольной форме, и протокол деградирует.
В NestJS есть все инструменты, чтобы этого избежать: DTO, pipes, guards, exception filters. Их стоит использовать в WebSocket-слое столь же дисциплинированно, как и в HTTP. Клиентское событие должно иметь четкий контракт. Ошибка должна быть предсказуемой по форме. Сервер должен уметь последовательно отвечать на проблемы валидации, авторизации и бизнес-ограничений. Это не «лишняя строгость», а фундамент для поддержки проекта спустя месяцы.
Чем формальнее ваш протокол, тем меньше шанс, что через некоторое время gateway превратится в набор частных соглашений, известный только двум разработчикам и одному фронтендеру.
Без корреляции в логах real-time-инцидент не разобрать
В обычном HTTP-приложении у каждого запроса есть довольно естественный жизненный цикл. В real-time все сложнее. Один пользователь мог открыть три вкладки, каждая создала соединение, одна из них переподключилась, затем два разных события одновременно запустили близкие сценарии. Если логирование не продумано, разбирать инциденты становится мучительно трудно.
Поэтому уже на старте стоит договориться, что именно вы логируете: подключение, отключение, попытку авторизации, подписку на сущность, выполнение критичных команд, ошибки доставки, аномальные повторы. Желательно иметь хотя бы минимальную корреляцию: пользователь, идентификатор соединения, имя события, ключевая сущность сценария. Это не роскошь. Это единственный способ понять, что происходит, когда real-time слой начинает жить под нагрузкой.
Особенно полезно отделять технические события транспорта от бизнес-событий приложения. Тогда можно видеть, где проблема: в сети, в соединениях, в маршрутизации или в самой предметной логике.
Когда WebSockets действительно нужны, а когда нет
Надо честно признать: WebSockets все еще нередко применяют шире, чем нужно. Иногда задача решается обычным polling или периодическим обновлением данных без всяких постоянных соединений. Не каждый счетчик обязан обновляться в ту же миллисекунду. Не каждый экран выигрывает от двустороннего канала. Чем сложнее транспорт, тем выше цена сопровождения.
Это не аргумент против WebSockets. Это аргумент против их бездумного использования. Если у вас чат, совместная работа, статусы присутствия, онлайн-оповещения, игровые или торговые сценарии — real-time более чем оправдан. Но если речь о таблице, которая обновляется раз в несколько минут, возможно, архитектурно проще и надежнее выбрать более спокойный механизм.
Самое плохое, что можно сделать, — использовать WebSockets не потому, что задача этого требует, а потому, что технология кажется современной. В долгой перспективе архитектура всегда важнее модности.
Меньше магии, больше явных потоков
Если свести все советы к одному рабочему принципу, он будет звучать так: проектируйте real-time как систему явных потоков, а не как набор реакций «по месту». Должно быть ясно, какая команда приходит, какой сервис ее обрабатывает, какое состояние меняется, какое событие публикуется и кто именно его получает. Каждый шаг должен быть объясним.
Как только в системе появляются скрытые побочные эффекты, неявные подписки, самопроизвольные рассылки «в пару комнат на всякий случай» и прямой доступ к сокетам из глубины сервисов — вы уже начали движение к лапше. Возможно, код все еще работает. Но он перестает быть прозрачным. А непрозрачный real-time-код особенно дорог в поддержке, потому что его ошибки редко проявляются локально и предсказуемо.
Итог
NestJS сам по себе не спасает от плохой архитектуры. Но он дает достаточно правильных строительных блоков, чтобы real-time функциональность не превращалась в хаос. Если использовать gateway как адаптер, держать бизнес-логику в сервисах, различать команды и события, не путать комнаты с моделью доступа, валидировать контракты и думать о масштабировании заранее, система остается живой и управляемой даже по мере роста.
Настоящая ценность хорошего проектирования видна не в день, когда вы впервые увидели сообщение, прилетевшее без перезагрузки страницы. Она видна через несколько месяцев, когда в проекте уже десятки событий, несколько типов клиентов, сложные права доступа и требования к надежной доставке. Вот тогда становится ясно, строили вы real-time как архитектуру или просто наращивали обработчики один на другой.
И если хочется сформулировать главный совет совсем по-простому, то он будет таким: не пишите приложение внутри gateway. Пишите приложение как приложение. А WebSockets пусть останутся тем, чем им и стоит быть, — хорошим транспортом для своевременной доставки событий.