查询批处理

使用 GraphOS Router 接收查询批次

此功能仅在 GraphOS 企业计划中可用.
您可以通过注册免费账户来测试它。企业试用版.

了解关于查询批处理和如何配置GraphOS 路由器以接收查询批处理。

关于查询批处理

现代应用程序通常需要多个请求来渲染单个页面。这通常是组件化架构的结果，其中单独的微前端(MFE)分别发出请求以获取与其相关的数据。这不仅会导致性能开销——不同的组件可能请求相同的数据——还可能导致一致性问题。为了解决这个问题，基于MFE的用户界面将多个彼此紧密相连的客户操作组合成一个单独的HTTP请求。这在Apollo 客户端和Apollo 服务器中得到支持。

路由器的批处理支持通过两组功能提供：

客户端批处理
子图批处理

在客户端批处理中，路由器从客户端接收批处理请求，并单独处理批处理中的每个请求。因此，路由器以批量形式向子图呈现请求，因此子图必须单独处理批处理请求。

在子图批处理中，路由器分析输入客户端批处理请求并向子图发出批处理请求。子图批处理是客户端批处理的扩展，需要参与的子图支持批处理请求。以下是说明如何在实践中工作的示例。

GraphOS 路由器支持客户端和子图查询批处理。

如果您使用的是Apollo 客户端，则可以利用内置的批处理支持来减少发送到路由器的单独操作的数量。

配置后，Apollo 客户端将自动将多个操作组合成一个单独的HTTP请求。批次内的操作数量由客户端配置，包括批次中的最大数量和等待操作累积发送批次的最大持续时间。

GraphOS 路由器必须配置为接收查询批次，否则它将拒绝它们。在处理批处理时，路由器将单独反序列化和处理批处理中的每个操作。仅在批次中的所有操作都完成后，才对客户端做出响应。每个操作与其他批处理中的操作并发执行。

router.yaml

1
batching:
2
  enabled: true
3
  mode: batch_http_link

属性	描述	有效值	默认值
`enabled`	启用接收客户端查询批次的标志	布尔类型	`false`
`mode`	支持客户端批量模式	`batch_http_link`：客户端使用 Apollo Link 及其 `BatchHttpLink` 连接。	无默认值

子图查询批量处理

如果启用客户端查询批量处理，并且路由器的子图支持查询批量处理，则可以通过设置以下字段在您的router.yaml配置文件中启用子图查询批量处理：

router.all_enabled.yaml

1
batching:
2
  enabled: true
3
  mode: batch_http_link
4
  subgraph:
5
    # Enable batching on all subgraphs
6
    all:
7
      enabled: true

router.yaml

1
batching:
2
  enabled: true
3
  mode: batch_http_link
4
  subgraph:
5
    # Disable batching on all subgraphs
6
    all:
7
      enabled: false
8
    # Configure(over-ride) batching support per subgraph
9
    subgraphs:
10
      subgraph_1:
11
        enabled: true
12
      subgraph_2:
13
        enabled: true

ⓘ 注意

路由器可以被配置为支持所有子图的批量处理或为每个子图单独启用。
路由器从客户端请求中保留批量到子图请求的能力有限。特别是，某些形式的查询在处理之前需要存在数据。因此，路由器只能从不需要这种约束的查询生成批次。这可能导致路由器发布多个批次或请求。
如果启用了查询去重或实体缓存，它们将不会应用于批量查询。批量处理将优于查询去重和实体缓存。对于非批量查询，仍将执行查询去重和实体缓存。

示例：简单的子图批量处理

此示例显示路由器如何在查询批次中不包含必需的获取约束的最多效场景中对子图请求进行批量处理。

假设联邦的图包含三个子图accounts，products和reviews。

输入客户端查询到联盟图：

simple-batch.json

1
[
2
    {"query":"query MeQuery1 {\n  me {\n    id\n }\n}"}
3
    {"query":"query MeQuery2 {\n  me {\n    name\n }\n}"},
4
    {"query":"query MeQuery3 {\n  me {\n    id\n }\n}"}
5
    {"query":"query MeQuery4 {\n  me {\n    name\n }\n}"},
6
    {"query":"query MeQuery5 {\n  me {\n    id\n }\n}"}
7
    {"query":"query MeQuery6 {\n  me {\n    name\n }\n}"},
8
    {"query":"query MeQuery7 {\n  me {\n    id\n }\n}"}
9
    {"query":"query MeQuery8 {\n  me {\n    name\n }\n}"},
10
    {"query":"query MeQuery9 {\n  me {\n    id\n }\n}"}
11
    {"query":"query MeQuery10 {\n  me {\n    name\n }\n}"},
12
    {"query":"query MeQuery11 {\n  me {\n    id\n }\n}"}
13
    {"query":"query MeQuery12 {\n  me {\n    name\n }\n}"},
14
    {"query":"query MeQuery13 {\n  me {\n    id\n }\n}"}
15
    {"query":"query MeQuery14 {\n  me {\n    name\n }\n}"},
16
    {"query":"query MeQuery15 {\n  me {\n    id\n }\n}"}
17
]

从输入查询中，路由器生成了一个子图查询集：

1
"query MeQuery1__accounts__0{me{id}}",
2
"query MeQuery2__accounts__0{me{name}}",
3
"query MeQuery3__accounts__0{me{id}}",
4
"query MeQuery4__accounts__0{me{name}}",
5
"query MeQuery5__accounts__0{me{id}}",
6
"query MeQuery6__accounts__0{me{name}}",
7
"query MeQuery7__accounts__0{me{id}}",
8
"query MeQuery8__accounts__0{me{name}}",
9
"query MeQuery9__accounts__0{me{id}}",
10
"query MeQuery10__accounts__0{me{name}}",
11
"query MeQuery11__accounts__0{me{id}}",
12
"query MeQuery12__accounts__0{me{name}}",
13
"query MeQuery13__accounts__0{me{id}}",
14
"query MeQuery14__accounts__0{me{name}}",
15
"query MeQuery15__accounts__0{me{id}}",

所有的查询可以合并成一个批次。因此，而不是15个（非批量）子图获取操作，路由器只需要进行一次获取。

子图	获取次数（无）	获取次数（有）
账户	15	1

示例：复杂的子图批量处理

此示例展示了路由器如何批量处理某图中的子图请求，其中客户端批次包含对一个查询的实体。

假设联盟图包含三个子图： accounts、products和reviews。

输入客户端查询到联盟图：

federated-batch.json

1
[
2
    {"query":"query MeQuery1 {\n  me {\n    id\n }\n}"},
3
    {"query":"query MeQuery2 {\n  me {\n    reviews {\n      body\n    }\n  }\n}"},
4
    {"query":"query MeQuery3 {\n  topProducts {\n    upc\n    reviews {\n      author {\n        name\n      }\n    }\n  }\n  me {\n    name\n  }\n}"},
5
    {"query":"query MeQuery4 {\n  me {\n    name\n }\n}"},
6
    {"query":"query MeQuery5 {\n  me {\n    id\n }\n}"}
7
]

从输入查询中，路由器生成了一个子图查询集：

1
"query MeQuery1__accounts__0{me{id}}",
2
"query MeQuery2__accounts__0{me{__typename id}}",
3
"query MeQuery3__products__0{topProducts{__typename upc}}",
4
"query MeQuery3__accounts__3{me{name}}",
5
"query MeQuery4__accounts__0{me{name}}",
6
"query MeQuery5__accounts__0{me{id}}",
7
"query MeQuery2__reviews__1($representations:[_Any!]!){_entities(representations:$representations){...on User{reviews{body}}}}",
8
"query MeQuery3__reviews__1($representations:[_Any!]!){_entities(representations:$representations){...on Product{reviews{author{__typename id}}}}}",
9
"query MeQuery3__accounts__2($representations:[_Any!]!){_entities(representations:$representations){...on User{name}}}",

前六个查询可以合并成两个批次——一个用于 accounts，一个用于products。它们必须先获取，才能单独执行最后的三个查询。

总的来看，没有子图批处理后，路由器在三个子图上总共进行9次获取，但有了子图批处理后，总数减少到5次。

子图	获取次数（无）	获取次数（有）
账户	6	2
products	1	1
reviews	2	2

名称	属性	描述
`apollo.router.operations.batching`	模式 [subgraph]	接收（来自客户端）或派发（到子图）批量的计数器。
`apollo.router.operations.batching.size`	模式 [subgraph]	接收批量大小的直方图。

如果存在 subgraph 属性，则是可选的。如果不存在该属性，则指标标识来自客户端的批量。如果存在该属性，则指标标识发送到特定 subgraph 的批量。

查询批量格式

请求格式

查询批量是一系列的 operations 数组。

1
[
2
query MyFirstQuery {
3
  me {
4
    id
5
  }
6
},
7
query MySecondQuery {
8
  me {
9
    name
10
  }
11
}
12
]

响应格式

响应以 JSON 数组形式提供，其中响应顺序与查询批量中操作的顺序相匹配。

1
[
2
  {"data":{"me":{"id":"1"}}},
3
  {"data":{"me":{"name":"Ada Lovelace"}}}
4
]

查询批量的错误处理

批量错误

如果无法处理查询批量，则整个批量会失败。

例如，此批量请求是无效的，因为它有两个逗号分隔构成查询。

1
[
2
query MyFirstQuery {
3
  me {
4
    id
5
  }
6
},,
7
query MySecondQuery {
8
  me {
9
    name
10
  }
11
}
12
]

因此，路由器返回一个无效批量错误：

1
{"errors":
2
  [
3
    {"message":"Invalid GraphQL request","extensions":{"details":"failed to deserialize the request body into JSON: expected value at line 1 column 54","code":"INVALID_GRAPHQL_REQUEST"}}
4
  ]
5
}

单个查询错误

如果在批量中单个查询无法处理，这将导致单个错误。

例如，查询 MyFirstQuery 访问一个不存在的字段，而其余的批处理查询是有效的。

1
[
2
query MyFirstQuery {
3
  me {
4
    thisfielddoesnotexist
5
  }
6
},
7
query MySecondQuery {
8
  me {
9
    name
10
  }
11
}
12
]

因此，对单个无效查询返回一个错误，而其他（有效）查询返回一个响应。

1
[
2
  {"errors":
3
    [
4
      {"message":"cannot query field 'thisfielddoesnotexist' on type 'User'",
5
       "extensions":{"type":"User","field":"thisfielddoesnotexist","code":"INVALID_FIELD"}
6
      }
7
    ]
8
  },
9
  {"data":{"me":{"name":"Ada Lovelace"}}}
10
]

已知限制

不支持的查询模式

启用批量处理时，任何导致响应流的结果的批量操作都不受支持，包括：

请求格式

订阅设置

查询批处理

使用 GraphOS Router 接收查询批次

关于查询批处理

配置客户端查询批处理

配置路由器

客户端查询批处理

子图查询批量处理

示例：简单的子图批量处理

示例：复杂的子图批量处理

配置客户端

配置兼容性

查询批量的指标

`apollo.router.operations.batching`

`apollo.router.operations.batching.size`

查询批量格式

请求格式

响应格式

查询批量的错误处理

批量错误

单个查询错误

已知限制

不支持的查询模式