Spring Boot GraphQL端点返回404未找到问题排查求助

核心原因：依赖版本不兼容 #

你使用的Spring Boot 3.0.2基于Jakarta EE规范，但graphql-spring-boot-starter 14.0.0版本仍依赖旧的Java EE（javax）API，导致自动配置类无法正常加载，GraphQL端点未被注册，从而出现404错误。

具体解决步骤 #

1. 调整依赖（二选一）

方案一：使用Spring官方GraphQL Starter（推荐，维护更活跃）

移除所有com.graphql-java-kickstart相关依赖，启用你注释掉的官方starter：

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

同时修改Resolver的写法，改用官方的注解方式：

@Controller
public class BankAccountController {

    @QueryMapping
    public BankAccount bankAccount(@Argument UUID id){
        return BankAccount.builder().id(id).currency(Currency.USD).name("XYZ").build();
    }
}

官方starter默认的GraphQL端点也是/graphql，并且会自动扫描src/main/resources/graphql下的schema文件。

方案二：升级kickstart依赖到兼容Spring Boot 3的版本

将kickstart相关依赖版本升级到15.0.0及以上（该版本开始支持Jakarta EE）：

<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphql-spring-boot-starter</artifactId>
    <version>15.0.0</version>
</dependency>
<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphql-java-tools</artifactId>
    <version>14.0.0</version> <!-- 对应15.x starter的兼容版本 -->
</dependency>

2. 检查Schema文件配置

确保你的schema文件后缀为.graphql或.graphqls，放置在src/main/resources/graphql目录下，kickstart和官方starter都会自动扫描该目录下的schema文件。

3. 确认Resolver被Spring扫描

你的BankAccountResolver标注了@Component，需确保该类所在的包在Spring Boot主类的@ComponentScan扫描范围内（默认主类所在包及其子包都会被扫描）。

4. 显式配置端点（可选）

在application.properties中添加配置，明确指定GraphQL端点路径：

# 官方starter配置
spring.graphql.path=/graphql

# kickstart配置
graphql.servlet.mapping=/graphql

额外检查 #

• 启动日志中是否有GraphQL相关的初始化日志，比如"GraphQLServlet initialized"或"GraphQL schema loaded"，如果没有说明配置未生效，需重新检查依赖和配置。
• 确保没有自定义的WebMvc配置拦截了/graphql端点。

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