Spring Boot GraphQL项目中/graphql端点POST请求返回404求助

问题描述 #

在Spring Boot应用中使用新版Spring for GraphQL时，向/graphql端点发送POST请求始终返回404状态码。

Gradle依赖 #

implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
implementation 'org.springframework.boot:spring-boot-starter-graphql'
implementation 'org.springframework.boot:spring-boot-starter-mail'
implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.springframework.boot:spring-boot-starter-validation'
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-websocket'
implementation 'org.flywaydb:flyway-core'
compileOnly 'org.projectlombok:lombok'
runtimeOnly 'org.postgresql:postgresql'
annotationProcessor 'org.projectlombok:lombok'

控制器代码（解析器） #

@Slf4j
@Controller
@RequiredArgsConstructor
public class StepController {
  private final StepService stepService;
  private final TokenService tokenService;

  @QueryMapping
  public ArrayList<Step> getSteps(String templateId) {
    return stepService.getSteps(templateId);
  }

  @MutationMapping
  public Step createStep(StepInput input, DataFetchingEnvironment env) {
    return stepService.createStep(input, tokenService.getUserId(env));
  }
}

Spring Security配置 #

@Configuration
public class SecurityConfiguration {

  @Bean
  public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.cors()
        .configurationSource(request -> {
          var cors = new CorsConfiguration();
          cors.setAllowedOrigins(List.of("http://localhost:4200", "electron://altair"));
          cors.setAllowedMethods(List.of("GET", "POST", "DELETE", "OPTIONS"));
          cors.setAllowedHeaders(List.of("*"));
          cors.setAllowCredentials(true);
          return cors;
        })
        .and()
        .csrf().disable()
        .authorizeRequests()
        .antMatchers(HttpMethod.POST, "/graphql").permitAll()
        .antMatchers(HttpMethod.GET, "/stomp/**").permitAll()
        .anyRequest().authenticated()
        .and()
        .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);
    return http.build();
  }
}

GraphQL Schema配置 #

原本Schema文件按文件夹结构放在resources/graphql目录下，切换新版前正常。更新后替换为单个schema.graphqls文件：

type Mutation {
  login(email: String!, password: String!): Login!
}

type Login {
  token: String
}

// unused, just to make the compiler happy
type Query {
  getLogin: Login
}

application.properties配置 #

spring.banner.location=classpath:logo.txt
spring.main.banner-mode=console
spring.output.ansi.enabled=ALWAYS
spring.main.allow-bean-definition-overriding=true

spring.mail.host=mail.blablabla
spring.mail.port=587
spring.mail.username=no-reply@blablabla
spring.mail.password=blablalba
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=false
spring.profiles.include=prod,dev

spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL95Dialect
spring.jpa.hibernate.ddl-auto=validate

spring.servlet.multipart.max-file-size=512KB

解决方案建议 #

• 版本兼容性检查：确保Spring Boot版本与spring-boot-starter-graphql版本匹配，比如Spring Boot 3.x对应Spring for GraphQL 1.2+，Spring Boot 2.x对应1.1.x版本。
• 确认端点自动配置：启动日志中搜索GraphQlHttpHandler或/graphql，查看是否有端点注册日志。Spring Boot 2.x需要手动添加@EnableGraphQl注解到配置类，3.x则无需额外配置。
• Schema文件验证：新版Spring for GraphQL默认扫描classpath:graphql/**/*.graphqls，原文件夹结构是支持的，无需改为单个文件。若使用单个文件，确保路径正确，或通过spring.graphql.schema.locations指定自定义路径。同时，Schema中的字段需与@QueryMapping/@MutationMapping的方法名严格匹配（如getSteps方法需要Schema中存在对应getSteps query字段），否则解析器无法绑定，端点可能因Schema不完整无法启动。
• 排查Security拦截：暂时注释Security配置，测试是否是安全规则导致的404。同时验证CORS配置，确保OPTIONS请求能正常通过，避免浏览器拦截后续POST请求。
• 检查Web配置冲突：确认是否有自定义DispatcherServlet或@WebMvcConfigurer修改了请求映射，导致/graphql端点被覆盖。
• 启用调试日志：添加logging.level.org.springframework.graphql=DEBUG到配置文件，查看GraphQL启动日志，排查Schema加载失败、解析器绑定失败等问题。

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