Spring Boot集成GraphQL无法启动及404错误求助

核心问题分析 #

启动后无GraphQL相关日志、访问/graphiql异常、/graphql端点返回404，通常说明GraphQL自动配置未生效，或Web容器未正确启动。以下是针对性排查步骤：

1. 检查Web依赖是否缺失 #

Spring Boot GraphQL Starter依赖Web容器才能暴露HTTP端点，但单独引入spring-boot-starter-graphql不会自动包含Web Starter。你的pom.xml中未显示spring-boot-starter-web依赖，这是导致404的最可能原因。

解决方案：
在pom.xml中添加Web Starter依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2. 确认Schema文件存放路径是否正确 #

Spring Boot GraphQL默认扫描src/main/resources/graphql/**/*.graphqls路径下的Schema文件。如果你的query.graphqls和article.graphqls放在其他位置（比如根目录），需要手动指定路径。

检查与配置：

• 确保文件路径为src/main/resources/graphql/query.graphqls和src/main/resources/graphql/article.graphqls
• 若路径不同，在application.properties中配置自定义路径：

  spring.graphql.schema.locations=classpath:your-custom-path/
  

3. 开启调试日志验证自动配置状态 #

启动时无GraphQL日志，说明自动配置可能未触发。开启调试日志可查看初始化细节：

配置方法：
在application.properties中添加：

logging.level.org.springframework.graphql=DEBUG
logging.level.org.springframework.boot.autoconfigure.graphql=DEBUG

重启应用后，检查日志中是否包含：

• 加载Schema文件的记录（如Loaded GraphQL schema from locations）
• /graphql端点注册日志
• 查询/变更方法的映射日志

4. 修正Schema与Controller的参数不匹配问题 #

你的Schema中getAllByClient查询未定义参数，但Controller对应方法添加了@Argument String id，这会导致该查询映射失败（虽不是404直接原因，但会影响功能）。

解决方案：
更新query.graphqls中的getAllByClient定义，补充参数：

type Query {
    getById(id: String): Article,
    getAll: [Article],
    getAllByClient(id: String): [Article] # 补充id参数
}

5. 确认GraphiQL配置状态 #

Spring Boot GraphQL默认开启GraphiQL，可手动确认配置：
在application.properties中添加：

spring.graphql.graphiql.enabled=true
spring.graphql.graphiql.path=/graphiql

重启后访问http://localhost:8080/graphiql，若Web容器正常启动，即可看到GraphiQL界面。

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