Spring GraphQL订阅返回异常：为何控制器无法返回数据？

核心可能原因 #

1. 订阅方法返回的Publisher未适配Spring GraphQL要求 #

Spring GraphQL订阅强制要求方法返回Reactor的Flux/Mono类型，而非原生Publisher接口实现。如果直接返回自定义Publisher或未被Spring WebFlux适配的实例，序列化时会暴露内部属性（比如Postman返回的upstreamPublisher），无法正确转化为可消费的订阅数据流。

2. WebSocket传输配置缺失或错误 #

GraphQL订阅依赖WebSocket协议，若项目未正确配置WebSocket支持：

• GraphiQL会因WebSocket连接失败抛出isTrusted类型错误（这是浏览器端WebSocket连接异常的封装）
• 非WebSocket客户端（如Postman直接用HTTP POST）无法触发订阅数据流，只能拿到原始Publisher的序列化元数据

3. Schema定义与控制器返回类型不匹配 #

• 订阅字段未放在type Subscription块中，导致GraphQL引擎无法识别为订阅操作
• Schema中定义的返回类型与控制器方法实际返回类型不兼容（比如Schema定义为String!，但方法返回Flux），会导致数据无法正确解析

4. 控制器数据流未正确发射数据 #

如果控制器返回的Flux/Mono是空流，或者没有触发数据发射逻辑（比如数据流未启动），则不会有任何数据返回，Postman只会显示Publisher的元信息。

排查与解决步骤 #

步骤1：修正控制器方法返回类型 #

确保订阅方法返回Flux<T>或Mono<T>，示例：

@Controller
public class GreetingController {
    @SubscriptionMapping("greeting")
    public Flux<String> greeting() {
        // 每秒发射一条问候消息
        return Flux.interval(Duration.ofSeconds(1))
                   .map(i -> "Hello, Subscription! " + i);
    }
}

步骤2：确认WebSocket配置正确 #

• 确保项目引入spring-boot-starter-graphql和spring-boot-starter-webflux依赖（WebSocket依赖WebFlux）
• Spring Boot 3.x+默认会自动配置WebSocket，无需额外代码；若为自定义配置，需保证GraphQlWebSocketHandler映射到正确路径（默认/graphql）

步骤3：验证Schema定义正确性 #

确保订阅字段在Subscription类型中，且返回类型与控制器一致：

type Query {
    hello: String
}

type Subscription {
    greeting: String!
}

步骤4：检查数据流发射状态 #

在控制器方法中添加日志，确认数据流是否正常发射：

return Flux.interval(Duration.ofSeconds(1))
           .doOnNext(i -> System.out.println("Emitting greeting: " + i))
           .map(i -> "Hello, Subscription! " + i);

若控制台无日志输出，说明数据流未被触发（Spring GraphQL会自动订阅，但若数据流本身存在逻辑问题则不会发射）。

步骤5：排查GraphiQL的WebSocket连接 #

打开浏览器开发者工具的Network标签，查看WebSocket连接是否成功建立（路径应为/graphql，协议为ws或wss）。若连接失败，检查：

• 是否配置了正确的CORS规则（若GraphiQL与服务端跨域）
• 服务器端口是否正常开放，有无防火墙拦截

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