3. 请求执行

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

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

3.1.GraphQLSource

GraphQlSource是一个合约，用于公开graphql.GraphQLinstance 来使用该 包含用于构建该实例的构建器 API。默认构建器可通过GraphQlSource.schemaResourceBuilder().spring-doc.cadn.net.cn

Boot Starter 会创建此构建器的实例并进一步初始化它 要从可配置位置加载 Schema 文件， 公开要应用到的属性GraphQlSource.Builder，以检测RuntimeWiringConfigurerbeans、用于 GraphQL 指标的插桩 bean、 和DataFetcherExceptionResolver和SubscriptionExceptionResolverbean 来解决异常。对于进一步的自定义，您还可以 声明一个GraphQlSourceBuilderCustomizerbean，例如：spring-doc.cadn.net.cn

@Configuration(proxyBeanMethods = false)
class GraphQlConfig {

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

3.1.1. Schema 资源

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

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

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

3.1.2. Schema 创建

默认情况下，GraphQlSource.Builder使用 GraphQL JavaSchemaGenerator要创建graphql.schema.GraphQLSchema.这适用于典型用途，但如果您需要使用 不同的生成器，例如对于联合，您可以注册一个schemaFactory回调：spring-doc.cadn.net.cn

GraphQlSource.Builder builder = ...

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

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

有关 Apollo Federation 的示例，请参见 federation-jvm-spring-example。spring-doc.cadn.net.cn

3.1.3. 模式遍历

您可以注册一个graphql.schema.GraphQLTypeVisitor通过builder.schemaResources(..).typeVisitors(..)如果要在 它已创建，并且可能会将更改应用于GraphQLCodeRegistry.请记住， 但是，此类访客无法更改架构。如果需要更改架构，请参阅 架构转换。spring-doc.cadn.net.cn

3.1.4. Schema 转换

您可以注册一个graphql.schema.GraphQLTypeVisitor通过builder.schemaResources(..).typeVisitorsToTransformSchema(..)如果要遍历 并在创建架构后对其进行转换，然后对架构进行更改。注意事项 这通常比 Schema Traversal 更昂贵 首选遍历而不是转换，除非您需要进行架构更改。spring-doc.cadn.net.cn

3.1.5.RuntimeWiringConfigurer

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

GraphQL Java 服务器应用程序仅将 Jackson 用于与数据映射之间的序列化。 客户端输入被解析为 Map。服务器输出将根据字段选择集组装到地图中。 这意味着您不能依赖 Jackson 序列化/反序列化 Comments。 相反，您可以使用自定义标量类型。

Boot Starter 检测 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

3.1.6. 默认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

3.1.7.作缓存

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

3.1.8. 指令

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

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

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

@Configuration
public class GraphQlConfig {

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

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

3.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

3.3. 上下文传播

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

3.3.1. WebMvc

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

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

public class RequestAttributesAccessor implements ThreadLocalAccessor<RequestAttributes> {

    @Override
    public Object key() {
        return RequestAttributesAccessor.class.getName();
    }

    @Override
    public RequestAttributes getValue() {
        return RequestContextHolder.getRequestAttributes();
    }

    @Override
    public void setValue(RequestAttributes attributes) {
        RequestContextHolder.setRequestAttributes(attributes);
    }

    @Override
    public void reset() {
        RequestContextHolder.resetRequestAttributes();
    }

}

您可以注册一个ThreadLocalAccessor在启动时使用全局ContextRegistry实例，可通过io.micrometer.context.ContextRegistry#getInstance().您也可以注册它 自动通过java.util.ServiceLoader机制。spring-doc.cadn.net.cn

3.3.2. WebFlux 浏览器

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

3.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

3.4.1. 请求异常

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

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

3.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

3.5. 批量加载

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

3.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

3.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 ...
    }

}

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

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

配置默认DataLoaderOptions全局，以用作任何 registration，您可以覆盖 Boot 的BatchLoaderRegistrybean 并使用构造函数 为DefaultBatchLoaderRegistry接受Supplier<DataLoaderOptions>.spring-doc.cadn.net.cn

在许多情况下，在加载相关实体时，您可以使用 @BatchMapping 控制器方法，这是一种快捷方式 for 并替换需要使用BatchLoaderRegistry和DataLoader径直。spring-doc.cadn.net.cn

BatchLoaderRegistry还提供其他重要的好处。它支持访问 一样GraphQLContextfrom batch loading functions 和 from@BatchMapping方法 以及确保对它们的上下文传播。这就是预期应用的原因 以使用它。可以执行你自己的DataLoaderregistrations 直接注册，但 此类注册将放弃上述好处。spring-doc.cadn.net.cn

3.5.3. 测试批量加载

首先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("...");
// ...