自定义 SmallRye GraphQL 错误消息（Quarkus）_技术教程

本文档介绍了如何在 Quarkus 中使用 SmallRye GraphQL 时自定义错误消息。默认情况下，运行时异常可能不会显示自定义消息，并且可能需要显式配置才能显示所需的字段。本文将指导你如何配置 Quarkus 以显示自定义异常消息和扩展字段。

显示运行时异常消息

默认情况下，Quarkus SmallRye GraphQL 不会自动显示运行时异常的详细消息。你需要显式启用此功能。

要显示运行时异常消息，需要在 application.properties 文件中进行如下配置：

quarkus.smallrye-graphql.show-runtime-exception-message=true

将此配置添加到你的 application.properties 文件后，SmallRye GraphQL 将会在错误响应中包含运行时异常的 getMessage() 方法的返回值。

自定义错误扩展字段

除了自定义错误消息，你可能还需要在错误响应中包含额外的字段，例如错误代码或详细的错误信息列表。这可以通过定义异常类的 getExtensions() 方法来实现。

例如，假设你有一个自定义异常类 SomeException：

import graphql.ErrorClassification;
import graphql.GraphQLError;
import graphql.language.SourceLocation;

import java.util.Collections;
import java.util.List;
import java.util.Map;

public class SomeException extends RuntimeException implements GraphQLError {

    private final List someErrors;
    private final String errorMessage;

    public SomeException(String message, List someErrors) {
        this.errorMessage = message;
        this.someErrors = someErrors;
    }

    @Override
    public String getMessage() {
        return this.errorMessage;
    }

    @Override
    public ErrorClassification getErrorType() {
        return null;
    }

    @Override
    public Map getExtensions() {
        return Collections.singletonMap("someErrors", someErrors);
    }

    @Override
    public List getLocations() {
        return null;
    }
}

为了使 someErrors 字段出现在错误响应中，需要在 application.properties 中进行如下配置：

quarkus.smallrye-graphql.error-extension-fields=someErrors

通过 quarkus.smallrye-graphql.error-extension-fields 属性，你可以指定要包含在错误响应中的扩展字段列表。多个字段可以使用逗号分隔。

示例

假设你有一个 GraphQL 查询，当发生特定错误时，会抛出 SomeException 异常。

import jakarta.inject.Inject;
import org.eclipse.microprofile.graphql.GraphQLApi;
import org.eclipse.microprofile.graphql.Query;

import java.util.Arrays;
import java.util.List;

@GraphQLApi
public class MyGraphQLApi {

    @Inject
    MyService myService;

    @Query
    public String something() {
        return myService.doSomething();
    }
}

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class MyService {

    public String doSomething() {
        List errors = Arrays.asList("Error 1", "Error 2");
        throw new SomeException("Custom error message", errors);
    }
}

结合上述配置，当调用 something 查询时，如果 MyService.doSomething() 抛出 SomeException 异常，GraphQL 响应将包含以下内容：

{
  "errors": [
    {
      "message": "Custom error message",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "something"
      ],
      "extensions": {
        "someErrors": [
          "Error 1",
          "Error 2"
        ],
        "classification": "DataFetchingException"
      }
    }
  ],
  "data": null
}

注意，message 字段现在包含 SomeException 中定义的自定义消息，并且 extensions 字段包含 someErrors 列表。

注意事项

确保你的异常类实现了 GraphQLError 接口。
quarkus.smallrye-graphql.show-runtime-exception-message 属性仅影响运行时异常。对于其他类型的错误，可能需要不同的处理方式。
quarkus.smallrye-graphql.error-extension-fields 属性允许你指定要包含的扩展字段。请谨慎选择要暴露的字段，避免泄露敏感信息。

总结

通过配置 quarkus.smallrye-graphql.show-runtime-exception-message 和 quarkus.smallrye-graphql.error-extension-fields 属性，你可以在 Quarkus 中使用 SmallRye GraphQL 时自定义错误消息和扩展字段，从而提供更清晰、更有用的错误信息给客户端。这有助于调试和问题排查，并提升用户体验。