操作请求格式

默认情况下，几乎每个 GraphQL IDE和客户端库会处理以Apollo Server支持的格式发送的操作。本文将描述该格式，该格式也描述在graphql.org和这个初步规范中。

Apollo Server接受通过POST请求发送的查询和mutations。

POST请求

Apollo Server接受POST请求，其中包含JSON主体。一个有效的请求包含一个query字段，以及可选的variables、extensions和operationName（如果请求包含多个可能的操作，可以明确指定要运行的query）。您必须指定类型为application/json的Content-TypeHTTP头。

假设我们想执行以下query：

1
query GetBestSellers($category: ProductCategory) {
2
  bestSellers(category: $category) {
3
    title
4
  }
5
}

以下是一个有效POST请求体示例:

1
{
2
  "query": "query GetBestSellers($category: ProductCategory){bestSellers(category: $category){title}}",
3
  "operationName": "GetBestSellers",
4
  "variables": { "category": "BOOKS" }
5
}

请注意，operationName对于这个特定的请求体不是必需的，因为query中只包含一个操作定义。

您现在可以使用以下curl命令来执行此查询

1
curl --request POST \
2
  -H 'Content-Type: application/json' \
3
  --data '{"query":"query GetBestSellers($category: ProductCategory){bestSellers(category: $category){title}}", "operationName":"GetBestSellers", "variables":{"category":"BOOKS"}}' \
4
  https://rover.apollo.dev/quickstart/products/graphql

Apollo Server的默认生产登陆页面提供了一个's default production landing page provides a curl命令，您可以使用此命令在您的服务器上执行测试查询：

批处理

默认情况下，Apollo Server 4不支持HTTP批处理请求。要启用HTTP批处理，您必须显式地将allowBatchedHttpRequests: true传递到ApolloServer构造函数。

如果您已启用HTTP批处理，您可以通过提供一个JSON编码的查询对象数组，通过单个POST请求发送一批查询，如下所示：

1
[
2
  {
3
    "query": "query { testString }"
4
  },
5
  {
6
    "query": "query AnotherQuery{ test(who: \"you\" ) }"
7
  }
8
]

如果您发送批处理请求，Apollo Server将返回相应的GraphQL响应数组。

GET请求

Apollo Server也接受查询的GET请求（但不是mutations）。通过GET请求，将查询详细信息（query、operationName、variables）作为URL查询参数提供。variables选项是一个URL编码的JSON对象。

以下是与POST请求格式相同的查询，格式化用于curl GET请求：

1
curl --request GET \
2
  https://rover.apollo.dev/quickstart/products/graphql?query=query%20GetBestSellers%28%24category%3A%20ProductCategory%29%7BbestSellers%28category%3A%20%24category%29%7Btitle%7D%7D&operationName=GetBestSellers&variables=%7B%22category%22%3A%22BOOKS%22%7D

与POST请求不同，GET请求不需要Content-Type头。但是，如果您已启用Apollo Server 4的默认CSRF预防功能，则不包含Content-Type头部的GET请求必须包含以下之一：

• 一个非空的X-Apollo-Operation-Name头
• 一个非空的Apollo-Require-Preflight头

有关更多详细信息，请参阅CSRF预防文档。

增量交付（实验性）

增量交付是 第二阶段：草案提案 GraphQL 规范的一部分，它添加了 @defer 和 @stream 可执行指令。这些指令允许客户端指定操作的一部分可以在初始响应之后发送，这样较慢的 字段 就不会延迟其他字段。截至 2022 年 9 月，基于 Apollo Server 的 construction 的 graphql 库（也称为 graphql-js）只在尚未发布的重大版本 17 中实现增量交付。如果在您的服务器中安装了 [email protected] 的预发布版，Apollo Server 4 可以执行这些增量交付指令并提供 multipart/mixed 响应。

在 graphql 版本 17 中对增量交付的支持是 主动选择 的，这意味着指令默认没有定义。为了使用 @defer 或 @stream，您必须在您的 SDL 中提供适当的定义。下面的定义可以直接粘贴到您的模式中：

1
directive @defer(if: Boolean, label: String) on FRAGMENT_SPREAD | INLINE_FRAGMENT
2
directive @stream(if: Boolean, label: String, initialCount: Int = 0) on FIELD

如果您自己创建模式对象，必须按照以下方式提供适当的 指令（s）给模式构造函数：

1
import {
2
  GraphQLSchema,
3
  GraphQLDeferDirective,
4
  GraphQLStreamDirective,
5
  specifiedDirectives,
6
} from 'graphql';
7

8
const schema = new GraphQLSchema({
9
  query,
10
  directives: [
11
    ...specifiedDirectives,
12
    GraphQLDeferDirective,
13
    GraphQLStreamDirective,
14
  ],
15
});

发送包含增量交付指令的操作的客户端需要明确表示他们期待接收到multipart/mixed格式响应。此外，由于增量交付尚未在GraphQL规范中确定，并且可能在最终版本之前发生变化，他们需要通过deferSpec参数指定期望Apollo Server当前生成的特定响应格式。具体来说，准备好接受增量交付响应的客户端应发送一个类似以下accept的报头：multipart/mixed; deferSpec=20220824。请注意，此报头意味着仅接受多部分响应；通常，客户端会发送类似以下multipart/mixed; deferSpec=20220824, application/json的报头，表示接受多部分或单部分响应。

在同一请求中不能将批处理与增量交付结合使用。