Apollo Server 3搭配graphql-ws中间件订阅对接Java WebFlux异常问题求助

1. 服务端协议兼容配置修正 #

Spring GraphQL 默认未开启graphql-ws协议支持，仅兼容老旧的subscriptions-transport-ws协议，需手动在application配置文件中新增如下配置：

spring:
  graphql:
    websocket:
      path: /graphql
      graphql-ws:
        enabled: true

配置完成后，Spring WebFlux才会识别graphql-ws标准的graphql-transport-ws握手头，解析对应协议帧。

2. 中间件转发规则调整 #

基于Apollo Server 3开发的中间件转发订阅请求时，必须满足两个要求：

• 完整携带Sec-WebSocket-Protocol请求头，值固定为graphql-transport-ws，该头缺失会直接被Spring WebFlux拦截，导致连接成功但无后续响应
• 不得修改graphql-ws协议标准的帧结构，包括connection_init、subscribe、next、complete等帧的字段，Spring对帧格式校验严格，字段不符合规范会直接丢弃请求不输出明确错误。

3. 跨域与路径匹配校验 #

WebFlux的WebSocket跨域规则需要单独配置，不可复用普通HTTP接口的跨域配置，需在WebFlux的CorsConfiguration中放行中间件的请求源；同时确保中间件转发的WebSocket请求路径与Spring配置的spring.graphql.websocket.path完全一致，无额外前后缀。

4. 错误日志排查方法 #

若修改后仍有问题，可调整Spring日志级别输出详细错误信息：

logging:
  level:
    org.springframework.graphql: DEBUG
    org.springframework.web.reactive.socket: DEBUG

• 日志出现Invalid message type/No adapter for payload：协议未正确开启或帧格式不匹配
• 日志出现No subscription found：转发过程中订阅ID丢失，需检查中间件的帧透传逻辑

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