本文介绍如何将多个独立的、含命名别名（alias）的 graphql 查询 documentnode 合并为一个合法的单文档 documentnode，避免 `anonymous operation must be only defined operation` 错误，并提供基于 `graphql-query` 的可维护、类型友好、符合 graphql 规范的 python 实现方案。

在 GraphQL 开发中，常需将多个查询（如按模块或数据表拆分的 fetchTable1、fetchTable2）合并为一个请求以减少网络往返。但直接使用 graphql.language.concat_ast() 合并多个 DocumentNode 会导致语法错误——因为该函数会将每个子查询视为独立的匿名操作（即用 {...} 包裹），而 GraphQL 规范明确禁止在一个文档中存在多个匿名操作。

正确的合并方式是：所有字段必须位于同一个顶层操作（如 query { ... }）内，且每个字段可带别名（如 table1: fetchTable1(...)）。这本质上不是“合并多个操作”，而是“构建一个包含多个字段的单一操作”。

推荐使用 graphql-query 库（轻量、无运行时依赖、纯 Python 构建 AST）替代底层拼接。它通过声明式 API 构建符合规范的查询字符串，再交由 graphql-core 的 gql() 解析为 DocumentNode：

from graphql_query import Argument, Field, Operation, Query
from graphql import parse  # 或 from gql import gql

# 定义带别名的独立查询字段
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"])]
)

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 操作（非多个 operation）
operation = Operation(
    type="query",
    queries=[fetchTable1, fetchTable2],  # 注意：此处是字段列表，非多个 DocumentNode
)

# 生成标准 GraphQL 字符串
graphql_string = operation.render()
print(graphql_string)
# 输出即为目标格式：query { table1: ... table2: ... }

# 转为 DocumentNode（供 graphql-core 或 gql 执行）
document_node = parse(graphql_string)  # 或 gql(graphql_string)

✅ 关键要点：

• Operation(queries=[...]) 生成的是一个 query { ... } 块，内部字段自动并列，支持别名与嵌套；
• 每个 Query 对象代表一个字段级子查询（非独立 operation），因此天然规避了多 operation 限制；
• 支持复用：同一 Query 实例可在不同 Operation 中重复使用（如分页场景），也可单独渲染用于调试；
• 兼容性好：输出为标准 GraphQL SDL 字符串，可无缝接入 gql, ariadne, graphql-core 等生态。

⚠️ 注意事项：

• 避免混合使用 concat_ast 与手动字符串拼接——易引入语法错误且难以调试；
• 若需动态增删字段，建议封装 Query 工厂函数（如 make_table_query(table_name, args)）；
• 对于 mutation 或 subscription，只需将 Operation(type="query") 改为 "mutation" 或 "subscription" 即可，API 一致。

综上，与其尝试“合并多个 DocumentNode”，不如从设计源头采用单操作 + 多字段 + 别名模式——这既是 GraphQL 最佳实践，也是性能与可维护性的双重保障。