Spring Cloud Gateway路由WebSocket服务时出现类型转换异常

问题根源分析 #

出现ClassCastException的核心原因是：Spring Cloud Gateway基于Reactor Netty（WebFlux响应式栈），但路由配置导致SockJS的HTTP fallback请求被错误路由到了WebSocket（ws://）端点，网关尝试对HTTP请求执行WebSocket升级操作，从而引发Tomcat的ResponseFacade与Reactor Netty的HttpServerResponse类型转换冲突。

解决步骤 #

1. 修正网关路由配置 #

调整路由规则，精准区分纯WebSocket请求和SockJS的HTTP请求路径：

cloud:
  gateway:
    routes:
      # 处理纯WebSocket连接请求（仅匹配/ws根端点）
      - id: websocket
        uri: ws://localhost:53110
        predicates:
          - Path=/ws
        filters:
          - StripPrefix=0

      # 处理SockJS的HTTP fallback请求（匹配/ws下所有子路径，如/ws/info、/ws/xxxx）
      - id: websocket_sockjs_route
        uri: http://localhost:53110
        predicates:
          - Path=/ws/**
        filters:
          - StripPrefix=0

说明：SockJS客户端在WebSocket连接失败后，会自动发起GET /ws/info等HTTP请求，这类请求必须路由到http://端点，而非ws://端点。

2. 调整客户端连接逻辑 #

如果使用SockJS客户端，需通过HTTP地址发起连接，而非直接使用ws://协议：

// 正确的SockJS连接方式
const socket = new SockJS('http://localhost:53100/ws');
const stompClient = Stomp.over(socket);

SockJS会自动优先尝试WebSocket升级，失败后自动切换到HTTP轮询，避免手动连接ws://导致的重复重试冲突。

3. 验证后端服务栈适配性 #

确保后端WebSocket服务的Web栈与网关路由匹配：

• 若后端为Spring MVC（Servlet栈，默认Tomcat）：保持上述路由配置即可，无需额外修改。
• 若后端为Spring WebFlux（响应式栈）：可统一使用ws:///wss://处理请求，但仍需通过路径区分避免冲突。

4. 排查过滤器干扰 #

检查网关自定义过滤器或安全过滤器（如日志中的AuthorizationWebFilter），确保不对WebSocket请求执行不必要的HTTP处理逻辑，避免打断升级流程。

验证方法 #

1. 重启网关与后端服务。
2. 打开浏览器开发者工具Network标签：
   • 正常情况下，首次会发起GET /ws的WebSocket请求，返回101状态码；
   • 若WebSocket连接受环境限制失败，会自动发起GET /ws/info等HTTP请求，返回200状态码。
3. 查看应用日志，确认不再出现ClassCastException与500错误。

内容的提问来源于stack exchange，提问作者YazarBaby