如何在 GraphQL 中正确合并多个命名操作的 DocumentNode

本文介绍如何将多个带有命名操作（如别名字段）的 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 是兼顾可读性、健壮性与开发效率的最佳实践。