Java 21 Spring Boot 3.2 MVC中graphql-ws WebSocket连接异常关闭排查

连接立即关闭（4400 Invalid message）的原因 #

当使用graphql-ws子协议时，该协议强制要求客户端在连接建立后必须立即发送connection_init类型的初始化消息。如果Postman在连接后未发送这条消息，服务器端的graphql-ws处理器会判定消息无效，直接返回4400错误并关闭连接。

你提到握手响应已返回graphql-ws子协议，说明握手阶段成功，但后续客户端未遵循协议的初始化要求，触发了服务器的断开逻辑。

消息无效的核心原因 #

1. 未遵循graphql-ws协议初始化流程：客户端未发送connection_init消息，服务器直接判定无效。
2. 移除Sec-WebSocket-Protocol头后，WebSocket使用默认子协议，无法解析GraphQL订阅的特定消息格式（如subscribe类型的消息结构），导致服务器内部处理失败，返回1011错误。

解决步骤 #

1. 客户端发送符合规范的初始化消息 #

在Postman连接WebSocket后，先发送以下初始化消息：

{
  "type": "connection_init",
  "payload": {}
}

服务器收到后会返回connection_ack响应，之后才能发送订阅请求。

2. 检查服务器端graphql-ws处理器配置 #

确保WebSocket处理器正确实现graphql-ws协议逻辑，配置类中明确注册子协议：

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {
    private final GraphQLWebSocketHandler graphQLWebSocketHandler;

    public WebSocketConfig(GraphQLWebSocketHandler graphQLWebSocketHandler) {
        this.graphQLWebSocketHandler = graphQLWebSocketHandler;
    }

    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(graphQLWebSocketHandler, "/ws")
                .setAllowedOrigins("*")
                .addSubProtocol("graphql-ws");
    }
}

3. 验证依赖配置 #

确保项目依赖包含支持graphql-ws的包（以Spring Boot 3.2为例）：

<!-- Spring GraphQL WebSocket支持 -->
<dependency>
    <groupId>org.springframework.graphql</groupId>
    <artifactId>spring-graphql-webflux</artifactId>
</dependency>

4. 发送格式正确的订阅消息 #

初始化完成后，订阅消息需符合graphql-ws规范：

{
  "id": "1",
  "type": "subscribe",
  "payload": {
    "query": "subscription { yourSubscriptionField }"
  }
}

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