本文详解如何利用 SPQR 的 @Batched 注解实现字段级批量加载，避免因嵌套查询导致的 N+1 性能瓶颈，显著提升 GraphQL 接口响应效率。
本文详解如何利用 spqr 的 `@batched` 注解实现字段级批量加载，避免因嵌套查询导致的 n+1 性能瓶颈，显著提升 graphql 接口响应效率。
在使用 leangen/graphql-spqr 构建 GraphQL 服务时，N+1 问题是一个典型性能陷阱：当查询返回多个对象（如 10 本图书），而每个对象又需单独调用一个关联字段解析器（如 price）时，就会触发 10 次独立的数据获取操作——这不仅增加网络/数据库开销，更严重拖慢响应时间。
SPQR 提供了原生、简洁的解决方案：@Batched 批量解析注解。它能自动将单个对象上下文（@GraphQLContext Book）聚合为列表上下文（@GraphQLContext List<book></book>），使开发者只需编写一次批量获取逻辑，即可替代 N 次重复调用。
✅ 正确做法如下：
@GraphQLQuery(name = "getAllBooks", description = "Get all books")
public List<Book> getAllBooks() {
return bookService.getAllBooks();
}
@Batched // ← 关键：启用批量加载
@GraphQLQuery
public List<Long> price(@GraphQLContext List<Book> books) {
// 批量获取所有图书价格（例如：一次 HTTP 批量请求、一次 SQL IN 查询）
return bookPriceService.fetchPricesByIds(
books.stream().map(Book::getId).collect(Collectors.toList())
);
}⚠️ 注意事项：
-
@Batched方法签名必须严格匹配：参数为List<t></t>类型的@GraphQLContext，返回值为List<r></r>（与单条解析器返回类型一致）； - 若你未使用
graphql-spqr-spring-boot-starter（即纯 SPQR 集成），必须通过GraphQLRuntime初始化 GraphQL 实例，否则@Batched不生效：
ExecutableSchema schema = new GraphQLSchemaGenerator()
.withOperationsFromSingleton(new BookResolver()) // 包含 @Batched 方法的类
.generateExecutable();
// ✅ 正确：GraphQLRuntime 支持自动注册 BatchLoader
GraphQL gql = GraphQLRuntime.newGraphQL(schema).build();
// ❌ 错误：标准 GraphQL 构造器会忽略 @Batched 元数据
// GraphQL gql = GraphQL.newGraphQL(schema).build();? 进阶建议：
对于更复杂的场景（如需根据字段选择动态预加载关联数据），可结合 DataFetchingEnvironment.getSelectionSet() 判断当前查询是否包含 price 字段，并在 getAllBooks() 中提前完成关联数据的批量加载（即“主动预取”策略）。这种方式虽需更多控制权，但能进一步减少解析阶段的延迟。
总结：@Batched 是 SPQR 中解决 N+1 问题最直接、侵入性最小的方案。合理使用它，配合正确的初始化方式，即可在不引入额外依赖（如 DataLoaderRegistryFactory）的前提下，实现高性能、声明式的批量数据获取。
