4. 请求执行

ExecutionGraphQlService是调用 GraphQL Java 执行的主要 Spring 抽象 请求。基础传输（如 Server Transports）委托给ExecutionGraphQlService处理请求。spring-doc.cadn.net.cn

主要实现DefaultExecutionGraphQlService配置了GraphQlSource要访问graphql.GraphQL实例。spring-doc.cadn.net.cn

4.1.GraphQLSource

GraphQlSource是 Spring 的核心抽象，用于访问graphql.GraphQL实例。它提供了一个构建器 API，用于 初始化 GraphQL Java 并构建一个GraphQlSource.spring-doc.cadn.net.cn

默认的GraphQlSourcebuilder，可通过以下方式访问GraphQlSource.schemaResourceBuilder()，启用对反应性的DataFetcher、Context Propagation 和 Exception Resolution。spring-doc.cadn.net.cn

Spring Boot Starters初始化一个GraphQlSource实例通过默认的GraphQlSource.Builder并且还支持 以下内容：spring-doc.cadn.net.cn

对于进一步的自定义，您可以声明自己的GraphQlSourceBuilderCustomizer豆; 例如，为了配置您自己的ExecutionIdProvider:spring-doc.cadn.net.cn

@Configuration(proxyBeanMethods = false)
class GraphQlConfig {

    @Bean
    public GraphQlSourceBuilderCustomizer sourceBuilderCustomizer() {
        return (builder) ->
                builder.configureGraphQl(graphQlBuilder ->
                        graphQlBuilder.executionIdProvider(new CustomExecutionIdProvider()));
    }
}

4.1.1. Schema 资源

GraphQlSource.Builder可以配置一个或多个Resource实例为 解析并合并在一起。这意味着 schema 文件几乎可以从任何 位置。spring-doc.cadn.net.cn

默认情况下， Spring Boot Starters会查找带有扩展名的 schema 文件 位置下的 “.graphqls” 或 “.gqls”classpath:graphql/**，这通常是src/main/resources/graphql.您还可以使用文件系统位置或任何位置 由 Spring 提供支持Resource层次结构，包括自定义实现 从远程位置、存储或内存加载架构文件。spring-doc.cadn.net.cn

用classpath*:graphql/**/在多个 Classpath 中查找 schema 文件 位置，例如跨多个模块。

4.1.2. Schema 创建

默认情况下，GraphQlSource.Builder使用 GraphQL JavaGraphQLSchemaGenerator自 创建graphql.schema.GraphQLSchema.这适用于大多数应用程序，但如果 必要时，您可以通过构建器挂接到 schema 创建中：spring-doc.cadn.net.cn

GraphQlSource.Builder builder = ...

builder.schemaResources(..)
        .configureRuntimeWiring(..)
        .schemaFactory((typeDefinitionRegistry, runtimeWiring) -> {
            // create GraphQLSchema
        })

这样做的主要原因是通过联合库创建架构。spring-doc.cadn.net.cn

GraphQlSource 部分解释了如何使用 Spring Boot 进行配置。spring-doc.cadn.net.cn

4.1.3.RuntimeWiringConfigurer

您可以使用RuntimeWiringConfigurer要注册：spring-doc.cadn.net.cn

与 Web 框架不同，GraphQL 不使用 Jackson 注释来驱动 JSON 序列化/反序列化。 自定义数据类型及其序列化必须描述为 Scalars。

Spring Boot Starters检测 bean 类型的RuntimeWiringConfigurer和 将它们注册到GraphQlSource.Builder.这意味着在大多数情况下，您将拥有 类似于 this 的配置：spring-doc.cadn.net.cn

@Configuration
public class GraphQlConfig {

    @Bean
    public RuntimeWiringConfigurer runtimeWiringConfigurer(BookRepository repository) {

        GraphQLScalarType scalarType = ... ;
        SchemaDirectiveWiring directiveWiring = ... ;
        DataFetcher dataFetcher = QuerydslDataFetcher.builder(repository).single();

        return wiringBuilder -> wiringBuilder
                .scalar(scalarType)
                .directiveWiring(directiveWiring)
                .type("Query", builder -> builder.dataFetcher("book", dataFetcher));
    }
}

如果您需要添加WiringFactory，例如，进行注册时要考虑到 schema definitions 中，实现替代configure方法，该方法同时接受RuntimeWiring.Builder和一个输出List<WiringFactory>.这允许您添加任何 然后按顺序调用的工厂数。spring-doc.cadn.net.cn

4.1.4. 默认TypeResolver

GraphQlSource.Builder寄存 器ClassNameTypeResolver作为默认值TypeResolver用于尚未进行此类注册的 GraphQL 接口和联合 通过RuntimeWiringConfigurer.目的 一个TypeResolver在 GraphQL 中，Java 用于确定值的 GraphQL 对象类型 从DataFetcher对于 GraphQL Interface （图形QL 接口） 或 Union （联合） 字段。spring-doc.cadn.net.cn

ClassNameTypeResolver尝试将值的简单类名与 GraphQL 匹配 Object 类型，如果不成功，它还会导航其超类型，包括 基类和接口，寻找匹配项。ClassNameTypeResolver提供了一个 选项配置名称提取函数以及Class更改为 GraphQL 对象类型 名称映射应该有助于涵盖更多极端情况：spring-doc.cadn.net.cn

GraphQlSource.Builder builder = ...
ClassNameTypeResolver classNameTypeResolver = new ClassNameTypeResolver();
classNameTypeResolver.setClassNameExtractor((klass) -> {
    // Implement Custom ClassName Extractor here
});
builder.defaultTypeResolver(classNameTypeResolver);

GraphQlSource 部分解释了如何使用 Spring Boot 进行配置。spring-doc.cadn.net.cn

4.1.5.作缓存

GraphQL Java 必须在执行作之前对其进行解析和验证。这可能会影响 性能显着。为避免需要重新分析和验证，应用程序可以 配置PreparsedDocumentProvider缓存和重用 Document 实例。GraphQL Java 文档提供了有关以下内容的更多详细信息 查询缓存PreparsedDocumentProvider.spring-doc.cadn.net.cn

在 Spring GraphQL 中，你可以注册一个PreparsedDocumentProvider通过GraphQlSource.Builder#configureGraphQl: .spring-doc.cadn.net.cn

// Typically, accessed through Spring Boot's GraphQlSourceBuilderCustomizer
GraphQlSource.Builder builder = ...

// Create provider
PreparsedDocumentProvider provider = ...

builder.schemaResources(..)
        .configureRuntimeWiring(..)
        .configureGraphQl(graphQLBuilder -> graphQLBuilder.preparsedDocumentProvider(provider))

GraphQlSource 部分解释了如何使用 Spring Boot 进行配置。spring-doc.cadn.net.cn

4.1.6. 指令

GraphQL 语言支持“描述替代运行时执行和 GraphQL 文档中的类型验证行为”。指令类似于 Java，但在 GraphQL 文档中的类型、字段、片段和作上声明。spring-doc.cadn.net.cn

GraphQL Java 提供了SchemaDirectiveWiringContract 帮助应用程序检测 和 handle 指令。有关更多详细信息，请参阅 GraphQL Java 文档。spring-doc.cadn.net.cn

在 Spring GraphQL 中，你可以注册一个SchemaDirectiveWiring通过RuntimeWiringConfigurer.Spring Boot Starters检测到 这样的 bean，所以你可能会有这样的东西：spring-doc.cadn.net.cn

@Configuration
public class GraphQlConfig {

     @Bean
     public RuntimeWiringConfigurer runtimeWiringConfigurer() {
          return builder -> builder.directiveWiring(new MySchemaDirectiveWiring());
     }

}
有关指令支持的示例，请查看 Graphql Java 库的扩展验证。

4.2. 反应式DataFetcher

默认的GraphQlSourcebuilder 启用对DataFetcher返回Mono或Flux这会将它们调整为CompletableFuture哪里Flux值被聚合 并转换为 List，除非请求是 GraphQL 订阅请求， 在这种情况下，返回值仍然是 Reactive StreamsPublisher用于流媒体 GraphQL 响应。spring-doc.cadn.net.cn

反应式DataFetcher可以依赖对从 传输层，例如从 WebFlux 请求处理，请参阅 WebFlux 上下文。spring-doc.cadn.net.cn

4.3. 上下文传播

Spring for GraphQL 支持通过 GraphQL Java 透明地将上下文从服务器传输传播到DataFetcher和其他组件 调用。这包括ThreadLocal来自 Spring MVC 请求处理的上下文 thread 和 ReactorContext从 WebFlux 处理管道。spring-doc.cadn.net.cn

4.3.1. WebMvc

一个DataFetcher和 GraphQL Java 调用的其他组件可能并不总是在 与 Spring MVC 处理程序相同的线程，例如，如果WebGraphQlInterceptor或DataFetcher切换到 不同的线程。spring-doc.cadn.net.cn

Spring for GraphQL 支持传播ThreadLocal来自 Servlet 容器的值 thread 设置为线程 aDataFetcher和其他组件，以 执行时间。为此，应用程序需要创建一个ThreadLocalAccessor提取ThreadLocal感兴趣的值：spring-doc.cadn.net.cn

public class RequestAttributesAccessor implements ThreadLocalAccessor {

    private static final String KEY = RequestAttributesAccessor.class.getName();

    @Override
    public void extractValues(Map<String, Object> container) {
        container.put(KEY, RequestContextHolder.getRequestAttributes());
    }

    @Override
    public void restoreValues(Map<String, Object> values) {
        if (values.containsKey(KEY)) {
            RequestContextHolder.setRequestAttributes((RequestAttributes) values.get(KEY));
        }
    }

    @Override
    public void resetValues(Map<String, Object> values) {
        RequestContextHolder.resetRequestAttributes();
    }

}

一个ThreadLocalAccessor可以在 WebGraphHandler 构建器中注册。Boot Starters会检测此类型的 bean 并自动为 Spring MVC 应用程序，请参阅 Web 端点部分。spring-doc.cadn.net.cn

4.3.2. WebFlux 网络

一个反应性的DataFetcher可以依赖对 Reactor 上下文的访问，该 源自 WebFlux 请求处理链。这包括 Reactor 上下文 由 WebGraphQlInterceptor 组件添加。spring-doc.cadn.net.cn

4.4. 异常解决

GraphQL Java 应用程序可以注册DataFetcherExceptionHandler来决定如何 表示 GraphQL 响应的 “errors” 部分中数据层的异常。spring-doc.cadn.net.cn

Spring for GraphQL 具有内置的DataFetcherExceptionHandler配置以供使用 默认情况下GraphQLSource架构工人。它允许应用程序注册 一个或多个 SpringDataFetcherExceptionResolver按顺序调用的组件 直到解决Exception添加到（可能为空的）列表graphql.GraphQLError对象。spring-doc.cadn.net.cn

DataFetcherExceptionResolver是一个异步合约。对于大多数实现，它 就足以扩展DataFetcherExceptionResolverAdapter并覆盖 它的resolveToSingleError或resolveToMultipleErrors方法 同步解决异常。spring-doc.cadn.net.cn

一个GraphQLError可以通过以下方式分配给类别graphql.ErrorClassification. 在 Spring GraphQL 中，您还可以通过ErrorType它有以下常见 应用程序可用于对错误进行分类的分类：spring-doc.cadn.net.cn

如果异常仍未解决，则默认情况下，它被归类为INTERNAL_ERROR替换为包含类别名称和executionId从DataFetchingEnvironment.该消息故意不透明以避免泄漏 实现细节。应用程序可以使用DataFetcherExceptionResolver自定义 错误详细信息。spring-doc.cadn.net.cn

未解决的异常将记录在 ERROR 级别，并且executionId关联 发送到客户端的错误。已解决的异常记录在 DEBUG 级别。spring-doc.cadn.net.cn

4.4.1. 请求异常

GraphQL Java 引擎在解析请求时可能会遇到验证或其他错误 这反过来又会阻止请求执行。在这种情况下，响应包含 “data” 键替换为null以及一个或多个请求级 “错误” 是全局的，即 not 具有字段路径。spring-doc.cadn.net.cn

DataFetcherExceptionResolver无法处理此类全局错误，因为它们是引发的 在执行开始之前和任何DataFetcher被调用。应用程序可以使用 传输级拦截器来检查和转换ExecutionResult. 请参阅下面的示例WebGraphQlInterceptor.spring-doc.cadn.net.cn

4.4.2. 订阅例外

这Publisher，订阅请求可能会完成并显示错误信号，在这种情况下 底层传输（例如 WebSocket）发送带有列表的最终 “error” 类型消息 的 GraphQL 错误。spring-doc.cadn.net.cn

DataFetcherExceptionResolver无法解决订阅中的错误Publisher, 由于数据DataFetcher仅创建Publisher最初。之后， transport 订阅Publisher然后可能会以错误结束。spring-doc.cadn.net.cn

应用程序可以注册SubscriptionExceptionResolver为了解决 订阅中的异常Publisher为了解决 GraphQL 错误 以发送到客户端。spring-doc.cadn.net.cn

4.5. 批量加载

给定一个Book及其Author，我们可以创建一个DataFetcher一本书和另一本书 对于它的作者。这允许选择有作者或无作者的书籍，但这意味着书籍 和 authors 不会一起加载，这在查询多个 books 作为每本书的作者是单独加载的。这称为 N+1 选择 问题。spring-doc.cadn.net.cn

4.5.1.DataLoader

GraphQL Java 提供了一个DataLoader用于批量加载相关实体的机制。 您可以在 GraphQL Java 文档中找到完整的详细信息。下面是一个 工作原理摘要：spring-doc.cadn.net.cn

  1. 注册DataLoader在DataLoaderRegistry，它可以加载给定唯一键的实体。spring-doc.cadn.net.cn

  2. DataFetcher的 can accessDataLoader的 ID 值，并使用它们按 ID 加载实体。spring-doc.cadn.net.cn

  3. 一个DataLoader通过返回 future 来延迟加载，以便可以批量完成。spring-doc.cadn.net.cn

  4. DataLoader维护加载实体的每个请求缓存，该缓存可以进一步 提高效率。spring-doc.cadn.net.cn

4.5.2.BatchLoaderRegistry

GraphQL Java 中的完整批处理加载机制需要实现以下之一 几个BatchLoader接口，然后将它们包装并注册为DataLoaders ，名称位于DataLoaderRegistry.spring-doc.cadn.net.cn

Spring GraphQL 中的 API 略有不同。对于注册，只有一个 中央BatchLoaderRegistry公开工厂方法和构建器以创建和 注册任意数量的批量加载函数：spring-doc.cadn.net.cn

@Configuration
public class MyConfig {

    public MyConfig(BatchLoaderRegistry registry) {

        registry.forTypePair(Long.class, Author.class).registerMappedBatchLoader((authorIds, env) -> {
                // return Mono<Map<Long, Author>
        });

        // more registrations ...
    }

}

Spring Boot Starters声明了一个BatchLoaderRegistry你可以注入的 bean 您的配置，如上所示，或按顺序放入任何组件（如控制器） 注册批量加载函数。反过来，BatchLoaderRegistry被注入DefaultExecutionGraphQlService确保DataLoader每个请求的注册数。spring-doc.cadn.net.cn

默认情况下，DataLoadername 基于目标实体的类名。 这允许@SchemaMapping方法声明具有泛型类型的 DataLoader 参数，以及 无需指定名称。但是，可以通过BatchLoaderRegistrybuilder（如有必要）以及其他DataLoader选项。spring-doc.cadn.net.cn

在许多情况下，在加载相关实体时，您可以使用 @BatchMapping 控制器方法，这是一种快捷方式 for 并替换需要使用BatchLoaderRegistry和DataLoader径直。 sBatchLoaderRegistry还提供其他重要的好处。它支持访问 一样GraphQLContextfrom batch loading functions 和 from@BatchMapping方法 以及确保对它们的上下文传播。这就是预期应用的原因 以使用它。可以执行你自己的DataLoaderregistrations 直接注册，但 此类注册将放弃上述好处。spring-doc.cadn.net.cn

4.5.3. 测试 Batch Load

首先BatchLoaderRegistry在DataLoaderRegistry:spring-doc.cadn.net.cn

BatchLoaderRegistry batchLoaderRegistry = new DefaultBatchLoaderRegistry();
// perform registrations...

DataLoaderRegistry dataLoaderRegistry = DataLoaderRegistry.newRegistry().build();
batchLoaderRegistry.registerDataLoaders(dataLoaderRegistry, graphQLContext);

现在您可以访问和测试个人DataLoader如下所示：spring-doc.cadn.net.cn

DataLoader<Long, Book> loader = dataLoaderRegistry.getDataLoader(Book.class.getName());
loader.load(1L);
loader.loadMany(Arrays.asList(2L, 3L));
List<Book> books = loader.dispatchAndJoin(); // actual loading

assertThat(books).hasSize(3);
assertThat(books.get(0).getName()).isEqualTo("...");
// ...