使用Spring Boot GraphQL SPQR后GraphiQL端点消失问题排查

1. 检查GraphiQL依赖配置 #

spring-boot-graphql-spqr 本身不包含GraphiQL组件依赖，你之前使用的标准Spring GraphQL Starter自带该组件，切换到SPQR后需要手动添加GraphiQL相关依赖：

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

Gradle项目则添加：

implementation 'org.springframework.boot:spring-boot-starter-graphql'

注：无需移除SPQR依赖，两者可共存，既保留SPQR的自动Schema生成能力，又能启用GraphiQL。

2. 确认GraphiQL启用配置 #

在application.properties或application.yml中明确启用GraphiQL并指定路径：

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

检查配置项是否被注释或被其他配置覆盖。

3. 排查端点拦截规则 #

如果项目使用Spring Security或Actuator，需确保/graphiql端点未被拦截：

• Spring Security环境下，添加放行规则：

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth
        .requestMatchers("/graphql", "/graphiql", "/graphiql/**").permitAll()
        .anyRequest().authenticated()
    );
    return http.build();
}

• Actuator环境下，确认端点暴露配置：

management.endpoints.web.exposure.include=graphiql

4. 验证SPQR配置正确性 #

确保业务类已正确添加SPQR注解（如@GraphQLApi、@GraphQLQuery等），且Spring能扫描到这些类：

• 检查启动类的@ComponentScan是否覆盖了SPQR注解所在的包；
• 确认SPQR版本与Spring Boot版本兼容（例如Spring Boot 3.x需搭配SPQR 1.0+版本）。

5. 查看日志定位问题 #

开启DEBUG日志级别，查看Spring Boot自动配置过程，确认GraphiQL相关配置类是否正常加载：

logging.level.org.springframework.graphql=DEBUG
logging.level.io.leangen.graphql=DEBUG

通过日志排查是否存在配置类被跳过、依赖冲突或初始化失败的情况。

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