使用Spring Boot GraphQL Starter暴露GraphQLException异常信息

我之前在使用Spring Boot GraphQL Starter时也碰到过一模一样的问题——默认情况下所有异常都会被包装成模糊的"Internal Server Error(s) while executing query"，完全没法给前端传递具体的业务错误信息。不过咱们可以通过自定义异常解析器来搞定这个需求，具体步骤如下：

1. 定义自定义GraphQL异常类 #

首先创建一个继承自GraphQLException的自定义异常，用来标记我们想要暴露具体消息的业务异常：

import graphql.GraphQLException;

public class CustomGraphQLException extends GraphQLException {
    public CustomGraphQLException(String message) {
        super(message);
    }
}

2. 实现自定义GraphQLError #

这个类用来封装我们要返回给前端的错误信息，确保异常消息能被正确暴露：

import graphql.GraphQLError;
import graphql.language.SourceLocation;
import org.springframework.graphql.execution.ErrorType;
import java.util.List;
import java.util.Map;

public class CustomGraphQLError implements GraphQLError {
    private final String message;
    private final List<SourceLocation> locations;
    private final ErrorType errorType;

    public CustomGraphQLError(String message, List<SourceLocation> locations, ErrorType errorType) {
        this.message = message;
        this.locations = locations;
        this.errorType = errorType;
    }

    @Override
    public String getMessage() {
        return message;
    }

    @Override
    public List<SourceLocation> getLocations() {
        return locations;
    }

    @Override
    public ErrorType getErrorType() {
        return errorType;
    }

    // 可选：如果需要给前端返回额外的错误扩展字段，可以重写这个方法
    @Override
    public Map<String, Object> getExtensions() {
        return GraphQLError.super.getExtensions();
    }
}

3. 自定义异常解析器（核心步骤） #

创建一个DataFetcherExceptionResolver的实现类，用来拦截数据获取过程中的异常，只把我们自定义的异常消息暴露出去：

import graphql.GraphQLError;
import graphql.GraphQLException;
import graphql.schema.DataFetchingEnvironment;
import org.springframework.graphql.execution.DataFetcherExceptionResolver;
import org.springframework.graphql.execution.ErrorType;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;
import java.util.List;

@Component
public class CustomGraphQLErrorResolver implements DataFetcherExceptionResolver {

    @Override
    public Mono<List<GraphQLError>> resolveException(Throwable ex, DataFetchingEnvironment env) {
        // 只处理我们自定义的GraphQLException
        if (ex instanceof GraphQLException customException) {
            CustomGraphQLError graphQLError = new CustomGraphQLError(
                    customException.getMessage(),
                    env.getField().getSourceLocations(),
                    ErrorType.BAD_REQUEST // 根据业务场景选择合适的错误类型，比如INTERNAL_ERROR、NOT_FOUND等
            );
            return Mono.just(List.of(graphQLError));
        }

        // 其他系统异常还是用默认处理逻辑（返回模糊的内部错误）
        return DataFetcherExceptionResolver.super.resolveException(ex, env);
    }
}

4. 配置文件调整（可选） #

确保你的application.yml或application.properties里的GraphQL异常配置是开启的，生产环境建议关闭debug模式避免暴露敏感信息：

spring:
  graphql:
    server:
      exception-handling:
        enabled: true
        debug: false # 设为true会显示堆栈信息，生产环境务必关闭
    graphiql:
      enabled: true # 方便在GraphiQL里测试错误返回

5. 测试自定义异常 #

在你的数据获取方法（比如@QueryMapping或@MutationMapping标记的方法）里抛出自定义异常：

@QueryMapping
public Book getBookById(@Argument String id) {
    if (id == null || id.isBlank()) {
        throw new CustomGraphQLException("书籍ID不能为空");
    }
    // 正常业务逻辑...
}

此时前端收到的GraphQL响应里，errors数组的message字段就会显示"书籍ID不能为空"，而不是默认的模糊错误信息了。

补充说明 #

• 如果不需要自定义异常类，也可以在解析器里判断特定的RuntimeException类型，但推荐用自定义异常来区分业务错误和系统错误，避免把系统异常的敏感信息暴露给前端。
• 如果你使用的是Spring Boot GraphQL 3.x及以上版本，这个写法完全兼容，不需要额外调整。

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