本文介绍如何将多个带有命名操作（如别名字段）的 graphql documentnode 合并为一个合法的、单 `query` 块内包含多个字段的 documentnode，避免因误用 `concat_ast` 导致的“anonymous operation must be the only defined operation”错误。
在使用 Python 处理 GraphQL 查询时，开发者常希望通过组合多个 DocumentNode（例如分别代表不同数据表的查询）来构建一个批量请求。然而，直接调用 graphql.utilities.concat_ast() 会将每个 DocumentNode 视为独立操作（即多个 { ... } 块），从而生成语法非法的 GraphQL 文本——GraphQL 规范明确禁止在单个文档中存在多个匿名操作（{ ... }），除非它们被包裹在统一的 query、mutation 或 subscription 操作声明中。
根本问题在于：concat_ast 是为合并多个完整操作（OperationDefinition）或片段（FragmentDefinition） 设计的，而非拼接多个“裸对象字面量”。你提供的示例中，原始 DocumentNode 实际上是仅含 SelectionSet 的匿名查询（即无 OperationDefinition 节点），concat_ast 将其作为独立操作节点合并，导致输出多个 {} 块，违反规范。
✅ 正确做法是：不依赖 AST 拼接，而是从结构化对象出发，显式构造一个带类型（如 "query"）和多个命名字段（alias + field）的 Operation，再渲染为合法 GraphQL 字符串，最后通过 gql() 解析为 DocumentNode。
推荐使用轻量、专为构建查询设计的第三方库 graphql-query（非官方但稳定、类型友好、无运行时依赖）。它提供面向对象的 DSL，可清晰表达别名、参数、嵌套字段等，并确保输出符合 GraphQL 规范的单操作文档。
以下为完整实现示例：
from graphql_query import Argument, Field, Operation, Query
from graphql import parse # 或使用 gql()（来自 graphql-core）
# 定义第一个命名字段：table1 别名指向 fetchTable1
fetchTable1 = Query(
name="fetchTable1",
alias="table1",
arguments=[
Argument(name="id", value=[5, 45]),
Argument(name="perPage", value=5),
Argument(name="currentPage", value=1),
],
fields=[Field(name="data", fields=["id", "name"])]
)
# 定义第二个命名字段：table2 别名指向 fetchTable2
fetchTable2 = Query(
name="fetchTable2",
alias="table2",
arguments=[
Argument(name="table1_id", value=[5, 45]),
Argument(name="perPage", value=5),
Argument(name="currentPage", value=1),
],
fields=[Field(name="data", fields=["id", "customer"])]
)
# 组合成一个顶层 query 操作（注意：type="query"）
operation = Operation(
type="query",
queries=[fetchTable1, fetchTable2],
)
# 渲染为标准 GraphQL 字符串
graphql_string = operation.render()
print(graphql_string)输出结果为合法的单操作 GraphQL 文本：
query {
table1: fetchTable1(
id: [5, 45]
perPage: 5
currentPage: 1
) {
data {
id
name
}
}
table2: fetchTable2(
table1_id: [5, 45]
perPage: 5
currentPage: 1
) {
data {
id
customer
}
}
}最后，转换为 DocumentNode 供执行器（如 graphql_sync 或 Apollo Client）使用：
from graphql import parse document_node = parse(graphql_string) # ✅ 合法 DocumentNode # 或使用 gql()（若已安装 graphql-core >= 3.2） # from graphql import gql # document_node = gql(graphql_string)
⚠️ 注意事项：
- 不要对已有 DocumentNode 直接 concat_ast —— 它适用于合并多个含 OperationDefinition 的文档（如多个命名 query），而非“裸 selection set”。
- 若需复用单表查询逻辑，建议封装为函数（如 build_table1_query(...)），返回 Query 对象而非 DocumentNode，便于灵活组合。
- graphql-query 不解析 Schema，仅生成字符串，因此无需连接服务端，适合构建阶段或动态查询场景。
- 如需强类型支持或与 strawberry/ariadne 集成，可基于 graphql.language.ast 手动构造 OperationDefinition 节点，但复杂度显著升高，不推荐初学者采用。
总结：合并命名字段查询的核心在于语义对齐——将多个字段视为同一 query 操作下的并列选择，而非多个独立操作。使用 graphql-query 是兼顾可读性、健壮性与开发效率的最佳实践。
