Spring Boot应用中GraphiQL端点无法访问（404错误）求助

问题现象 #

访问http://localhost:8080/graphiql?path=/graphql或http://localhost:8080/graphiql均返回Whitelabel Error 404，已通过spring.graphql.graphiql.enabled=true启用GraphiQL。

排查与修复方案 #

1. 修正GraphQL Schema文件路径 #

Spring Boot GraphQL默认扫描src/main/resources/graphql/**/*.graphqls路径下的Schema文件，而你的Schema文件放在src/main/resources/schema/query.graphqls，不在默认扫描范围内，导致GraphQL无法识别查询定义，进而影响GraphiQL加载。

修复方式二选一：

• 直接将query.graphqls移动到src/main/resources/graphql目录下；
• 在application.properties中添加自定义Schema路径配置：

  spring.graphql.schema.locations=classpath:/schema/
  

2. 确认组件扫描范围 #

检查Spring Boot主启动类的包位置：如果主启动类不在com.practise.graphql根包下，会导致com.practise.graphql.query.Query这个GraphQLQueryResolver组件无法被Spring扫描到，GraphQL没有可用的查询处理器。

修复方式：

• 将主启动类移至com.practise.graphql包下；
• 或者在主启动类上添加@ComponentScan(basePackages = "com.practise.graphql")，强制指定扫描范围。

3. 排查端点冲突 #

你提到项目中有示例REST控制器，检查该控制器是否使用了@RequestMapping("/")这类全局路径映射，会覆盖GraphiQL的端点路径，导致404。

修复方式：

• 修改REST控制器的映射路径，例如改为@RequestMapping("/api")，避免与GraphiQL（/graphiql）、GraphQL核心端点（/graphql）冲突。

4. 验证依赖与构建 #

虽然pom.xml中的依赖配置看起来正常，但可以执行mvn clean install重新构建项目，确保所有依赖（尤其是spring-boot-starter-graphql）完整下载且无版本冲突。

5. 确认端点配置（可选） #

默认GraphQL核心端点为/graphql，如果没有自定义修改过，无需调整；若有修改需求，可在application.properties中明确配置：

spring.graphql.path=/graphql

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