GraphQL APIs with Spring Boot · 课时

GraphQL 中的自定义错误处理

实现自定义异常处理，并根据 GraphQL 最佳实践格式化错误响应。

GraphQL 中的自定义错误处理 是 CoddyKit 上的免费 GraphQL APIs with Spring Boot 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 GraphQL APIs with Spring Boot 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 GraphQL APIs with Spring Boot 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Understanding GraphQL Errors

When something goes wrong in a GraphQL operation, the server typically returns an errors array in the response. This array contains objects describing what went wrong.

By default, these error messages can be generic or even expose sensitive internal details like stack traces, which isn't ideal for production APIs.

Spring GraphQL's Default Behavior

Out-of-the-box, Spring GraphQL often maps Java exceptions (like RuntimeException) thrown by your data fetchers into a standard DataFetchingException. While functional, this default behavior might not provide the specific, user-friendly details your clients need.

Why Customize Error Responses?

Customizing error handling offers significant benefits:

Improved UX: Provide clear, actionable messages for end-users.
Enhanced Security: Prevent exposure of sensitive internal information (e.g., database errors, full stack traces).
Client-Side Logic: Include custom error codes or details that frontend applications can use to react specifically to different error types.

Meet DataFetcherExceptionResolver

In Spring GraphQL, the primary way to customize error responses is by implementing the DataFetcherExceptionResolver interface. This powerful interface allows you to intercept any exception thrown by a data fetcher and transform it into a structured GraphQLError object.

Define Your Custom Error

First, let's create a simple custom exception. This helps categorize specific error scenarios in your application. For example, a ResourceNotFoundException:

public class ResourceNotFoundException extends RuntimeException {
  private final String resourceId;

  public ResourceNotFoundException(String message, String resourceId) {
    super(message);
    this.resourceId = resourceId;
  }

  public String getResourceId() {
    return resourceId;
  }
}

Building Your Custom Resolver

Now, we'll create a class that implements DataFetcherExceptionResolver. This class will inspect the thrown exception and build a custom GraphQLError, potentially adding specific details via extensions.

import graphql.GraphQLError;
import graphql.execution.DataFetcherExceptionHandler;
import graphql.execution.DataFetcherExceptionHandlerParameters;
import graphql.execution.DataFetcherExceptionHandlerResult;
import graphql.error.ErrorType;
import java.util.HashMap;
import java.util.Map;

public class CustomExceptionResolver implements DataFetcherExceptionHandler {
  @Override
  public DataFetcherExceptionHandlerResult onException(
      DataFetcherExceptionHandlerParameters handlerParameters) {
    Throwable exception = handlerParameters.getException();

    if (exception instanceof ResourceNotFoundException) {
      ResourceNotFoundException rnfEx = (ResourceNotFoundException) exception;
      Map<String, Object> extensions = new HashMap<>();
      extensions.put("errorCode", "NOT_FOUND");
      extensions.put("resourceId", rnfEx.getResourceId());

      GraphQLError error = GraphQLError.newError()
          .message(rnfEx.getMessage())
          .locations(handlerParameters.getSourceLocation())
          .path(handlerParameters.getPath())
          .extensions(extensions)
          .errorType(ErrorType.DataFetchingException)
          .build();

      return DataFetcherExceptionHandlerResult.newResult().error(error).build();
    }
    // Fallback for unhandled exceptions
    return DataFetcherExceptionHandlerResult.newResult()
        .error(GraphQLError.newError()
            .message("An unexpected error occurred.")
            .errorType(ErrorType.DataFetchingException)
            .build())
        .build();
  }
}

Activating Your Custom Resolver

To make Spring GraphQL use your CustomExceptionResolver, you need to register it as a Spring @Bean in your application's configuration. This tells Spring to include it in the GraphQL execution chain.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import graphql.execution.DataFetcherExceptionHandler;

@Configuration
public class GraphQLConfig {
  @Bean
  public DataFetcherExceptionHandler customDataFetcherExceptionHandler() {
    return new CustomExceptionResolver();
  }
}

See It in Action!

Let's run a simplified Spring Boot app. If you query for an item with an ID other than '1', our custom error resolver will catch the DemoResourceNotFoundException and format the error response with specific details in the extensions field.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import graphql.kickstart.tools.GraphQLQueryResolver;
import graphql.execution.DataFetcherExceptionHandler;
import graphql.execution.DataFetcherExceptionHandlerParameters;
import graphql.execution.DataFetcherExceptionHandlerResult;
import graphql.GraphQLError;
import graphql.error.ErrorType;
import java.util.HashMap;
import java.util.Map;

// Main Application Class
@SpringBootApplication
public class ErrorDemoApp {
  public static void main(String[] args) {
    SpringApplication.run(ErrorDemoApp.class, args);
  }

  @Bean
  public GraphQLQueryResolver queryResolver() {
    return new DemoQueryResolver();
  }

  @Bean
  public DataFetcherExceptionHandler customDataFetcherExceptionHandler() {
    return new CustomErrorResolver();
  }

  // Custom Exception
  static class DemoResourceNotFoundException extends RuntimeException {
    private final String resourceId;
    public DemoResourceNotFoundException(String msg, String id) {
      super(msg); this.resourceId = id;
    }
    public String getResourceId() { return resourceId; }
  }

  // Data Fetcher
  @Component
  static class DemoQueryResolver implements GraphQLQueryResolver {
    public String getItem(String id) {
      if ("1".equals(id)) {
        return "Item Found: " + id;
      }
      throw new DemoResourceNotFoundException("Item not found", id);
    }
  }

  // Custom Error Resolver
  @Component
  static class CustomErrorResolver implements DataFetcherExceptionHandler {
    @Override
    public DataFetcherExceptionHandlerResult onException(
        DataFetcherExceptionHandlerParameters params) {
      Throwable ex = params.getException();
      if (ex instanceof DemoResourceNotFoundException) {
        DemoResourceNotFoundException rnfEx = (DemoResourceNotFoundException) ex;
        Map<String, Object> ext = new HashMap<>();
        ext.put("code", "ITEM_NOT_FOUND");
        ext.put("itemId", rnfEx.getResourceId());
        GraphQLError error = GraphQLError.newError()
            .message(rnfEx.getMessage())
            .locations(params.getSourceLocation())
            .extensions(ext)
            .errorType(ErrorType.DataFetchingException)
            .build();
        return DataFetcherExceptionHandlerResult.newResult().error(error).build();
      }
      return DataFetcherExceptionHandlerResult.newResult()
          .error(GraphQLError.newError()
              .message("Unexpected error")
              .errorType(ErrorType.DataFetchingException)
              .build())
          .build();
    }
  }
}

Error Extensions for Context

The extensions map within a GraphQLError is a powerful feature. It allows you to include custom, machine-readable data (like errorCode, resourceId, or validation errors) that clients can use for advanced error handling logic, beyond just the human-readable message.

Best Practices for Errors

To ensure robust error handling in your GraphQL API:

Be Specific: Use distinct custom exceptions for different error types.
Hide Internals: Never expose raw stack traces or database errors in production environments.
Consistent Format: Ensure your custom errors always follow a predictable structure.
Client-Friendly: Provide clear messages and actionable codes for frontend logic.

Quick Check: Error Handling

Which interface is primarily used in Spring GraphQL to customize how Java exceptions are transformed into GraphQLError objects?

Recap: Custom Error Handling

We learned how to move beyond default GraphQL error messages by implementing custom exception handling in Spring Boot. You can create custom exceptions, use the DataFetcherExceptionResolver to catch them, and format precise GraphQLError objects with useful extensions. This improves API security, user experience, and client-side error management.

常见问题解答

「GraphQL 中的自定义错误处理」课时是免费的吗？

是的 — 「GraphQL 中的自定义错误处理」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 GraphQL APIs with Spring Boot 课程的其余内容，请升级到 CoddyKit PRO。 GraphQL APIs with Spring Boot 课程共包含 4 节课。

「GraphQL 中的自定义错误处理」这节课中我会学到什么？

实现自定义异常处理，并根据 GraphQL 最佳实践格式化错误响应。你通过在浏览器中直接运行的动手代码来练习 GraphQL APIs with Spring Boot，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 GraphQL APIs with Spring Boot 需要有经验吗？

无需任何先前经验。CoddyKit 上的 GraphQL APIs with Spring Boot 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「GraphQL 中的自定义错误处理」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 GraphQL APIs with Spring Boot 课中编写并运行代码吗？

能。每节 GraphQL APIs with Spring Boot 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 GraphQL APIs with Spring Boot