Spring Boot GraphQL项目请求返回404错误排查求助

问题根源 #

你的项目同时引入了两套冲突的GraphQL集成方案：老的com.graphql-java生态依赖（graphql-spring-boot-starter、graphql-java-tools等）和Spring官方的spring-boot-starter-graphql，两者的自动配置、注解体系完全不兼容，导致端点无法正确注册。同时代码和配置也未匹配正确的集成方式。

分步解决 #

1. 清理pom.xml依赖 #

只保留Spring官方的GraphQL starter，删除所有com.graphql-java相关依赖，修改后的核心依赖如下：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <!-- 仅保留Spring官方GraphQL starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-graphql</artifactId>
    </dependency>
</dependencies>

2. 修改Query类适配官方注解 #

Spring官方GraphQL使用@QueryMapping定义查询，无需实现GraphQLQueryResolver接口：

package com.gql.graphql;

import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

@Controller
public class Query {
    @QueryMapping
    public String firstQuery() {
        return "first query";
    }
}

注意：用@Controller替代@Component，让Spring识别为GraphQL控制器。

3. 修正application.properties配置 #

官方starter的配置前缀为spring.graphql，调整配置如下：

server.port=8681
# GraphQL端点路径（默认就是/graphql，可省略）
spring.graphql.path=/graphql
# 可选：启用GraphiQL可视化调试界面，访问路径为/graphiql
spring.graphql.graphiql.enabled=true

4. 确保Schema文件位置正确 #

将query.graphqls放到src/main/resources/graphql目录下（官方starter默认扫描该目录下的所有.graphqls文件），文件内容保持不变：

type Query{
    firstQuery:String
}

5. Postman请求正确姿势 #

• 请求方法：POST
• 请求URL：http://localhost:8681/graphql
• Body选择GraphQL类型，输入查询语句：

  query {
      firstQuery
  }
  

  或选择raw->JSON格式，传入：

  {
      "query": "query { firstQuery }"
  }
  

验证 #

启动项目后，可访问http://localhost:8681/graphiql打开可视化界面，直接测试查询是否正常返回结果。

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