此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring GraphQL 1.4.1！spring-doc.cadn.net.cn

数据集成

Spring for GraphQL 允许您利用现有的 Spring 技术，遵循常见的编程模型，通过 GraphQL 公开底层数据源。spring-doc.cadn.net.cn

本节讨论 Spring Data 的集成层，它提供了一种简单的方法将 Querydsl 或 Query by Example 存储库调整为DataFetcher，包括用于自动检测和 GraphQL 查询注册标记为存储库的选项跟@GraphQlRepository.spring-doc.cadn.net.cn

查询

Spring for GraphQL 支持使用 Querydsl 通过 Spring Data Querydsl 扩展。 Querydsl 提供了一种灵活且类型安全的方法来表达查询谓词使用注释处理器生成元模型。spring-doc.cadn.net.cn

例如，将存储库声明为QuerydslPredicateExecutor:spring-doc.cadn.net.cn

public interface AccountRepository extends Repository<Account, Long>,
			QuerydslPredicateExecutor<Account> {
}

然后用它来创建一个DataFetcher:spring-doc.cadn.net.cn

// For single result queries
DataFetcher<Account> dataFetcher =
		QuerydslDataFetcher.builder(repository).single();

// For multi-result queries
DataFetcher<Iterable<Account>> dataFetcher =
		QuerydslDataFetcher.builder(repository).many();

// For paginated queries
DataFetcher<Iterable<Account>> dataFetcher =
		QuerydslDataFetcher.builder(repository).scrollable();

您现在可以注册上述内容DataFetcher通过RuntimeWiringConfigurer.spring-doc.cadn.net.cn

这DataFetcher构建一个 QuerydslPredicatefrom GraphQL 参数，并使用它来获取数据。Spring Data 支持QuerydslPredicateExecutor用于 JPA、MongoDB、Neo4j 和 LDAP。spring-doc.cadn.net.cn

对于作为 GraphQL 输入类型的单个参数，QuerydslDataFetcher嵌套一 level down，并使用参数子映射中的值。

如果存储库是ReactiveQuerydslPredicateExecutor，则构建器返回DataFetcher<Mono<Account>>或DataFetcher<Flux<Account>>.Spring Data 支持这一点 MongoDB 和 Neo4j 的变体。spring-doc.cadn.net.cn

构建设置

要在构建中配置 Querydsl，请遵循官方参考文档：spring-doc.cadn.net.cn

例如：spring-doc.cadn.net.cn

Gradlespring-doc.cadn.net.cn
Mavenspring-doc.cadn.net.cn

dependencies {
	//...

	annotationProcessor "com.querydsl:querydsl-apt:$querydslVersion:jakarta",
			'jakarta.persistence:jakarta.persistence-api'
}

compileJava {
	options.annotationProcessorPath = configurations.annotationProcessor
}

<build>
	<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<annotationProcessorPaths>
						<!-- Explicit opt-in required via annotationProcessors or
										annotationProcessorPaths on Java 22+, see https://bugs.openjdk.org/browse/JDK-8306819 -->
						<annotationProcessorPath>
							<groupId>com.querydsl</groupId>
							<artifactId>querydsl-apt</artifactId>
							<version>${querydsl.version}</version>
							<classifier>jakarta</classifier>
						</annotationProcessorPath>
						<annotationProcessorPath>
							<groupId>jakarta.persistence</groupId>
							<artifactId>jakarta.persistence-api</artifactId>
						</annotationProcessorPath>
					</annotationProcessorPaths>

					<!-- Recommended: Some IDE's might require this configuration to include generated sources for IDE usage -->
					<generatedTestSourcesDirectory>target/generated-test-sources</generatedTestSourcesDirectory>
					<generatedSourcesDirectory>target/generated-sources</generatedSourcesDirectory>
				</configuration>
			</plugin>
	</plugins>
</build>

定制

QuerydslDataFetcher支持自定义如何将 GraphQL 参数绑定到属性上创建 QuerydslPredicate.默认情况下，参数绑定为 “等于” 每个可用的属性。要自定义它，您可以使用QuerydslDataFetcher架构工人提供QuerydslBinderCustomizer.spring-doc.cadn.net.cn

存储库本身可以是QuerydslBinderCustomizer.这是自动检测的并在自动注册期间透明应用。但是，当手动构建一个QuerydslDataFetcher您将需要使用构建器方法来应用它。spring-doc.cadn.net.cn

QuerydslDataFetcher支持接口和 DTO 投影来转换查询结果在返回这些以进行进一步的 GraphQL 处理之前。spring-doc.cadn.net.cn

要了解什么是投影，请参阅 Spring Data 文档。要了解如何在GraphQL中使用投影，请参阅选择集与投影。

要将 Spring Data 投影与 Querydsl 存储库一起使用，请创建一个投影接口或目标 DTO 类，并通过projectAs获取DataFetcher生成目标类型：spring-doc.cadn.net.cn

class Account {

	String name, identifier, description;

	Person owner;
}

interface AccountProjection {

	String getName();

	String getIdentifier();
}

// For single result queries
DataFetcher<AccountProjection> dataFetcher =
		QuerydslDataFetcher.builder(repository).projectAs(AccountProjection.class).single();

// For multi-result queries
DataFetcher<Iterable<AccountProjection>> dataFetcher =
		QuerydslDataFetcher.builder(repository).projectAs(AccountProjection.class).many();

自动注册

如果存储库的注释为@GraphQlRepository，它会自动注册对于尚未注册的查询DataFetcher以及其返回类型与存储库域类型匹配。这包括单值查询、多值查询查询和分页查询。spring-doc.cadn.net.cn

默认情况下，查询返回的 GraphQL 类型的名称必须与简单名称匹配存储库域类型的。如果需要，您可以使用typeName属性@GraphQlRepository以指定目标 GraphQL 类型名称。spring-doc.cadn.net.cn

对于分页查询，存储库域类型的简单名称必须与Connection类型名称，而不使用Connection结尾（例如Book比赛BooksConnection).对于自动注册，分页基于偏移量，有 20 个项目每页。spring-doc.cadn.net.cn

自动注册检测给定存储库是否实现QuerydslBinderCustomizer和透明地通过QuerydslDataFetcherbuilder 方法。spring-doc.cadn.net.cn

自动注册是通过内置的RuntimeWiringConfigurer那可以是获得自QuerydslDataFetcher.启动Starters自动检测@GraphQlRepositorybean 并使用它们来初始化RuntimeWiringConfigurer跟。spring-doc.cadn.net.cn

自动注册通过调用customize(Builder)在存储库实例上，如果您的存储库实现QuerydslBuilderCustomizer或ReactiveQuerydslBuilderCustomizer分别。spring-doc.cadn.net.cn

按示例查询

Spring Data 支持使用 Query by Example 来获取数据。示例查询（QBE）是一种简单的查询技术，不需要您可以通过特定于商店的查询语言编写查询。spring-doc.cadn.net.cn

首先声明一个存储库，该存储库是QueryByExampleExecutor:spring-doc.cadn.net.cn

public interface AccountRepository extends Repository<Account, Long>,
			QueryByExampleExecutor<Account> {
}

用QueryByExampleDataFetcher将存储库转换为DataFetcher:spring-doc.cadn.net.cn

// For single result queries
DataFetcher<Account> dataFetcher =
		QueryByExampleDataFetcher.builder(repository).single();

// For multi-result queries
DataFetcher<Iterable<Account>> dataFetcher =
		QueryByExampleDataFetcher.builder(repository).many();

// For paginated queries
DataFetcher<Iterable<Account>> dataFetcher =
		QueryByExampleDataFetcher.builder(repository).scrollable();

您现在可以注册上述内容DataFetcher通过RuntimeWiringConfigurer.spring-doc.cadn.net.cn

这DataFetcher使用 GraphQL 参数映射创建存储库，并将其用作获取数据的示例对象。Spring Data 支持QueryByExampleDataFetcher适用于 JPA、MongoDB、Neo4j 和 Redis。spring-doc.cadn.net.cn

对于作为 GraphQL 输入类型的单个参数，QueryByExampleDataFetcher嵌套一级，并与参数子映射中的值绑定。

如果存储库是ReactiveQueryByExampleExecutor，则构建器返回DataFetcher<Mono<Account>>或DataFetcher<Flux<Account>>.Spring Data 支持这一点 MongoDB、Neo4j、Redis 和 R2dbc 的变体。spring-doc.cadn.net.cn

构建设置

Query by Example 已包含在数据存储的 Spring Data 模块中，其中它受支持，因此无需额外设置即可启用它。spring-doc.cadn.net.cn

定制

QueryByExampleDataFetcher支持接口和DTO投影转换查询结果，然后返回这些结果以进行进一步的 GraphQL 处理。spring-doc.cadn.net.cn

要了解什么是投影，请参阅 Spring Data 文档。要了解投影在 GraphQL 中的作用，请参阅选择集与投影。

要将 Spring Data 投影与 Query by Example 存储库一起使用，请创建一个投影接口或目标 DTO 类，并通过projectAs获取DataFetcher生成目标类型：spring-doc.cadn.net.cn

class Account {

	String name, identifier, description;

	Person owner;
}

interface AccountProjection {

	String getName();

	String getIdentifier();
}

// For single result queries
DataFetcher<AccountProjection> dataFetcher =
		QueryByExampleDataFetcher.builder(repository).projectAs(AccountProjection.class).single();

// For multi-result queries
DataFetcher<Iterable<AccountProjection>> dataFetcher =
		QueryByExampleDataFetcher.builder(repository).projectAs(AccountProjection.class).many();

自动注册

自动注册是通过内置的RuntimeWiringConfigurer那可以是获得自QueryByExampleDataFetcher.启动Starters自动检测@GraphQlRepositorybean 并使用它们来初始化RuntimeWiringConfigurer跟。spring-doc.cadn.net.cn

自动注册通过调用customize(Builder)在存储库实例上，如果您的存储库实现QueryByExampleBuilderCustomizer或ReactiveQueryByExampleBuilderCustomizer分别。spring-doc.cadn.net.cn

选择集与投影

出现的一个常见问题是，GraphQL 选择集与 Spring Data 投影相比如何，每个选择集扮演什么角色？spring-doc.cadn.net.cn

简短的回答是，Spring for GraphQL 不是翻译 GraphQL 的数据网关查询直接转换为 SQL 或 JSON 查询。相反，它允许您利用现有的 Spring 技术，并且不假设 GraphQL 架构与基础数据模型。这就是为什么客户端驱动的选择和服务器端转换的数据模型可以发挥互补作用。spring-doc.cadn.net.cn

为了更好地理解，请考虑 Spring Data 将领域驱动（DDD）设计推广为管理数据层复杂性的建议方法。在 DDD 中，重要的是以遵守聚合的约束。根据定义，聚合仅在以下情况下有效全部加载，因为部分加载的聚合可能会对聚合功能。spring-doc.cadn.net.cn

在 Spring Data 中，您可以选择是否希望聚合按原样公开，或者在将数据模型作为 GraphQL 返回之前，是否将转换应用于数据模型结果。有时做前者就足够了，默认情况下，Querydsl 和 Query by Example 集成会将 GraphQL 选择集到属性路径提示中，底层 Spring Data 模块用于限制选择。spring-doc.cadn.net.cn

在其他情况下，减少甚至转换以适应 GraphQL 架构。Spring Data 通过接口支持这一点和 DTO 预测。spring-doc.cadn.net.cn

界面投影定义一组固定的属性，以公开属性可能或可能不是null，具体取决于数据存储查询结果。有两种接口投影，两者都决定了要从底层加载的属性数据来源：spring-doc.cadn.net.cn

如果无法部分具体化聚合对象，则封闭界面投影会很有帮助，但您仍然想要公开属性的子集。spring-doc.cadn.net.cn
开放接口投影利用 Spring 的@Value注释和 SpEL 表达式来应用轻量级数据转换，例如串联、计算或应用静态函数到一个属性。spring-doc.cadn.net.cn

DTO 投影提供更高级别的自定义，因为您可以放置转换构造函数或 getter 方法中的代码。spring-doc.cadn.net.cn

DTO 投影从查询中实现，其中各个属性是由投影本身决定。DTO 投影通常与全参数一起使用构造函数（例如 Java 记录），因此只有在所有必填字段（或列）是数据库查询结果的一部分。spring-doc.cadn.net.cn

滚动

如分页中所述，GraphQL 游标连接规范定义了一个分页机制Connection,Edge和PageInfoschema 类型，而 GraphQL Java 提供了等效的 Java 类型表示。spring-doc.cadn.net.cn

Spring for GraphQL 提供内置的ConnectionAdapter实现以适应 Spring Data 分页类型Window和Slice透明。您可以配置如下：spring-doc.cadn.net.cn

CursorStrategy<ScrollPosition> strategy = CursorStrategy.withEncoder(
		new ScrollPositionCursorStrategy(),
		CursorEncoder.base64()); (1)

GraphQLTypeVisitor visitor = ConnectionFieldTypeVisitor.create(List.of(
		new WindowConnectionAdapter(strategy),
		new SliceConnectionAdapter(strategy))); (2)

GraphQlSource.schemaResourceBuilder()
		.schemaResources(..)
		.typeDefinitionConfigurer(..)
		.typeVisitors(List.of(visitor)); (3)

1	制定转化策略`ScrollPosition`到 Base64 编码的游标。
2	创建要适应的访问者类型`Window`和`Slice`返回自`DataFetcher`s.
3	注册类型 visitor。

在请求端，控制器方法可以声明 ScrollSubrange 方法参数以向前分页或向后。为此，您必须声明CursorStrategy支持ScrollPosition作为豆子。spring-doc.cadn.net.cn

Boot Starter 声明CursorStrategy<ScrollPosition>bean，并注册ConnectionFieldTypeVisitor如果 Spring Data 在类路径上，则如上所示。spring-doc.cadn.net.cn

键集位置

为KeysetScrollPosition，则需要从键集创建光标，即本质上是一个Map键值对。要决定如何从键集创建游标，您可以配置ScrollPositionCursorStrategy跟CursorStrategy<Map<String, Object>>. 默认情况下，JsonKeysetCursorStrategy写入密钥集Map到 JSON。这适用于简单，如 String、Boolean、Integer 和 Double，但其他无法恢复回没有目标类型信息的相同类型。Jackson 库具有默认的键入功能可以在 JSON 中包含类型信息。为了安全地使用它，您必须指定一个列表允许的类型。例如：spring-doc.cadn.net.cn

PolymorphicTypeValidator validator = BasicPolymorphicTypeValidator.builder()
		.allowIfBaseType(Map.class)
		.allowIfSubType(ZonedDateTime.class)
		.build();

ObjectMapper mapper = new ObjectMapper();
mapper.activateDefaultTyping(validator, ObjectMapper.DefaultTyping.NON_FINAL);

然后，您可以创建JsonKeysetCursorStrategy:spring-doc.cadn.net.cn

ObjectMapper mapper = ... ;

CodecConfigurer configurer = ServerCodecConfigurer.create();
configurer.defaultCodecs().jacksonJsonDecoder(new JacksonJsonDecoder(mapper));
configurer.defaultCodecs().jacksonJsonEncoder(new JacksonJsonEncoder(mapper));

JsonKeysetCursorStrategy strategy = new JsonKeysetCursorStrategy(configurer);

默认情况下，如果JsonKeysetCursorStrategy在没有CodecConfigurer和 Jackson 库在类路径上，应用了上述自定义Date,Calendar，以及来自java.time.spring-doc.cadn.net.cn

排序

Spring for GraphQL 定义了一个SortStrategy创建Sort来自 GraphQL 参数。AbstractSortStrategy使用抽象方法实现合约以提取排序方向和属性。启用对Sort作为控制器方法参数，您需要声明一个SortStrategy豆。spring-doc.cadn.net.cn