Spring WebSocket实时消息推送实战：从入门到分布式集群的全链路指南

在实时交互场景中，比如在线聊天、订单状态通知、系统监控告警，HTTP短轮询或长轮询方案存在性能瓶颈：据鳄鱼java社区2026年《实时交互性能调研》显示，短轮询的QPS仅能达到500，且每次请求携带大量HTTP头信息，服务器CPU占用率高达70%；而Spring Websocket实时消息推送实战基于TCP长连接实现，QPS可突破10000，服务器CPU占用率降至15%以下，同时实现消息的主动推送，将消息延迟从秒级压缩至毫秒级，成为企业级Spring项目中构建实时交互系统的标准方案。

为什么选择Spring WebSocket？HTTP短轮询的致命痛点

很多开发者最初会选择HTTP短轮询实现实时交互：客户端每隔1秒发送一次请求，查询最新状态；或长轮询：客户端发起请求后，服务器挂起连接直到有新消息才返回。但这两种方案存在三大致命痛点：

其一，资源浪费严重：短轮询的每个请求都携带完整HTTP头，其中有效数据占比不足10%，1000个在线用户的短轮询请求会让服务器CPU占用率飙升至70%；其二，消息延迟高：短轮询的消息延迟受轮询间隔限制，最少为1秒；长轮询虽然延迟低，但服务器挂起大量连接会消耗过多内存，鳄鱼java社区测试显示，1000个长轮询连接会占用服务器500MB以上内存；其三，被动响应限制：HTTP协议是客户端主动发起请求，服务器无法主动给客户端推送消息，不适合需要实时告警、主动通知的场景。

而Spring WebSocket基于HTML5 WebSocket协议实现，通过一次TCP长连接实现双工通信，服务器可以主动给客户端推送消息，完美解决了这些痛点。据鳄鱼java社区的性能测试，WebSocket的消息延迟平均为20ms，仅为短轮询的2%；服务器CPU占用率仅为短轮询的20%。

Spring WebSocket基础入门：依赖配置与第一个推送示例

要快速上手Spring WebSocket，只需完成三步基础配置即可实现第一个推送示例：

1. 添加Maven依赖： Spring Boot提供了专门的WebSocket Starter，无需手动引入复杂的依赖：

 
<dependency> 
    <groupId>org.springframework.boot</groupId> 
    <artifactId>spring-boot-starter-websocket</artifactId> 
</dependency> 

2. 配置WebSocket连接端点： 创建配置类开启WebSocket支持，并注册连接端点：

 
import org.springframework.context.annotation.Configuration; 
import org.springframework.web.socket.config.annotation.EnableWebSocket; 
import org.springframework.web.socket.config.annotation.WebSocketConfigurer; 
import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry; 
@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {
@Override
public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
// 注册消息处理Handler，客户端连接地址为/ws/message
registry.addHandler(new MessageWebSocketHandler(), "/ws/message")
.setAllowedOrigins("*"); // 允许跨域，生产环境需指定具体域名
}
}

3. 实现消息处理Handler： 继承TextWebSocketHandler处理文本消息，重写handleTextMessage方法实现消息的接收与推送：

 
import org.springframework.web.socket.TextMessage; 
import org.springframework.web.socket.WebSocketSession; 
import org.springframework.web.socket.handler.TextWebSocketHandler; 
public class MessageWebSocketHandler extends TextWebSocketHandler {
@Override
protected void handleTextMessage(WebSocketSession session, TextMessage message) throws Exception {
// 收到客户端消息后，推送响应消息
String response = "服务器收到消息：" + message.getPayload();
session.sendMessage(new TextMessage(response));
}
}

4. 前端客户端连接测试： 使用原生WebSocket API连接服务器并发送消息：

 
let socket = new WebSocket('ws://localhost:8080/ws/message'); 
// 接收服务器消息 
socket.onmessage = function(event) { 
    console.log('收到服务器消息：', event.data); 
}; 
// 发送消息给服务器 
socket.onopen = function() { 
    socket.send('Hello Spring WebSocket!'); 
}; 

核心组件详解：WebSocketHandler、Session与STOMP协议

要实现复杂的实时交互场景，需要理解Spring WebSocket的核心组件与STOMP协议的价值：

1. WebSocketHandler：处理消息的核心类，负责接收客户端消息、发送服务器消息，常用子类有TextWebSocketHandler（文本消息）、BinaryWebSocketHandler（二进制消息）； 2. WebSocketSession：代表客户端与服务器的长连接会话，每个客户端对应一个Session，可通过Session获取客户端ID、发送消息、关闭连接； 3. STOMP协议：原生WebSocket仅定义了消息传输的底层格式，没有提供订阅、发布、目标地址等高级特性，而STOMP（Simple Text Oriented Messaging Protocol）是一个基于文本的消息协议，提供了类似MQ的订阅-发布模型，适合复杂的实时交互场景，这也是Spring Websocket实时消息推送实战中构建生产级系统的首选方案。

配置STOMP协议的核心代码：

 
import org.springframework.context.annotation.Configuration; 
import org.springframework.messaging.simp.config.MessageBrokerRegistry; 
import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker; 
import org.springframework.web.socket.config.annotation.StompEndpointRegistry; 
import org.springframework.web.socket.config.annotation.WebSocketMessageBrokerConfigurer; 
@Configuration
@EnableWebSocketMessageBroker
public class StompWebSocketConfig implements WebSocketMessageBrokerConfigurer {
@Override
public void configureMessageBroker(MessageBrokerRegistry config) {
// 启用内置消息代理，支持订阅/topic（广播）和/queue（私信）前缀的地址
config.enableSimpleBroker("/topic", "/queue");
// 客户端发送消息的前缀，比如客户端发送到/app/send的消息会被@MessageMapping注解的方法处理
config.setApplicationDestinationPrefixes("/app");
}
@Override 
public void registerStompEndpoints(StompEndpointRegistry registry) { 
    // 注册STOMP端点，启用SockJS兼容不支持WebSocket的浏览器 
    registry.addEndpoint("/ws/stomp").withSockJS(); 
} 

}

Spring WebSocket实时消息推送实战：实现广播与私信功能

基于STOMP协议，我们可以快速实现广播消息与用户私信功能，这是生产环境中最常见的实时交互场景：

1. 广播消息实现： 服务器接收客户端消息后，推送给所有订阅广播地址的客户端：

 
import org.springframework.messaging.handler.annotation.MessageMapping; 
import org.springframework.messaging.handler.annotation.SendTo; 
import org.springframework.stereotype.Controller; 
@Controller
public class MessageController {
// 客户端发送消息到/app/broadcast，服务器推送给订阅/topic/broadcast的所有客户端
@MessageMapping("/broadcast")
@SendTo("/topic/broadcast")
public String sendBroadcastMessage(String message) {
return "系统广播：" + message;
}
}

 
// 使用SockJS连接STOMP端点 
let stompClient = Stomp.over(new SockJS('/ws/stomp')); 
stompClient.connect({}, function(frame) { 
    // 订阅广播消息 
    stompClient.subscribe('/topic/broadcast', function(message) { 
        console.log('收到广播消息：', message.body); 
    }); 
    // 发送广播消息 
    stompClient.send("/app/broadcast", {}, "Hello 所有用户!"); 
}); 

2. 用户私信功能实现： 使用@SendToUser注解实现用户专属消息推送，鳄鱼java社区的实战案例显示，该方案已被应用于电商订单状态通知、社交平台私信等场景：

 
import org.springframework.messaging.handler.annotation.DestinationVariable; 
import org.springframework.messaging.handler.annotation.MessageMapping; 
import org.springframework.messaging.handler.annotation.SendToUser; 
import org.springframework.stereotype.