Spring for GraphQL 提供了一个基于注释的编程模型，其中组件使用注释来声明具有灵活方法签名的处理程序方法，以 获取特定 GraphQL 字段的数据。例如：@Controllerspring-doc.cn

@Controller
public class GreetingController {

		@QueryMapping (1)
		public String hello() { (2)
			return "Hello, world!";
		}

}
1 将此方法绑定到查询，即 Query 类型下的字段。
2 如果未在注释上声明，则从方法名称确定查询。

Spring for GraphQL 用于将上述处理程序方法注册为名为“你好”的查询。RuntimeWiring.Buildergraphql.schema.DataFetcherspring-doc.cn

1 将此方法绑定到查询，即 Query 类型下的字段。
2 如果未在注释上声明，则从方法名称确定查询。

声明

您可以将 bean 定义为标准的 Spring bean 定义。构造型允许自动检测，与 Spring 通用 支持 Detecting 和 类 为它们自动注册 bean 定义。它还充当带注释的 类，指示其在 GraphQL 应用程序中作为数据获取组件的角色。@Controller@Controller@Controller@Componentspring-doc.cn

AnnotatedControllerConfigurer检测 bean 并注册其 带注释的处理程序方法为 S 通过 .它是一个 的实现可以添加到 . Boot Starter 自动声明为 bean 并将所有 bean 添加到 和 中，这将启用 支持带注释的 s，请参阅 GraphQL RuntimeWiring 部分 在 Boot Starter 文档中。@ControllerDataFetcherRuntimeWiring.BuilderRuntimeWiringConfigurerGraphQlSource.BuilderAnnotatedControllerConfigurerRuntimeWiringConfigurerGraphQlSource.BuilderDataFetcherspring-doc.cn

@SchemaMapping

注释将处理程序方法映射到 GraphQL 架构中的字段 并声明它是该字段的 。注解可以指定 父类型名称，以及字段名称：@SchemaMappingDataFetcherspring-doc.cn

@Controller
public class BookController {

	@SchemaMapping(typeName="Book", field="author")
	public Author getAuthor(Book book) {
		// ...
	}
}

注解也可以省略这些属性，在这种情况下， field name 默认为 method name，而 type name 默认为 simple 类 注入方法的源/父对象的名称。例如，下面的 默认为 type “Book” 和字段 “author”：@SchemaMappingspring-doc.cn

@Controller
public class BookController {

	@SchemaMapping
	public Author author(Book book) {
		// ...
	}
}

可以在类级别声明 Comments 以指定默认值 键入类中所有处理程序方法的 name。@SchemaMappingspring-doc.cn

@Controller
@SchemaMapping(typeName="Book")
public class BookController {

	// @SchemaMapping methods for fields of the "Book" type

}

@QueryMapping、 和 是元注释，它们 本身带有 Comments ，并且 typeName 分别预设为 、 或 。实际上，这些是快捷方式注释 for 字段 Query， Mutation 和 Subscription 类型。例如：@MutationMapping@SubscriptionMapping@SchemaMappingQueryMutationSubscriptionspring-doc.cn

@Controller
public class BookController {

	@QueryMapping
	public Book bookById(@Argument Long id) {
		// ...
	}

	@MutationMapping
	public Book addBook(@Argument BookInput bookInput) {
		// ...
	}

	@SubscriptionMapping
	public Flux<Book> newPublications() {
		// ...
	}
}

@SchemaMapping处理程序方法具有灵活的签名，并且可以从一系列 方法参数和返回值..spring-doc.cn

方法参数

架构映射处理程序方法可以具有以下任何方法参数：spring-doc.cn

方法参数 描述

@Argumentspring-doc.cn

用于访问绑定到更高级别类型化 Object 的命名字段参数。spring-doc.cn

请参阅 @Argument。spring-doc.cn

@Argument Map<String, Object>spring-doc.cn

用于访问原始参数值。spring-doc.cn

请参阅 @Argument。spring-doc.cn

ArgumentValuespring-doc.cn

用于访问绑定到更高级别的类型化 Object 的命名字段参数 带有一个标志，用于指示是否省略了 input 参数，而不是设置为 。nullspring-doc.cn

请参阅 ArgumentValue。spring-doc.cn

@Argumentsspring-doc.cn

用于访问绑定到更高级别类型化 Object 的所有字段参数。spring-doc.cn

请参阅 @Arguments。spring-doc.cn

@Arguments Map<String, Object>spring-doc.cn

用于访问参数的原始映射。spring-doc.cn

@ProjectedPayload接口spring-doc.cn

用于通过项目接口访问字段参数。spring-doc.cn

请参阅 @ProjectedPayload 界面。spring-doc.cn

“来源”spring-doc.cn

用于访问字段的源（即父级/容器）实例。spring-doc.cn

请参阅源代码。spring-doc.cn

Subrange和ScrollSubrangespring-doc.cn

用于访问分页参数。spring-doc.cn

请参阅 Pagination， Scroll， Subrange。spring-doc.cn

Sortspring-doc.cn

用于访问排序详细信息。spring-doc.cn

请参阅 Pagination， Sort。spring-doc.cn

DataLoaderspring-doc.cn

要访问 .DataLoaderDataLoaderRegistryspring-doc.cn

请参阅 DataLoader。spring-doc.cn

@ContextValuespring-doc.cn

要从 中的主 访问属性。GraphQLContextDataFetchingEnvironmentspring-doc.cn

@LocalContextValuespring-doc.cn

要从 中的本地访问属性。GraphQLContextDataFetchingEnvironmentspring-doc.cn

GraphQLContextspring-doc.cn

要从 .DataFetchingEnvironmentspring-doc.cn

java.security.Principalspring-doc.cn

从 Spring Security 上下文获取（如果可用）。spring-doc.cn

@AuthenticationPrincipalspring-doc.cn

用于从 Spring Security 上下文访问。Authentication#getPrincipal()spring-doc.cn

DataFetchingFieldSelectionSetspring-doc.cn

要通过 .DataFetchingEnvironmentspring-doc.cn

Locale,Optional<Locale>spring-doc.cn

要从 访问 。LocaleDataFetchingEnvironmentspring-doc.cn

DataFetchingEnvironmentspring-doc.cn

要直接访问底层 .DataFetchingEnvironmentspring-doc.cn

返回值

架构映射处理程序方法可以返回：spring-doc.cn

  • 任何类型的 resolved 值。spring-doc.cn

  • Mono以及 asynchronous value（s）。支持控制器方法和 any 中，如 Reactive DataFetcher 中所述。FluxDataFetcherspring-doc.cn

  • Kotlin 协程，并适应 和 。FlowMonoFluxspring-doc.cn

  • java.util.concurrent.Callable以异步方式生成值。 要使其正常工作，必须配置一个 .AnnotatedControllerConfigurerExecutorspring-doc.cn

在 Java 21+ 上，当配置了 ， 控制器 具有阻塞方法签名的方法将异步调用。默认情况下，控制器 如果 method 不返回异步类型（如 、 、 ），并且也不是 Kotlin 挂起函数，则视为阻塞。您可以配置 blocking controller 方法提供帮助 确定哪些方法被视为阻塞。AnnotatedControllerConfigurerExecutorFluxMonoCompletableFuturePredicateAnnotatedControllerConfigurerspring-doc.cn

设置属性后，Spring Boot starter for Spring for GraphQL 会自动配置为虚拟线程。AnnotatedControllerConfigurerExecutorspring.threads.virtual.enabled

接口架构映射

当控制器方法映射到架构接口字段时，默认情况下，映射为 替换为多个映射，每个映射对应实现接口的每个架构对象类型。 这允许对所有子类型使用一个控制器方法。spring-doc.cn

例如，给定：spring-doc.cn

type Query {
	activities: [Activity!]!
}

interface Activity {
	id: ID!
	coordinator: User!
}

type FooActivity implements Activity {
	id: ID!
	coordinator: User!
}

type BarActivity implements Activity {
	id: ID!
	coordinator: User!
}

type User {
	name: String!
}

您可以编写这样的控制器：spring-doc.cn

@Controller
public class BookController {

	@QueryMapping
	public List<Activity> activities() {
		// ...
	}

	@SchemaMapping
	public User coordinator(Activity activity) {
		// Called for any Activity subtype
	}

}

如有必要，您可以接管各个子类型的映射：spring-doc.cn

@Controller
public class BookController {

	@QueryMapping
	public List<Activity> activities() {
		// ...
	}

	@SchemaMapping
	public User coordinator(Activity activity) {
		// Called for any Activity subtype except FooActivity
	}

	@SchemaMapping
	public User coordinator(FooActivity activity) {
		// ...
	}

}

@Argument

在 GraphQL Java 中，提供对特定于字段的映射的访问 argument 值。这些值可以是简单的标量值（例如 String、Long）、a 或 values 用于更复杂的输入，或 a of 值。DataFetchingEnvironmentMapListspring-doc.cn

使用注释将参数绑定到目标对象，并使用 注入到 handler 方法中。通过将参数值映射到 primary data 构造函数，或者使用默认的 constructor 创建对象，然后将 argument 值映射到其属性。这是 递归重复，使用所有嵌套参数值并创建嵌套目标对象 因此。例如：@Argumentspring-doc.cn

@Controller
public class BookController {

	@QueryMapping
	public Book bookById(@Argument Long id) {
		// ...
	}

	@MutationMapping
	public Book addBook(@Argument BookInput bookInput) {
		// ...
	}
}
如果目标对象没有 setter，并且您无法更改它，则可以使用 属性 on 允许通过 Direct 进行回退绑定 字段访问。AnnotatedControllerConfigurer

默认情况下，如果方法参数名称可用（需要编译器 标志替换为 Java 8+ 或编译器中的调试信息），它用于查找参数。 如果需要，您可以通过 annotation 自定义名称，例如 .-parameters@Argument("bookInput")spring-doc.cn

注解没有 “required” 标志，也没有 指定 Default （默认值）。这两者都可以在 GraphQL 架构级别指定，并且 由 GraphQL Java 强制执行。@Argument

如果绑定失败，则会引发 a，并将绑定问题累积为字段 errors，其中 of each error 是出现问题的参数路径。BindExceptionfieldspring-doc.cn

您可以与参数一起使用，以获取 参数。例如：@ArgumentMap<String, Object>spring-doc.cn

@Controller
public class BookController {

	@MutationMapping
	public Book addBook(@Argument Map<String, Object> bookInput) {
		// ...
	}
}
在 1.2 之前，如果 注释未指定名称。在 1.2 之后，with 始终返回原始参数值，与名称匹配 在注释中指定，或添加到参数名称。要访问完整参数 map，请改用 @Arguments。@Argument Map<String, Object>@ArgumentMap<String, Object>

ArgumentValue

默认情况下，GraphQL 中的输入参数是可为 null 的可选参数，即参数 可以设置为 literal，或者根本不提供。这种区别对于 使用更改进行部分更新，其中基础数据也可能相应地设置为 或 根本不更改。使用 @Argument 时，没有办法进行这样的区分，因为在这两种情况下你都会得到 OR AN 空。nullnullnullOptionalspring-doc.cn

如果你不想知道某个值是否根本没有提供，你可以声明一个 method 参数，它是结果值的简单容器。 以及一个标志，以指示是否完全省略了 input 参数。你 可以使用 this 而不是 ，在这种情况下，参数名称由 方法参数名称，或与 一起指定参数名称。ArgumentValue@Argument@Argumentspring-doc.cn

例如：spring-doc.cn

@Controller
public class BookController {

	@MutationMapping
	public void addBook(ArgumentValue<BookInput> bookInput) {
		if (!bookInput.isOmitted()) {
			BookInput value = bookInput.value();
			// ...
		}
	}
}

ArgumentValue还支持作为方法参数的对象结构中的字段，通过 constructor 参数或 setter 初始化，包括 作为嵌套在顶级对象下任何级别的对象的字段。@Argumentspring-doc.cn

@Arguments

如果要将完整的参数映射绑定到单个 target Object 的 ，而 则绑定特定的命名参数。@Arguments@Argumentspring-doc.cn

例如，使用参数 “bookInput” 的值 来初始化 ，while 使用完整的参数映射，并在其中 case 时，顶级参数将绑定到 properties。@Argument BookInput bookInputBookInput@ArgumentsBookInputspring-doc.cn

您可以与参数一起使用，以获取 all 参数值。@ArgumentsMap<String, Object>spring-doc.cn

@ProjectedPayload接口

作为将完整 Objects 与 @Argument 结合使用的替代方法， 您还可以使用投影接口通过 定义明确的最小接口。当 Spring Data 位于 class path 上时，参数投影由 Spring Data 的接口投影提供。spring-doc.cn

要使用此功能，请创建一个带有 Comments 并声明 it 作为控制器方法参数。如果参数用 ， 它适用于 Map 中的单个参数。当声明时没有 ，投影适用于 完整的 arguments 映射。@ProjectedPayload@ArgumentDataFetchingEnvironment.getArguments()@Argumentspring-doc.cn

例如：spring-doc.cn

@Controller
public class BookController {

	@QueryMapping
	public Book bookById(BookIdProjection bookId) {
		// ...
	}

	@MutationMapping
	public Book addBook(@Argument BookInputProjection bookInput) {
		// ...
	}
}

@ProjectedPayload
interface BookIdProjection {

	Long getId();
}

@ProjectedPayload
interface BookInputProjection {

	String getName();

	@Value("#{target.author + ' ' + target.name}")
	String getAuthorAndName();
}

源

在 GraphQL Java 中，它提供对源（即 parent/container） 实例。要访问它，只需声明一个 method 参数 的预期目标类型。DataFetchingEnvironmentspring-doc.cn

@Controller
public class BookController {

	@SchemaMapping
	public Author author(Book book) {
		// ...
	}
}

source method 参数还有助于确定 Map 的类型名称。 如果 Java 类的简单名称与 GraphQL 类型匹配，则无需 在 Annotation 中显式指定 type name。@SchemaMappingspring-doc.cn

@BatchMapping 处理程序方法可以批量加载查询的所有作者。 给定 Source/Parent Books 对象的列表。spring-doc.cn

Subrange

当 Spring 配置中存在 CursorStrategy bean 时， 控制器方法支持参数，其中 是相对位置 从游标转换而来。对于 Spring Data，公开 . 例如：Subrange<P><P>ScrollSubrangeScrollPositionspring-doc.cn

@Controller
public class BookController {

	@QueryMapping
	public Window<Book> books(ScrollSubrange subrange) {
		ScrollPosition position = subrange.position().orElse(ScrollPosition.offset());
		int count = subrange.count().orElse(20);
		// ...
	}

}

有关分页和内置机制的概述，请参阅 Pagination。spring-doc.cn

Sort

当 Spring 配置中有 SortStrategy bean 时，控制器 methods 支持作为方法参数。例如：Sortspring-doc.cn

@Controller
public class BookController {

	@QueryMapping
	public Window<Book> books(Optional<Sort> optionalSort) {
		Sort sort = optionalSort.orElse(Sort.by(..));
	}

}

DataLoader

当您为实体注册批量加载函数时，如批量加载中所述，您可以通过声明 method 参数，并使用它来加载实体：DataLoaderDataLoaderspring-doc.cn

@Controller
public class BookController {

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

	@SchemaMapping
	public CompletableFuture<Author> author(Book book, DataLoader<Long, Author> loader) {
		return loader.load(book.getAuthorId());
	}

}

默认情况下，使用值类型的完整类名（例如 ） 的类名 ） 作为注册的键，因此只需声明 泛型类型的 method 参数提供了足够的信息 以在 .作为回退，method 参数 Resolver 还会尝试将方法参数 name 作为键，但通常不应这样做 是必要的。BatchLoaderRegistryAuthorDataLoaderDataLoaderRegistryDataLoaderspring-doc.cn

请注意，对于加载相关实体的许多情况，其中简单的 委托给 ，您可以通过使用 @BatchMapping 方法减少样板，如下一节所述。@SchemaMappingDataLoaderspring-doc.cn

验证

找到 Bean 后，在带 Comments 的控制器方法上启用对 Bean 验证的支持。通常，该 bean 的类型为 。javax.validation.ValidatorAnnotatedControllerConfigurerLocalValidatorFactoryBeanspring-doc.cn

Bean 验证允许你对类型声明约束：spring-doc.cn

public class BookInput {

	@NotNull
	private String title;

	@NotNull
	@Size(max=13)
	private String isbn;
}

然后，您可以对控制器方法参数进行注释，以便在 方法调用：@Validspring-doc.cn

@Controller
public class BookController {

	@MutationMapping
	public Book addBook(@Argument @Valid BookInput bookInput) {
		// ...
	}
}

如果在验证期间发生错误，则会引发 a。 您可以使用 Exceptions 链来决定如何将其呈现给客户端 将其转换为错误以包含在 GraphQL 响应中。ConstraintViolationExceptionspring-doc.cn

除了 之外，您还可以使用 Spring 的 Spring，它允许 指定验证组。@Valid@Validated

Bean 验证对于 @Argument、@Arguments 和 @ProjectedPayload 方法参数很有用，但更普遍地适用于任何方法参数。spring-doc.cn

验证和 Kotlin 协程

Hibernate Validator 与 Kotlin 协程方法不兼容，并且在 内省他们的方法参数。请参阅 spring-projects/spring-graphql#344 （评论） 以获取相关问题的链接和建议的解决方法。spring-doc.cn
方法参数 描述

@Argumentspring-doc.cn

用于访问绑定到更高级别类型化 Object 的命名字段参数。spring-doc.cn

请参阅 @Argument。spring-doc.cn

@Argument Map<String, Object>spring-doc.cn

用于访问原始参数值。spring-doc.cn

请参阅 @Argument。spring-doc.cn

ArgumentValuespring-doc.cn

用于访问绑定到更高级别的类型化 Object 的命名字段参数 带有一个标志，用于指示是否省略了 input 参数，而不是设置为 。nullspring-doc.cn

请参阅 ArgumentValue。spring-doc.cn

@Argumentsspring-doc.cn

用于访问绑定到更高级别类型化 Object 的所有字段参数。spring-doc.cn

请参阅 @Arguments。spring-doc.cn

@Arguments Map<String, Object>spring-doc.cn

用于访问参数的原始映射。spring-doc.cn

@ProjectedPayload接口spring-doc.cn

用于通过项目接口访问字段参数。spring-doc.cn

请参阅 @ProjectedPayload 界面。spring-doc.cn

“来源”spring-doc.cn

用于访问字段的源（即父级/容器）实例。spring-doc.cn

请参阅源代码。spring-doc.cn

Subrange和ScrollSubrangespring-doc.cn

用于访问分页参数。spring-doc.cn

请参阅 Pagination， Scroll， Subrange。spring-doc.cn

Sortspring-doc.cn

用于访问排序详细信息。spring-doc.cn

请参阅 Pagination， Sort。spring-doc.cn

DataLoaderspring-doc.cn

要访问 .DataLoaderDataLoaderRegistryspring-doc.cn

请参阅 DataLoader。spring-doc.cn

@ContextValuespring-doc.cn

要从 中的主 访问属性。GraphQLContextDataFetchingEnvironmentspring-doc.cn

@LocalContextValuespring-doc.cn

要从 中的本地访问属性。GraphQLContextDataFetchingEnvironmentspring-doc.cn

GraphQLContextspring-doc.cn

要从 .DataFetchingEnvironmentspring-doc.cn

java.security.Principalspring-doc.cn

从 Spring Security 上下文获取（如果可用）。spring-doc.cn

@AuthenticationPrincipalspring-doc.cn

用于从 Spring Security 上下文访问。Authentication#getPrincipal()spring-doc.cn

DataFetchingFieldSelectionSetspring-doc.cn

要通过 .DataFetchingEnvironmentspring-doc.cn

Locale,Optional<Locale>spring-doc.cn

要从 访问 。LocaleDataFetchingEnvironmentspring-doc.cn

DataFetchingEnvironmentspring-doc.cn

要直接访问底层 .DataFetchingEnvironmentspring-doc.cn
设置属性后，Spring Boot starter for Spring for GraphQL 会自动配置为虚拟线程。AnnotatedControllerConfigurerExecutorspring.threads.virtual.enabled
如果目标对象没有 setter，并且您无法更改它，则可以使用 属性 on 允许通过 Direct 进行回退绑定 字段访问。AnnotatedControllerConfigurer
注解没有 “required” 标志，也没有 指定 Default （默认值）。这两者都可以在 GraphQL 架构级别指定，并且 由 GraphQL Java 强制执行。@Argument
在 1.2 之前，如果 注释未指定名称。在 1.2 之后，with 始终返回原始参数值，与名称匹配 在注释中指定，或添加到参数名称。要访问完整参数 map，请改用 @Arguments。@Argument Map<String, Object>@ArgumentMap<String, Object>

@BatchMapping 处理程序方法可以批量加载查询的所有作者。 给定 Source/Parent Books 对象的列表。spring-doc.cn
除了 之外，您还可以使用 Spring 的 Spring，它允许 指定验证组。@Valid@Validated
验证和 Kotlin 协程

Hibernate Validator 与 Kotlin 协程方法不兼容，并且在 内省他们的方法参数。请参阅 spring-projects/spring-graphql#344 （评论） 以获取相关问题的链接和建议的解决方法。spring-doc.cn

@BatchMapping

批量加载通过使用 an 来延迟单个实体实例的加载，从而解决了 N+1 select 问题，因此它们 可以一起加载。例如：org.dataloader.DataLoaderspring-doc.cn

@Controller
public class BookController {

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

	@SchemaMapping
	public CompletableFuture<Author> author(Book book, DataLoader<Long, Author> loader) {
		return loader.load(book.getAuthorId());
	}

}

对于加载关联实体的直接情况（如上所示），该方法只不过将 .这是 样板，可以通过方法避免。例如：@SchemaMappingDataLoader@BatchMappingspring-doc.cn

@Controller
public class BookController {

	@BatchMapping
	public Mono<Map<Book, Author>> author(List<Book> books) {
		// ...
	}
}

以上内容成为 where keys 是 instances 和 loaded values their authors 中的批量加载函数。此外， a 还透明地绑定到 type 的 field ，该 只需委托给 for authors，给定其 source/parent 实例。BatchLoaderRegistryBookDataFetcherauthorBookDataLoaderBookspring-doc.cn

要用作唯一键，必须实现 和 。Bookhashcodeequalsspring-doc.cn

默认情况下，字段名称默认为方法名称，而类型名称默认为 input 元素类型的 Simple Class Name。两者都可以通过以下方式进行定制 annotation 属性。类型名称也可以从 class level 继承。List@SchemaMappingspring-doc.cn

方法参数

批量映射方法支持以下参数：spring-doc.cn

方法参数 描述

List<K>spring-doc.cn

源/父对象。spring-doc.cn

java.security.Principalspring-doc.cn

从 Spring Security 上下文获取（如果可用）。spring-doc.cn

@ContextValuespring-doc.cn

要从 中访问值 ， 这与 .GraphQLContextBatchLoaderEnvironmentDataFetchingEnvironmentspring-doc.cn

GraphQLContextspring-doc.cn

要从 访问上下文 ， 这与 .BatchLoaderEnvironmentDataFetchingEnvironmentspring-doc.cn

BatchLoaderEnvironmentspring-doc.cn

GraphQL Java 中可用的环境到 .org.dataloader.BatchLoaderWithContextspring-doc.cn

返回值

批量映射方法可以返回：spring-doc.cn

返回类型 描述

Mono<Map<K,V>>spring-doc.cn

一个映射，其中父对象作为键，批量加载的对象作为值。spring-doc.cn

Flux<V>spring-doc.cn

批量加载的对象序列，必须与源/父对象的顺序相同 对象。spring-doc.cn

Map<K,V>,Collection<V>spring-doc.cn

命令式变体，例如，无需远程调用。spring-doc.cn

Callable<Map<K,V>>,Callable<Collection<V>>spring-doc.cn

异步调用的命令式变体。要使其正常工作，必须配置一个 .AnnotatedControllerConfigurerExecutorspring-doc.cn

Kotlin 协程与 ， KotlinMap<K,V>Flow<K,V>spring-doc.cn

适应于 和 。Mono<Map<K,V>Flux<V>spring-doc.cn

在 Java 21+ 上，当配置了 ， 控制器 具有阻塞方法签名的方法将异步调用。默认情况下，控制器 如果 method 不返回异步类型（如 、 、 ），并且也不是 Kotlin 挂起函数，则视为阻塞。您可以配置 blocking controller 方法提供帮助 确定哪些方法被视为阻塞。AnnotatedControllerConfigurerExecutorFluxMonoCompletableFuturePredicateAnnotatedControllerConfigurerspring-doc.cn

设置属性后，Spring Boot starter for Spring for GraphQL 会自动配置为虚拟线程。AnnotatedControllerConfigurerExecutorspring.threads.virtual.enabled

接口批处理映射

与 Interface Schema Mappings 一样， 将批处理映射方法映射到 Schema Interface 字段时，该映射将替换为 多个映射，每个映射用于实现接口的每个 Schema 对象类型。spring-doc.cn

这意味着，给定以下内容：spring-doc.cn

type Query {
	activities: [Activity!]!
}

interface Activity {
	id: ID!
	coordinator: User!
}

type FooActivity implements Activity {
	id: ID!
	coordinator: User!
}

type BarActivity implements Activity {
	id: ID!
	coordinator: User!
}

type User {
	name: String!
}

您可以编写这样的控制器：spring-doc.cn

@Controller
public class BookController {

	@QueryMapping
	public List<Activity> activities() {
		// ...
	}

	@BatchMapping
	Map<Activity, User> coordinator(List<Activity> activities) {
		// Called for all Activity subtypes
	}
}

如有必要，您可以接管各个子类型的映射：spring-doc.cn

@Controller
public class BookController {

	@QueryMapping
	public List<Activity> activities() {
		// ...
	}

	@BatchMapping
	Map<Activity, User> coordinator(List<Activity> activities) {
		// Called for all Activity subtypes
	}

	@BatchMapping(field = "coordinator")
	Map<Activity, User> fooCoordinator(List<FooActivity> activities) {
		// ...
	}
}

要用作唯一键，必须实现 和 。Bookhashcodeequalsspring-doc.cn
方法参数 描述

List<K>spring-doc.cn

源/父对象。spring-doc.cn

java.security.Principalspring-doc.cn

从 Spring Security 上下文获取（如果可用）。spring-doc.cn

@ContextValuespring-doc.cn

要从 中访问值 ， 这与 .GraphQLContextBatchLoaderEnvironmentDataFetchingEnvironmentspring-doc.cn

GraphQLContextspring-doc.cn

要从 访问上下文 ， 这与 .BatchLoaderEnvironmentDataFetchingEnvironmentspring-doc.cn

BatchLoaderEnvironmentspring-doc.cn

GraphQL Java 中可用的环境到 .org.dataloader.BatchLoaderWithContextspring-doc.cn
返回类型 描述

Mono<Map<K,V>>spring-doc.cn

一个映射，其中父对象作为键，批量加载的对象作为值。spring-doc.cn

Flux<V>spring-doc.cn

批量加载的对象序列，必须与源/父对象的顺序相同 对象。spring-doc.cn

Map<K,V>,Collection<V>spring-doc.cn

命令式变体，例如，无需远程调用。spring-doc.cn

Callable<Map<K,V>>,Callable<Collection<V>>spring-doc.cn

异步调用的命令式变体。要使其正常工作，必须配置一个 .AnnotatedControllerConfigurerExecutorspring-doc.cn

Kotlin 协程与 ， KotlinMap<K,V>Flow<K,V>spring-doc.cn

适应于 和 。Mono<Map<K,V>Flux<V>spring-doc.cn
设置属性后，Spring Boot starter for Spring for GraphQL 会自动配置为虚拟线程。AnnotatedControllerConfigurerExecutorspring.threads.virtual.enabled

@GraphQlExceptionHandler

使用方法处理数据获取异常，并使用 灵活的方法签名。当在 controller 时，异常处理程序方法适用于来自同一控制器的异常：@GraphQlExceptionHandlerspring-doc.cn

@Controller
public class BookController {

	@QueryMapping
	public Book bookById(@Argument Long id) {
		// ...
	}

	@GraphQlExceptionHandler
	public GraphQLError handle(BindException ex) {
		return GraphQLError.newError().errorType(ErrorType.BAD_REQUEST).message("...").build();
	}
}

在 中声明时，异常处理程序方法将应用于跨控制器：@ControllerAdvicespring-doc.cn

@ControllerAdvice
public class GlobalExceptionHandler {

	@GraphQlExceptionHandler
	public GraphQLError handle(BindException ex) {
		return GraphQLError.newError().errorType(ErrorType.BAD_REQUEST).message("...").build();
	}

}

通过方法进行的异常处理会自动应用于 控制器调用。要处理来自其他实现的异常，而不是基于控制器方法，请获取 from ，并将其注册为 DataFetcherExceptionResolver。@GraphQlExceptionHandlergraphql.schema.DataFetcherDataFetcherExceptionResolverAnnotatedControllerConfigurerGraphQlSource.Builderspring-doc.cn

方法签名

异常处理程序方法支持带有方法参数的灵活方法签名 从 a 解析并匹配到 @SchemaMapping 方法的 THE SETTINGS。DataFetchingEnvironment,spring-doc.cn

支持的返回类型如下：spring-doc.cn

返回类型 描述

graphql.GraphQLErrorspring-doc.cn

将异常解决为单字段错误。spring-doc.cn

Collection<GraphQLError>spring-doc.cn

解决多个字段错误的异常。spring-doc.cn

voidspring-doc.cn

解决异常而不出现响应错误。spring-doc.cn

Objectspring-doc.cn

将异常解决为单个错误、多个错误或无异常。 返回值必须是 、 或 。GraphQLErrorCollection<GraphQLError>nullspring-doc.cn

Mono<T>spring-doc.cn

对于异步解析，其中 是支持的同步返回类型之一。<T>spring-doc.cn
返回类型 描述

graphql.GraphQLErrorspring-doc.cn

将异常解决为单字段错误。spring-doc.cn

Collection<GraphQLError>spring-doc.cn

解决多个字段错误的异常。spring-doc.cn

voidspring-doc.cn

解决异常而不出现响应错误。spring-doc.cn

Objectspring-doc.cn

将异常解决为单个错误、多个错误或无异常。 返回值必须是 、 或 。GraphQLErrorCollection<GraphQLError>nullspring-doc.cn

Mono<T>spring-doc.cn

对于异步解析，其中 是支持的同步返回类型之一。<T>spring-doc.cn

命名空间

在架构级别，查询和更改操作直接在 and 类型下定义。 丰富的 GraphQL API 可以定义数十个操作来区分这些类型，这使得探索 API 和分离关注点变得更加困难。 您可以选择在 GraphQL 架构中定义命名空间。 虽然这种方法有一些注意事项，但您可以使用 Spring for GraphQL 注释的控制器实现此模式。QueryMutationspring-doc.cn

例如，通过命名空间，您的 GraphQL 架构可以将查询操作嵌套在顶级类型下，而不是直接将它们列在 . 在这里，我们将定义和类型，并在 下提供它们：QueryMusicQueriesUserQueriesQueryspring-doc.cn

type Query {
    music: MusicQueries
    users: UserQueries
}

type MusicQueries {
    album(id: ID!): Album
    searchForArtist(name: String!): [Artist]
}

type Album {
    id: ID!
    title: String!
}

type Artist {
    id: ID!
    name: String!
}

type UserQueries {
    user(login: String): User
}

type User {
    id: ID!
    login: String!
}

GraphQL 客户端将使用以下查询：albumspring-doc.cn

{
  music {
    album(id: 42) {
      id
      title
    }
  }
}

并得到以下响应：spring-doc.cn

{
  "data": {
    "music": {
      "album": {
        "id": "42",
        "title": "Spring for GraphQL"
      }
    }
  }
}

这可以通过以下模式实现：@Controllerspring-doc.cn

import java.util.List;

import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.graphql.data.method.annotation.SchemaMapping;
import org.springframework.stereotype.Controller;

@Controller
@SchemaMapping(typeName = "MusicQueries") (1)
public class MusicController {

	@QueryMapping (2)
	public MusicQueries music() {
		return new MusicQueries();
	}

	(3)
	public record MusicQueries() {

	}

	@SchemaMapping (4)
	public Album album(@Argument String id) {
		return new Album(id, "Spring GraphQL");
	}

	@SchemaMapping
	public List<Artist> searchForArtist(@Argument String name) {
		return List.of(new Artist("100", "the Spring team"));
	}


}
1 使用 and 属性注释控制器，以避免在方法上重复它@SchemaMappingtypeName
2 为 “music” 命名空间定义一个@QueryMapping
3 “music” 查询返回 “空” 记录，但也可能返回空地图
4 查询现在声明为 “MusicQueries” 类型下的字段

无需在控制器中显式声明包装类型（“MusicQueries”、“UserQueries”），不如在控制器中显式声明包装类型 您可以选择使用 Spring Boot 通过 runtime 连接来配置它们：GraphQlSourceBuilderCustomizerspring-doc.cn

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

import org.springframework.boot.autoconfigure.graphql.GraphQlSourceBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;


@Configuration
public class NamespaceConfiguration {

	@Bean
	public GraphQlSourceBuilderCustomizer customizer() {
		List<String> queryWrappers = List.of("music", "users"); (1)

		return (sourceBuilder) -> sourceBuilder.configureRuntimeWiring((wiringBuilder) ->
				queryWrappers.forEach((field) -> wiringBuilder.type("Query",
						(builder) -> builder.dataFetcher(field, (env) -> Collections.emptyMap()))) (2)
		);
	}

}
1 列出 “Query” 类型的所有包装类型
2 为每个 Map 手动声明数据获取器，返回一个空的 Map
1 使用 and 属性注释控制器，以避免在方法上重复它@SchemaMappingtypeName
2 为 “music” 命名空间定义一个@QueryMapping
3 “music” 查询返回 “空” 记录，但也可能返回空地图
4 查询现在声明为 “MusicQueries” 类型下的字段
1 列出 “Query” 类型的所有包装类型
2 为每个 Map 手动声明数据获取器，返回一个空的 Map