SpringBoot+WebFlux+GraphQL返回Flux报错及后续问题排查

核心问题是GraphQL Schema定义与Resolver返回类型不匹配：

• Schema中getPages: Page声明返回单个Page对象，但你的Resolver返回的是Flux<Page>（多个Page对象的响应式流），GraphQL无法将代表多元素流的Flux解析为单个Page实例，因此抛出类型不匹配错误。

1. 修正GraphQL Schema定义 #

将getPages的返回类型改为列表类型[Page]，对应响应式流中的多元素：

type Page {
    id: Int!
    host: String
}

type Query {
    getPages: [Page]  # 改为列表类型匹配多元素流
}

2. 调整Resolver返回类型（语义更清晰） #

直接返回Flux<Page>替代Publisher<Page>，Spring GraphQL对Reactor类型有原生支持，语义明确：

@Component
public class PageQuery implements GraphQLQueryResolver {
    private final PageService pageService;

    // 构造注入替代@Autowired（符合Spring最佳实践）
    public PageQuery(PageService pageService) {
        this.pageService = pageService;
    }

    public Flux<Page> getPages() {
        return pageService.getPages();
    }
}

3. 切换到官方支持的响应式GraphQL依赖 #

放弃com.graphql-java或org.springframework.experimental的依赖，改用Spring官方的spring-boot-starter-graphql（兼容Spring Boot 2.6.3版本），它原生支持Mono/Flux作为Resolver返回值：

<!-- Maven依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-graphql</artifactId>
    <version>2.6.14</version> <!-- 匹配Spring Boot 2.6.3的兼容版本 -->
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-mongodb-reactive</artifactId>
</dependency>

4. 分页需求补充（若需返回Spring Data分页结果） #

如果实际需求是返回分页结构（而非多个Page实体），需要在Schema中定义分页专用类型：

type Page {
    id: Int!
    host: String
}

type PageInfo {
    totalElements: Int!
    totalPages: Int!
    size: Int!
    number: Int!
}

type PageResult {
    content: [Page]!
    pageInfo: PageInfo!
}

type Query {
    getPages(page: Int, size: Int): PageResult
}

Resolver返回Mono<PageResult>，将Spring Data的Page<Page>转换为自定义分页对象：

public Mono<PageResult> getPages(@Argument int page, @Argument int size) {
    return pageService.getPageablePages(page, size)
            .map(dataPage -> new PageResult(
                    dataPage.getContent(),
                    new PageInfo(
                            dataPage.getTotalElements(),
                            dataPage.getTotalPages(),
                            dataPage.getSize(),
                            dataPage.getNumber()
                    )
            ));
}

1. 启动应用后，访问默认GraphQL Playground路径/graphiql
2. 执行查询：

query {
    getPages {
        id
        host
    }
}

即可正确返回包含单个Page对象的列表。

内容的提问来源于stack exchange，提问作者k-wasilewski