오늘은 그냥 가볍게 WebSocket이랑 STOMP가 뭔지 한 번 정리해보려고 한다.
프로젝트 하다 보면 채팅이나 알림 같은 실시간 기능을 넣어야 할 때가 있는데, 그럴 때마다 정확히 둘의 역할이 뭐였는지 살짝 헷갈릴 때가 있더라. 그래서 이번에 한 번 제대로 정리해두면 나중에 다시 볼 때 편할 것 같아서 적어본다.

📌 WebSocket

우리가 흔히 알고 있는 HTTP는 Stateless, Connectionless 하다는 특징을 가지고 있다.

즉, 클라이언트가 서버에 요청을 한 번 보내고 응답을 받으면 그 연결은 바로 끊기고, 서버는 방금 누구였는지에 대한 상태도 기억하지 못한다.

딱 요청–응답 한 번 하고 끝나는, 정말 단발성 통신 방식인 거다.

그래서 이런 구조는 일반적인 웹 페이지 요청처럼 “필요할 때만 잠깐 물어보고 받는” 작업에는 잘 맞지만, 채팅처럼 계속 대화를 이어가야 하거나 실시간으로 뭔가를 푸시해야 하는 상황에서는 한계가 있다.

바로 이 지점이 WebSocket이 등장하게 된 이유다.

WebSocket은 HTTP와는 다른 프로토콜이지만, 최초 연결 시 HTTP Upgrade 요청을 사용하기 때문에 80/443 포트를 그대로 사용할 수 있고 기존 방화벽 규칙도 재사용할 수 있도록 설계되었다.

밑에 HTTP 요청 예시를 보자

GET /chat HTTP/1.1
Host: example.com
Upgrade: websocket --- 1
Connection: Upgrade --- 2
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Origin: https://example.com

• 1: 현재 HTTP 통신을 WebSocket 프로토콜로 변경하고 싶다”라는 신호
• 2: Upgrade 헤더를 활성화하는 용도

그러면 서버는 응답을 이렇게 한다.

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

• 101 Switching Protocols
  서버가 “좋아, WebSocket 프로토콜로 전환할게”라고 승인한 것. 핸드셰이크가 성공했다는 의미

• Upgrade: websocket
  이제부터 WebSocket 프로토콜로 통신할 거라는 선언

• Connection: Upgrade
  Upgrade 헤더를 활성화하는 역할

WebSocket 동작흐름

WebSocket은 크게 3단계로 동작한다

1. Handshake(HTTP 업그레이드)
2. 양방향 프레임 통신
3. Close(종료 요청)

1. Handshake – HTTP에서 WebSocket으로 프로토콜 전환

먼저 브라우저가 서버에게 이렇게 묻는다:

🗣️ “우리 HTTP 말고 WebSocket으로 얘기할래? Protocol Upgrade 할게!”

이때 브라우저는 HTTP/1.1 GET 요청 + Upgrade 헤더를 보낸다.

서버는 요청을 보고 OK라면

🗣️ “좋아, 지금부터 WebSocket 프로토콜로 전환한다(101 Status)”

라는 응답을 보낸다.

여기까지는 완전히 HTTP 통신이다.

응답이 끝나는 순간부터는 HTTP가 끊기고 WebSocket 프로토콜이 된다.

2. 양방향 통신 – WebSocket Frame 전송

Handshake가 끝나면 이제 진짜 WebSocket이 시작된다.

이제부터는 HTTP 메시지가 아니라 프레임(Frame) 을 주고받는다.

• 브라우저 → 서버
• 서버 → 브라우저

양쪽 모두 요청/응답 관계 없이 자유롭게 메시지를 보낼 수 있다.

즉, WebSocket의 핵심 기능인 실시간 양방향 통신 단계

주고받는 데이터는 모두 WebSocket 프레임 형식이며, 텍스트 프레임 또는 바이너리 프레임으로 전송된다.

---

3. Close – 어느 한쪽에서 종료 요청

통신 중 어느 쪽이든 “그만하자”라고 Close 프레임을 보낼 수 있다.

예: 브라우저가 “끝낼게요(Close Frame)”
서버가 “오케이(Close Response Frame)” 하고 응답

또는 서버가 먼저 종료 요청할 수도 있다.

Close 프레임이 오가면 연결은 정상적으로 닫히고, WebSocket 연결이 종료된다.

SocketJS

물론 위에처럼 WebSocket 연결이 잘되면 정말 최고다. 하지만 인생처럼, 현실에서는 늘 계획대로 되지는 않는다.

회사 네트워크나 학교 와이파이, 혹은 어떤 프록시 장비들을 거치면 WebSocket 자체를 아예 막아놓은 경우가 꽤 많다.

그래서 클라이언트는 “분명 내 코드는 맞는데 왜 연결이 안 되지?” 하면서 원인을 알 수 없는 에러를 만나는 일이 생긴다.

이럴 때 등장하는 게 SockJS다.

SockJS는 한마디로 말하면,

WebSocket이 되면 WebSocket을 쓰고, 안 되면 조용히 다른 방식으로 넘어가서 최대한 WebSocket처럼 동작하게 만들어주는 안전 장치

라고 보면 된다.

웹소켓이 연결이 안 될 때, SockJS는 바로 포기하지 않고
다른 폴백(fallback) 방식들을 순서대로 시도한다.

예를 들면 XHR Streaming, Long Polling 같은 것들이다.

덕분에 개발자는 “WebSocket이 되나 안 되나” 걱정하지 않고 항상 양방향 통신이 되는 통로를 확보할 수 있다.

Spring에서 .withSockJS()를 붙이는 이유도 이거다.
WebSocket이 잘 되는 환경에서는 그냥 WebSocket로 연결하고, 문제가 있는 환경에서는 자동으로 안전한 다른 방식으로 전환된다.

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(new MyWebSocketHandler(), "/ws")
                .setAllowedOrigins("*")      // CORS 허용
                .withSockJS();
    }
}

정리하자면,

• WebSocket: 되면 빠르고 깔끔함
• SockJS: 안 되면 대신 나서서 WebSocket처럼 동작하게 만들어줌

이 정도 느낌으로 이해하면 된다.

STOMP(Simple/Stream Text Oriented Message Protocol)

STOMP는 WebSocket 위에서 동작하는 문자 기반 메시징 프로토콜로, 클라이언트와 서버가 주고받는 메시지의 유형, 형식, 구조를 명확하게 정의해주는 역할을 한다.

WebSocket은 단순히 양방향 통신 통로를 열어주는 수준이지만, STOMP는 그 통로 안에서 메시지가 어떻게 오가야 하는지에 대한 “규칙”을 제공한다고 보면 된다.

이 프로토콜은 TCP, WebSocket처럼 신뢰할 수 있는 양방향 스트리밍 네트워크 프로토콜 위에서 사용할 수 있도록 설계되어 있다. STOMP 자체가 메시지 전송 규약만 정의할 뿐, 실제 전송은 하위 네트워크 프로토콜(WebSocket 등)이 담당한다.

또 하나 중요한 특징은 기본적으로 pub/sub 구조를 사용한다는 점이다. 메시지를 보내는 곳(SEND)과 메시지를 구독하는 곳(SUBSCRIBE)이 명확하게 나뉘어 있어서, 어떤 목적지로 메시지가 발행되고, 누가 그 목적지를 구독하고 있으며, 어떤 방식으로 메시지가 전달되는지가 확실하게 정해져 있다.

STOMP 역시 HTTP처럼 프레임(Frame) 기반 프로토콜이며, 각 메시지는 헤더와 바디를 갖는 특정 형식의 프레임으로 전송된다. 덕분에 메시지는 단순 문자열이 아니라 구조화된 형태로 교환될 수 있다.

요약하자면, STOMP는 WebSocket 위에서 메시지 형식과 라우팅 규칙을 정의해주는 고수준 프로토콜이며, pub/sub 패턴을 기반으로 실시간 메시징을 보다 체계적이고 안정적으로 처리할 수 있도록 도와주는 역할을 한다.

🤔 굳이 STOMP가 필요할까?

사실 WebSocket만 놓고 보면 기능이 굉장히 단순하다.

기본적으로 문자열을 주고받는 정도에 불과하고, 메시지가 누구에게 전달돼야 하는지, 어떤 목적지로 보내야 하는지, 채팅방 같은 개념은 전혀 없다. 심지어 메시지 타입조차 구분되지 않는다. 말 그대로 “열린 소켓에서 문자열을 보내고 받는다”가 끝인 셈이다.

이렇게 단순하다 보니, 실제 웹 애플리케이션을 만들 때 필요한 기능들을 전부 직접 구현해야 한다.

예를 들면,

• 특정 채팅방에만 메시지 보내기
• 특정 유저에게만 메시지 보내기
• 여러 유저에게 브로드캐스트하기
• 메시지 타입(입장/퇴장/채팅 등) 구분하기
• pub/sub 구조 설계하기

이런 것들을 매번 처음부터 만들려고 하면 사실상 개발 지옥이 펼쳐진다.

그래서 등장한 것이 바로 STOMP다.

STOMP는 WebSocket 위에서 “메시지를 어떻게 보내고 받을지”에 대한 규칙을 제공해주는 프로토콜로, WebSocket의 단순한 통신 구조에 구독, 발행, 목적지 라우팅, 메시지 구조화 같은 고수준 기능을 얹어준다.

덕분에 개발자는 복잡한 메시징 로직을 직접 만들 필요 없이, 정해진 규약에 따라 훨씬 깔끔하게 실시간 기능을 구현할 수 있게 된다.

STOMP는 WebSocket 위에서 동작하는 “메시지 규약(프로토콜)”이다. 쉽게 말하면, “WebSocket은 통로만 열어줄 뿐이고, STOMP는 그 통로 안에서 메시지를 어떤 규칙으로 주고받을지 정해주는 약속.”

STOMP 사용법에 대해 좀 더 알아보자

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void configureMessageBroker(MessageBrokerRegistry registry) {

        // 서버 → 클라이언트로 메시지를 보내는 prefix (subscribe)
        registry.enableSimpleBroker("/topic", "/queue");

        // 클라이언트 → 서버로 메시지를 보내는 prefix (publish)
        registry.setApplicationDestinationPrefixes("/app");
    }

    // 클라이언트가 WebSocket 연결을 생성하는 endpoint
    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws")
                .setAllowedOriginPatterns("*")   // CORS 허용
                .withSockJS();                   // SockJS fallback 지원
    }
}

• @EnableWebSocketMessageBroker
  STOMP 기반의 메시지 브로커 기능을 켜서, WebSocket에서 publish/subscribe 구조를 사용할 수 있게 해준다.

• registry.enableSimpleBroker("/topic", "/queue")
  즉, 클라이언트가 subscribe(구독)하는 경로를 설정하는 부분이다. 서버는 메시지를 보낼 때 해당 prefix로 시작하는 목적지로 전달한다. /topic → 여러 클라이언트에게 동시에 보내는 브로드캐스트(broadcast)
  예) 채팅방 메시지, 공지
  /queue → 특정 사용자에게만 보내는 1:1(point-to-point)
  예) 알림, 개인 메시지

• registry.setApplicationDestinationPrefixes("/app")
  즉, publish 요청을 보낼 때 사용하는 prefix를 지정한다.
  클라이언트가 /app/** 로 메시지를 보내면 Spring은 이 요청을 @MessageMapping 메서드를 찾아서 전달한다.

@MessageMapping("/hello")
public void messageHandler(...) { ... }

//  클라이언트는 이런식으로 보낸다.
stomp.send("/app/hello", {}, "안녕");

enableSimpleBroker() : 서버 → 클라이언트 메시지 전달 경로 (구독 경로)
setApplicationDestinationPrefixes() : 클라이언트 → 서버 메시지 전달 경로 (publish 경로)

1) WebSocket 연결 (Handshake)

• 클라이언트가 /ws 엔드포인트로 WebSocket 연결을 시도
• HTTP GET 요청으로 WebSocket 핸드셰이크 수행 → 서버가 Upgrade 승인
• 연결이 완료되어야 그 위에서 STOMP 프로토콜이 시작됨

HTTP 요청 예시 (클라이언트 → 서버)

GET /ws HTTP/1.1
Host: localhost:8080
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: <random_key>
Sec-WebSocket-Version: 13
Origin: http://localhost:3000

HTTP 응답 예시 (서버 → 클라이언트)

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: <hashed_key>

---

2) STOMP CONNECT

• WebSocket 연결 위에서 STOMP CONNECT frame 전송
• 서버는 CONNECTED frame으로 STOMP 세션 승인

STOMP CONNECT 예시 (클라이언트 → 서버)

CONNECT
accept-version:1.2
host:localhost
login:guest
passcode:guest
heart-beat:10000,10000

STOMP CONNECTED 예시 (서버 → 클라이언트)

CONNECTED
version:1.2
heart-beat:0,0

---

3) SUBSCRIBE

• 클라이언트가 /topic/** 또는 /queue/**를 구독(SUBSCRIBE frame)
• 서버는 구독 정보를 Simple Broker 또는 Broker Relay에 저장
• 이후 해당 destination으로 오는 메시지를 구독 클라이언트에게 전달

SUBSCRIBE 예시

SUBSCRIBE
id:sub-0
destination:/topic/greeting
ack:auto

---

4) SEND

• 클라이언트가 /app/** 경로로 메시지 발행(SEND frame)
• 서버는 setApplicationDestinationPrefixes("/app")로 라우팅
• 해당 메시지를 처리할 @MessageMapping 메서드로 전달

SEND 예시

SEND
destination:/app/greeting
content-type:text/plain
content-length:25

---

5) 메시지 브로커 전달

• Controller 처리 결과(payload)는 brokerChannel을 통해 브로커로 전달
• 브로커는 구독 정보를 참고하여 적절한 클라이언트에게 메시지 전송

---

6) MESSAGE

• 구독한 클라이언트는 SUBSCRIBE한 destination으로 MESSAGE frame 수신

MESSAGE 예시

MESSAGE
subscription:sub-0
destination:/topic/greeting
message-id:007
content-type:text/plain
content-length:25

• Simple Broker: 서버 메모리에서 바로 구독 클라이언트로 전달 → clientOutboundChannel
• Broker Relay: 외부 브로커 → 구독 클라이언트 → clientOutboundChannel

---

💡 포인트

• WebSocket 연결이 먼저 성립되어야 STOMP CONNECT, SUBSCRIBE, SEND, MESSAGE가 가능
• SUBSCRIBE와 SEND 경로에 따라 Controller 처리 또는 브로커 직접 전달 방식이 결정됨
• 전체 흐름:
  WebSocket 연결 → STOMP CONNECT → SUBSCRIBE → SEND → 브로커 → MESSAGE → 클라이언트

인메모리 메시지 브로커를 사용한다면?

Simple Broker는 클라이언트 구독(subscription)을 메모리에 저장하고, 해당 구독을 기반으로 메시지를 연결된 클라이언트에게 전달한다.

채널	역할	설명
clientInboundChannel	클라이언트 → 서버	웹소켓 클라이언트가 보낸 메시지를 서버로 전달하는 채널
clientOutboundChannel	서버 → 클라이언트	서버가 클라이언트로 메시지를 보낼 때 사용하는 채널
brokerChannel	애플리케이션 → 브로커	서버(애플리케이션)에서 Simple Broker로 메시지를 전달하는 채널

외부 메시지 브로커를 사용한다면?

Broker Relay 는 외부 STOMP 브로커(RabbitMQ 등)와 TCP로 연결, 브로커가 구독된 클라이언트에게 메시지 전달한다.

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void configureMessageBroker(MessageBrokerRegistry registry) {

        // 클라이언트 → 서버로 메시지를 보내는 prefix
        registry.setApplicationDestinationPrefixes("/app");

        // 외부 STOMP 브로커와 TCP로 연결
        registry.enableStompBrokerRelay("/topic", "/queue")
                .setRelayHost("localhost")        // 외부 브로커 호스트
                .setRelayPort(61613)             // STOMP 포트
                .setClientLogin("guest")         // 브로커 인증
                .setClientPasscode("guest")      // 브로커 인증
                .setSystemLogin("guest")         // 시스템 계정 (관리용)
                .setSystemPasscode("guest")
                .setVirtualHost("/");            // RabbitMQ 등 가상 호스트
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws")
                .setAllowedOriginPatterns("*")
                .withSockJS();
    }
}

채널	역할	설명
clientInboundChannel	클라이언트 → 서버	클라이언트가 보낸 STOMP 메시지를 수신하고 디코딩한 후, Spring Message로 변환
clientOutboundChannel	서버 → 클라이언트	브로커가 매칭된 구독자에게 STOMP frame으로 메시지를 전송
brokerChannel	애플리케이션 → 브로커	@Controller 또는 애플리케이션에서 브로커로 메시지를 전달

---

Annotated Controllers (메시지 처리 컨트롤러)

클라이언트에서 받은 메시지를 처리하기 위해 @Controller를 사용할 수 있다.

각 컨트롤러는 다음과 같은 메소드 어노테이션을 가질 수 있다.

• @MessageMapping → 목적지 기반 메시지 처리

• @SubscribeMapping → 구독 메시지 처리 (브로커를 거치지 않고 직접 클라이언트 전송)

• `@MessageExceptionHandler1 → 메시지 처리 중 발생한 예외 처리

@MessageMapping

• 클라이언트가 /app/** 경로로 보낸 메시지를 처리

• 컨트롤러 메소드나 클래스 레벨에 적용 가능

• @DestinationVariable을 사용하여 동적 경로 처리 가능

• 반환값은 MessageConverter를 통해 직렬화되어 브로커 채널로 전달

목적지 커스터마이징:

• @SendTo → 여러 목적지 또는 기본 브로드캐스트

• @SendToUser → 메시지 보낸 특정 사용자에게만 전송

@Controller
public class ChatController {

    // 클라이언트가 /app/chat으로 메시지를 보냈을 때 처리
    @MessageMapping("/chat")
    @SendTo("/topic/messages") // 모든 구독자에게 브로드캐스트
    public ChatMessage sendMessage(ChatMessage message, Principal principal) {
        // 서버에서 발신자 정보 추가
        message.setSender(principal.getName());
        message.setTimestamp(System.currentTimeMillis());
        return message;
    }

    // 특정 유저에게만 알림을 보내는 예시
    @MessageMapping("/private-alert")
    @SendToUser("/queue/alerts")
    public Alert sendPrivateAlert(Alert alert, Principal principal) {
        // 로그인한 사용자에게만 알림
        alert.setRecipient(principal.getName());
        return alert;
    }
}

@SubscribeMapping

• 구독 메시지를 처리할 때 사용

• 기본적으로 클라이언트에게 직접 응답 전송 (브로커 사용 X)

• UI 초기 데이터 전달 등에 유용

• broker와 controller를 동일 접두사에 매핑하지 않으면 메시지 충돌 방지 가능

@SubscribeMapping("/init")
public InitData getInitData() {
    return new InitData();
}

@MessageExceptionHandler

// 메시지 처리 중 예외 발생 시 처리
@MessageExceptionHandler
@SendToUser(destinations="/queue/errors", broadcast=false)
    public ErrorMessage handleException(ChatException ex) {
        return new ErrorMessage(ex.getMessage());
    }

• @MessageMapping 처리 중 발생한 예외 처리

• 반환값은 특정 사용자에게 전송 가능 (@SendToUser)

• 클래스 레벨에서만 적용하거나 @ControllerAdvice를 사용해 전역 처리 가능

메시지 비동기 처리 및 채널 쓰레드풀

Spring WebSocket + STOMP 서버는 클라이언트로부터 들어오는 메시지를 비동기적으로 처리한다.

즉, 클라이언트가 메시지를 보내면 서버는 즉시 처리하지 않고, 쓰레드풀(Thread Pool) 내에서 작업을 실행한다.

이 구조 덕분에 동시에 많은 클라이언트가 메시지를 보내도 서버는 블로킹 없이 안정적으로 처리할 수 있다.

1. 채널별 쓰레드풀

STOMP 메시지는 내부적으로 채널(Channel)을 통해 처리되며, 각 채널별로 쓰레드풀이 존재한다.

채널	역할
clientInboundChannel	클라이언트 → 서버로 들어오는 메시지 수신, 라우팅, Controller 호출 등
clientOutboundChannel	서버 → 클라이언트로 나가는 메시지 전송, 브로커 구독자 탐색 후 메시지 발송

각 채널별 쓰레드 수를 적절히 설정해야 메시지 병목을 방지하고 안정적인 처리 속도를 유지할 수 있다.

---

2. 쓰레드풀 조정 필요 상황

• 메시지 처리 중 DB 호출이나 외부 API 연동과 같이 IO 지연이 발생할 경우
• 다수 클라이언트가 동시에 메시지를 전송할 경우
• 메시지 처리량을 높여야 하는 경우

→ 이런 상황에서는 채널별 쓰레드 수를 늘리고, 큐 용량을 조정하여 처리 성능을 확보할 수 있다.

3. WebSocket 전송 제한 설정

메시지 전송 시간, 버퍼 크기 등을 제한하여 느린 클라이언트나 큰 메시지로 인한 서버 지연을 방지할 수 있다.

@Override
public void configureWebSocketTransport(WebSocketTransportRegistration registration) {
    registration
        .setSendTimeLimit(15 * 1000)        // 메시지 전송 최대 시간 15초
        .setSendBufferSizeLimit(512 * 1024) // 전송 버퍼 최대 512KB
        .setMessageSizeLimit(128 * 1024);   // 메시지 최대 크기 128KB
}

• setSendTimeLimit → 메시지 전송 최대 시간 설정
• setSendBufferSizeLimit → 버퍼 크기 제한
• setMessageSizeLimit → 한 메시지의 최대 크기 제한

1. 메시지는 비동기로 처리되며, 쓰레드풀을 통해 동시성을 확보
2. clientInboundChannel / clientOutboundChannel에 별도 쓰레드풀 존재 → 수신/전송 처리
3. IO 지연이나 외부 호출이 많은 경우 쓰레드 수를 늘려 병목 방지
4. WebSocket 전송 제한을 통해 서버 안정성과 처리 성능 확보

---

참고

• Stomp, WebSocket 개념 정리(ver. Spring)
• Spring webSocket with stomp 기본 개념 정리