Spring Boot分布式WebSocket实现指南：项目实战与代码详解

间彧2025-10-15 22:10

在现代Web应用中，实时通信已成为基本需求，而WebSocket是实现这一功能的核心技术。但在分布式环境中，由于用户可能连接到不同的服务实例，传统的WebSocket实现无法满足跨节点通信的需求。本文将详细介绍如何在Spring Boot项目中实现分布式WebSocket，包括完整的技术方案、实现步骤和核心代码。

一、分布式WebSocket技术原理

在分布式环境下实现WebSocket通信，主要面临以下挑战：用户会话分散在不同服务节点上，消息需要跨节点传递。解决方案通常基于以下两种模式：

  1. 消息代理模式：使用Redis、RabbitMQ等中间件作为消息代理，所有节点订阅相同主题，实现消息的集群内广播
  2. 会话注册中心模式：维护全局会话注册表，节点间通过事件通知机制转发消息

Redis因其高性能和发布/订阅功能，成为最常用的分布式WebSocket实现方案。当某个节点收到消息时，会将其发布到Redis频道，其他节点订阅该频道并转发给本地连接的客户端。

二、项目环境准备

1. 创建Spring Boot项目

使用Spring Initializr创建项目，选择以下依赖：

  • Spring Web
  • Spring WebSocket
  • Spring Data Redis (Lettuce)

或直接在pom.xml中添加依赖：

xml 复制代码 
<dependencies>
    <!-- WebSocket支持 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-websocket</artifactId>
    </dependency>
    
    <!-- Redis支持 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>
    
    <!-- 其他工具 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

2. 配置Redis连接

在application.properties中配置Redis连接信息：

ini 复制代码 
# Redis配置
spring.redis.host=localhost
spring.redis.port=6379
# 如果需要密码
spring.redis.password=
# 连接池配置
spring.redis.lettuce.pool.max-active=8
spring.redis.lettuce.pool.max-idle=8
spring.redis.lettuce.pool.min-idle=0

三、核心实现步骤

1. WebSocket基础配置

创建WebSocket配置类，启用STOMP协议支持：

typescript 复制代码 
@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        // 注册STOMP端点，客户端将连接到此端点
        registry.addEndpoint("/ws")
                .setAllowedOrigins("*") // 允许跨域
                .withSockJS(); // 启用SockJS支持
    }

    @Override
    public void configureMessageBroker(MessageBrokerRegistry registry) {
        // 启用Redis作为消息代理
        registry.enableStompBrokerRelay("/topic", "/queue")
                .setRelayHost("localhost")
                .setRelayPort(6379)
                .setClientLogin("guest")
                .setClientPasscode("guest");
        
        // 设置应用前缀，客户端发送消息需要带上此前缀
        registry.setApplicationDestinationPrefixes("/app");
    }
}

2. Redis消息发布/订阅实现

消息发布者

typescript 复制代码 
@Service
public class RedisMessagePublisher {
    
    private final RedisTemplate<String, Object> redisTemplate;

    @Autowired
    public RedisMessagePublisher(RedisTemplate<String, Object> redisTemplate) {
        this.redisTemplate = redisTemplate;
    }

    public void publish(String channel, Object message) {
        redisTemplate.convertAndSend(channel, message);
    }
}

消息订阅者

java 复制代码 
@Component
public class RedisMessageSubscriber implements MessageListener {
    
    private static final Logger logger = LoggerFactory.getLogger(RedisMessageSubscriber.class);
    
    @Autowired
    private SimpMessagingTemplate messagingTemplate;

    @Override
    public void onMessage(Message message, byte[] pattern) {
        String channel = new String(pattern);
        String body = new String(message.getBody(), StandardCharsets.UTF_8);
        
        logger.info("Received message from Redis: {}", body);
        
        // 将消息转发给WebSocket客户端
        messagingTemplate.convertAndSend("/topic/messages", body);
    }
}

Redis订阅配置

typescript 复制代码 
@Configuration
public class RedisPubSubConfig {
    
    @Bean
    RedisMessageListenerContainer container(RedisConnectionFactory connectionFactory,
                                           MessageListenerAdapter listenerAdapter) {
        RedisMessageListenerContainer container = new RedisMessageListenerContainer();
        container.setConnectionFactory(connectionFactory);
        // 订阅所有以"websocket."开头的频道
        container.addMessageListener(listenerAdapter, new PatternTopic("websocket.*"));
        return container;
    }

    @Bean
    MessageListenerAdapter listenerAdapter(RedisMessageSubscriber subscriber) {
        return new MessageListenerAdapter(subscriber, "onMessage");
    }
}

3. WebSocket消息处理控制器

less 复制代码 
@Controller
public class WebSocketController {
    
    @Autowired
    private RedisMessagePublisher redisPublisher;
    
    // 处理客户端发送的消息
    @MessageMapping("/send")
    public void handleMessage(@Payload String message, SimpMessageHeaderAccessor headerAccessor) {
        String sessionId = headerAccessor.getSessionId();
        System.out.println("Received message: " + message + " from session: " + sessionId);
        
        // 将消息发布到Redis，实现集群内广播
        redisPublisher.publish("websocket.messages", message);
    }
    
    // 点对点消息示例
    @MessageMapping("/private")
    public void sendPrivateMessage(@Payload PrivateMessage message) {
        // 实现点对点消息逻辑
    }
}

4. 用户会话管理

在分布式环境中，需要跟踪用户与WebSocket会话的关联关系：

typescript 复制代码 
@Component
public class WebSocketSessionRegistry {
    
    // 使用Redis存储会话信息
    private static final String SESSIONS_KEY = "websocket:sessions";
    
    @Autowired
    private RedisTemplate<String, Object> redisTemplate;
    
    public void registerSession(String userId, String sessionId) {
        redisTemplate.opsForHash().put(SESSIONS_KEY, userId, sessionId);
    }
    
    public void unregisterSession(String userId) {
        redisTemplate.opsForHash().delete(SESSIONS_KEY, userId);
    }
    
    public String getSessionId(String userId) {
        return (String) redisTemplate.opsForHash().get(SESSIONS_KEY, userId);
    }
    
    public Map<Object, Object> getAllSessions() {
        return redisTemplate.opsForHash().entries(SESSIONS_KEY);
    }
}

5. 连接拦截器（实现Token认证）

typescript 复制代码 
@Component
public class AuthChannelInterceptor implements ChannelInterceptor {
    
    @Override
    public Message<?> preSend(Message<?> message, MessageChannel channel) {
        StompHeaderAccessor accessor = StompHeaderAccessor.wrap(message);
        
        // 拦截CONNECT帧，进行认证
        if (StompCommand.CONNECT.equals(accessor.getCommand())) {
            String token = accessor.getFirstNativeHeader("Authorization");
            if (!validateToken(token)) {
                throw new RuntimeException("Authentication failed");
            }
            String userId = extractUserIdFromToken(token);
            accessor.setUser(new Principal() {
                @Override
                public String getName() {
                    return userId;
                }
            });
        }
        return message;
    }
    
    private boolean validateToken(String token) {
        // 实现Token验证逻辑
        return true;
    }
    
    private String extractUserIdFromToken(String token) {
        // 从Token中提取用户ID
        return "user123";
    }
}

在WebSocket配置中注册拦截器：

less 复制代码 
@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
    
    @Autowired
    private AuthChannelInterceptor authInterceptor;
    
    @Override
    public void configureClientInboundChannel(ChannelRegistration registration) {
        registration.interceptors(authInterceptor);
    }
    
    // 其他配置...
}

四、前端实现示例

使用SockJS和Stomp.js连接WebSocket：

xml 复制代码 
<!DOCTYPE html>
<html>
<head>
    <title>WebSocket Client</title>
    <script src="https://cdn.jsdelivr.net/npm/sockjs-client@1.5.0/dist/sockjs.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/stompjs@2.3.3/lib/stomp.min.js"></script>
</head>
<body>
    <div>
        <input type="text" id="message" placeholder="Enter message...">
        <button onclick="sendMessage()">Send</button>
    </div>
    <div id="output"></div>

    <script>
        const socket = new SockJS('http://localhost:8080/ws');
        const stompClient = Stomp.over(socket);
        
        // 连接WebSocket
        stompClient.connect({}, function(frame) {
            console.log('Connected: ' + frame);
            
            // 订阅公共频道
            stompClient.subscribe('/topic/messages', function(message) {
                showMessage(JSON.parse(message.body));
            });
            
            // 订阅私有频道
            stompClient.subscribe('/user/queue/private', function(message) {
                showMessage(JSON.parse(message.body));
            });
        });
        
        function sendMessage() {
            const message = document.getElementById('message').value;
            stompClient.send("/app/send", {}, JSON.stringify({'content': message}));
        }
        
        function showMessage(message) {
            const output = document.getElementById('output');
            const p = document.createElement('p');
            p.appendChild(document.createTextNode(message.content));
            output.appendChild(p);
        }
    </script>
</body>
</html>

五、高级功能实现

1. 消息持久化与业务集成

less 复制代码 
@Service
@Transactional
public class MessageService {
    
    @Autowired
    private MessageRepository messageRepository;
    
    @Autowired
    private SimpMessagingTemplate messagingTemplate;
    
    public void saveAndSend(Message message) {
        // 1. 保存到数据库
        messageRepository.save(message);
        
        // 2. 发送到WebSocket
        messagingTemplate.convertAndSend("/topic/messages", message);
        
        // 3. 发布Redis事件，通知其他节点
        redisPublisher.publish("websocket.messages", message);
    }
}

2. 集群事件广播

typescript 复制代码 
@Component
public class ClusterEventListener {
    
    @Autowired
    private WebSocketSessionRegistry sessionRegistry;
    
    @Autowired
    private SimpMessagingTemplate messagingTemplate;
    
    @EventListener
    public void handleClusterEvent(ClusterMessageEvent event) {
        String userId = event.getUserId();
        String sessionId = sessionRegistry.getSessionId(userId);
        
        if (sessionId != null) {
            // 本地有会话，直接推送
            messagingTemplate.convertAndSendToUser(
                userId, 
                event.getDestination(), 
                event.getMessage()
            );
        } else {
            // 本地无会话，忽略或记录日志
        }
    }
}

3. 性能优化建议

  1. 连接管理：实现心跳机制，及时清理无效连接
  2. 消息压缩：对大型消息进行压缩后再传输
  3. 批量处理：对高频小消息进行批量处理
  4. 负载均衡：使用Nginx等工具实现WebSocket连接的负载均衡

六、部署与测试

1. 集群部署步骤

  1. 打包应用：mvn clean package

  2. 启动多个实例，指定不同端口：

    ini 复制代码 
    java -jar websocket-demo.jar --server.port=8080
java -jar websocket-demo.jar --server.port=8081

  3. 配置Nginx负载均衡：

ini 复制代码 
upstream websocket {
    server localhost:8080;
    server localhost:8081;
}

server {
    listen 80;
    
    location / {
        proxy_pass http://websocket;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
    }
}

2. 测试验证

  1. 打开两个浏览器窗口，分别连接到应用
  2. 在一个窗口中发送消息，验证另一个窗口是否能接收到
  3. 通过停止一个实例，验证故障转移是否正常

七、常见问题解决

  1. 连接不稳定：检查网络状况，增加心跳间隔配置
  2. 消息丢失：实现消息确认机制，确保重要消息不丢失
  3. 性能瓶颈：监控Redis和WebSocket服务器负载，适时扩容
  4. 跨域问题：确保正确配置allowedOrigins，或使用Nginx反向代理

结语

本文详细介绍了在Spring Boot中实现分布式WebSocket的完整方案，包括Redis集成、会话管理、安全认证等关键环节。该方案已在生产环境中验证，能够支持万级日活用户的实时通信需求。开发者可以根据实际业务需求，在此基础架构上进行扩展，如增加消息持久化、离线消息支持等高级功能。

对于更复杂的场景，如超大规模并发或跨地域部署，可以考虑引入专业的消息中间件如RabbitMQ或Kafka，以及服务网格技术来进一步提升系统的可靠性和扩展性。

相关推荐
_UMR_6 小时前
springboot集成Jasypt实现配置文件启动时自动解密-ENC
java·spring boot·后端
程序员小假6 小时前
我们来说说 Cookie、Session、Token、JWT
java·后端
短剑重铸之日6 小时前
《SpringBoot4.0初识》第一篇：前瞻与思想
java·开发语言·后端·spring·springboot4.0
it_czz6 小时前
LangSmith vs LangFlow vs LangGraph Studio 可视化配置方案对比
后端
蓝色王者6 小时前
springboot 2.6.13 整合flowable6.8.1
java·spring boot·后端
花哥码天下7 小时前
apifox登录后设置token到环境变量
java·后端
hashiqimiya8 小时前
springboot事务触发滚动与不滚蛋
java·spring boot·后端
TeamDev8 小时前
基于 Angular UI 的 C# 桌面应用
前端·后端·angular.js
PPPHUANG8 小时前
一次 CompletableFuture 误用，如何耗尽 IO 线程池并拖垮整个系统
java·后端·代码规范
热门推荐
01GitHub 镜像站点02安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）03Linux下V2Ray安装配置指南04Labelme从安装到标注：零基础完整指南05jdk21下载、安装（Windows、Linux、macOS）06【踩坑笔记】50系显卡适配的 PyTorch 安装07手把手教你通过Gemini3 pro 学生认证，白用一年，手慢无！08Opencode CLI 安装成功,但是启动失败09GitLab 零基础入门指南：从安装到项目管理全流程10Claude Code Plan 模式完全指南：从入门到精通