本文介绍如何将多个独立的、含命名别名（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 最佳实践，也是性能与可维护性的双重保障。
