Spring 整合 WebSocket 實現消息推送完整教程

WebSocket 協議基礎

WebSocket 提供全雙工長連接，解決 HTTP 輪詢高延遲、高開銷問題。握手階段升級 HTTP 協議（Upgrade: websocket），後續雙向幀傳輸，無需重複 Header。

Spring 整合方案對比

本文採用 Spring Boot + Spring WebSocket + STOMP + SockJS 方案。

依賴配置

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-websocket</artifactId>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>webjars-locator-core</artifactId>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>sockjs-client</artifactId>
        <version>1.6.1</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>stomp-websocket</artifactId>
        <version>2.3.4</version>
    </dependency>
</dependencies>

配置類

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void configureMessageBroker(MessageBrokerRegistry registry) {
        // 簡單內存代理：/topic 廣播、/queue 點對點
        registry.enableSimpleBroker("/topic", "/queue");
        // 應用目標前綴：客戶端發送 @MessageMapping 路徑
        registry.setApplicationDestinationPrefixes("/app");
        // 用戶專屬隊列前綴
        registry.setUserDestinationPrefix("/user");
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        // 原生 WebSocket 端點
        registry.addEndpoint("/ws").setAllowedOriginPatterns("*");
        // SockJS 降級端點（兼容舊瀏覽器、代理）
        registry.addEndpoint("/ws").setAllowedOriginPatterns("*").withSockJS();
    }

    @Override
    public void configureClientInboundChannel(ChannelRegistration registration) {
        registration.interceptors(new AuthChannelInterceptor()); // 鑒權攔截器
    }
}

消息控制器

消息模型

public class ChatMessage {
    private String content;
    private String sender;
    private MessageType type; // CHAT, JOIN, LEAVE
    private Instant timestamp;
    // getter/setter
}

public class PrivateMessage {
    private String toUser;
    private String content;
    // getter/setter
}

public enum MessageType { CHAT, JOIN, LEAVE }

鑒權攔截器

public class AuthChannelInterceptor implements ChannelInterceptor {
    @Override
    public Message preSend(Message message, MessageChannel channel) {
        StompHeaderAccessor accessor = StompHeaderAccessor.wrap(message);
        if (StompCommand.CONNECT.equals(accessor.getCommand())) {
            // 從 Header 獲取 Token
            String token = accessor.getFirstNativeHeader("Authorization");
            if (token != null && token.startsWith("Bearer ")) {
                token = token.substring(7);
                // 驗證 Token 並設置 Principal
                UserDetails user = tokenService.validate(token);
                if (user != null) {
                    accessor.setUser(new StompPrincipal(user.getUsername()));
                } else {
                    throw new InvalidTokenException("Token 無效");
                }
            } else {
                throw new MissingTokenException("缺少 Authorization Header");
            }
        }
        return message;
    }
}

前端接入 (JavaScript)

<script src="/webjars/sockjs-client/1.6.1/sockjs.min.js"></script>
<script src="/webjars/stomp-websocket/2.3.4/stomp.min.js"></script>

生產環境擴展

1. 外部消息代理：替換 enableSimpleBroker 為 enableStompBrokerRelay("/topic", "/queue") 連接 RabbitMQ/ActiveMQ/Kafka，支持集群水平擴展。
2. 心跳機制：配置 setHeartbeatValue(new long[]{10000, 10000}) 客戶端/服務端心跳間隔。
3. 消息持久化：配合 Redis/Kafka 存儲離線消息，用戶上線推送。
4. 分布式 Session：Spring Session + Redis 共享 WebSocket 會話。
5. 安全加固：WSS (WebSocket over TLS)、CSRF 保護、速率限制。

常見問題排查

總結

Spring WebSocket + STOMP 提供開箱即用的消息推送能力：@MessageMapping 處理業務、SimpMessagingTemplate 主動推送、@SendTo 廣播、convertAndSendToUser 私聊。配合 SockJS 兼容性、外部 Broker 集群化、鑒權攔截器，可構建企業級實時通訊系統。