Установка и подключение библиотеки

Библиотека STOMP.js используется как клиентская реализация протокола STOMP поверх WebSocket и предназначена для взаимодействия с брокерами сообщений, поддерживающими этот протокол. В современных приложениях она применяется для организации двустороннего обмена сообщениями между клиентом и сервером в реальном времени.

Установка через npm

Наиболее распространённый способ подключения STOMP.js в современных JavaScript-проектах — установка через npm-пакет.

Основной пакет:

npm install @stomp/stompjs

После установки библиотека становится доступной в проекте как модуль ES или CommonJS в зависимости от конфигурации окружения.

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

import { Client } from '@stomp/stompjs';

Использование в CommonJS:

const { Client } = require('@stomp/stompjs');

Важно учитывать, что современная версия библиотеки ориентирована на работу в браузерных и Node.js окружениях через единый API клиента Client.

Установка через yarn

При использовании yarn процесс аналогичен:

yarn add @stomp/stompjs

После установки импортирование выполняется теми же способами, что и в npm-сценарии.

Подключение через CDN

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

<script src="https://cdn.jsdelivr.net/npm/@stomp/stompjs@7.0.0/bundles/stomp.umd.min.js"></script>

После подключения библиотека становится доступной через глобальный объект:

const client = new StompJs.Client();

CDN-версия удобна для прототипов, тестов и небольших страниц, но ограничена по возможностям конфигурации сборки.

Требования к окружению

STOMP.js работает поверх WebSocket, поэтому наличие поддержки WebSocket в среде выполнения является обязательным.

В браузерах поддержка WebSocket встроена:

const ws = new WebSocket('ws://localhost:8080/ws');

В Node.js WebSocket не является встроенным API, поэтому требуется дополнительная библиотека:

npm install ws

И подключение через настройку глобального объекта:

import WebSocket from 'ws';

global.WebSocket = WebSocket;

Это позволяет STOMP.js использовать WebSocket в серверной среде.

Создание клиента STOMP

Основной объект библиотеки — Client. Он инкапсулирует подключение, переподключение, отправку и подписку на сообщения.

Базовая инициализация

import { Client } from '@stomp/stompjs';

const client = new Client({
  brokerURL: 'ws://localhost:8080/ws'
});

Параметр brokerURL указывает адрес WebSocket-соединения брокера сообщений.

Подключение через фабрику WebSocket

В случаях, когда требуется кастомизация создания WebSocket (например, SockJS или дополнительные параметры), используется webSocketFactory.

import { Client } from '@stomp/stompjs';

const client = new Client({
  webSocketFactory: () => {
    return new WebSocket('ws://localhost:8080/ws');
  }
});

Этот вариант применяется при необходимости полного контроля над созданием соединения.

Инициализация соединения

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

client.activate();

Метод activate() запускает процесс подключения к брокеру. Внутри он создаёт WebSocket-соединение и выполняет STOMP handshake.

Отключение выполняется методом:

client.deactivate();

Обработка жизненного цикла соединения

STOMP.js предоставляет набор callback-хуков для управления состоянием соединения.

Подключение и успешная авторизация

client.onConn ect = (frame) => {
  console.log('Соединение установлено');
};

frame содержит данные STOMP-ответа брокера, включая заголовки.

Ошибки соединения

client.onStompEr ror = (frame) => {
  console.error('STOMP ошибка:', frame.headers['message']);
};

Этот обработчик вызывается при ошибках протокольного уровня, например при отказе брокера.

Ошибки транспорта

client.onWebSocketEr ror = (event) => {
  console.error('WebSocket ошибка', event);
};

Используется для отслеживания проблем на уровне транспортного соединения.

Закрытие соединения

client.onWebSocketCl ose = () => {
  console.log('Соединение закрыто');
};

Параметры конфигурации клиента

STOMP.js предоставляет набор параметров для управления поведением клиента.

reconnectDelay

Задает задержку автоматического переподключения:

const client = new Client({
  brokerURL: 'ws://localhost:8080/ws',
  reconnectDelay: 5000
});

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

heartbeat

Механизм проверки живости соединения:

const client = new Client({
  brokerURL: 'ws://localhost:8080/ws',
  heartbeatIncoming: 4000,
  heartbeatOutgoing: 4000
});

heartbeatIncoming — интервал ожидания сообщений от сервера heartbeatOutgoing — интервал отправки heartbeat на сервер

debug

Функция логирования внутренних событий:

const client = new Client({
  brokerURL: 'ws://localhost:8080/ws',
  debug: (str) => {
    console.log(str);
  }
});

Используется для отладки соединения, STOMP-фреймов и состояния клиента.

Подключение с заголовками авторизации

STOMP позволяет передавать заголовки при установлении соединения.

client.connectHeaders = {
  login: 'user',
  passcode: 'password'
};

Эти данные отправляются в STOMP CONNECT frame и используются брокером для авторизации.

Подключение к защищённому WebSocket

При использовании токенов JWT:

const client = new Client({
  brokerURL: 'ws://localhost:8080/ws',
  connectHeaders: {
    Authorization: 'Bearer токен'
  }
});

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

Особенности работы в браузере и Node.js

В браузере STOMP.js напрямую использует встроенный WebSocket API без дополнительных зависимостей.

В Node.js необходимо:

  1. Установить WebSocket реализацию
  2. Передать её в глобальную область
  3. Или использовать webSocketFactory

Пример для Node.js:

import { Client } from '@stomp/stompjs';
import WebSocket from 'ws';

global.WebSocket = WebSocket;

const client = new Client({
  brokerURL: 'ws://localhost:8080/ws'
});

client.activate();

Типичные ошибки при подключении

Неверный URL брокера

Подключение не устанавливается при использовании HTTP вместо WebSocket:

ws://localhost:8080/ws  // корректно
http://localhost:8080/ws // некорректно

Отсутствие WebSocket в Node.js

Ошибка возникает при отсутствии polyfill:

ReferenceError: WebSocket is not defined

Решается установкой пакета ws.

Несовпадение протоколов

Если сервер не поддерживает STOMP поверх WebSocket, соединение устанавливается, но сообщения не обрабатываются.

Структура STOMP клиента после подключения

После активации клиент имеет следующие ключевые компоненты:

  • транспорт WebSocket
  • STOMP session
  • очередь подписок
  • очередь отправки сообщений
  • менеджер переподключения

Эти компоненты работают асинхронно и управляются внутренним event loop библиотеки.

Поведение автоматического переподключения

При включённом reconnectDelay клиент автоматически пытается восстановить соединение:

  1. фиксируется разрыв WebSocket
  2. активируется таймер
  3. создаётся новое соединение
  4. восстанавливаются подписки (если включена логика повторной подписки)

Это позволяет использовать STOMP.js в нестабильных сетевых условиях без ручного контроля соединения.

Оглавление