HTTP 链接

使用 HTTP 获取 GraphQL 结果。

建议阅读Apollo 链接概述在学习个别链接之前。

HttpLink 是一个终止链接，它通过 HTTP 将 GraphQL 操作发送到远程端点。Apollo Client 默认使用 HttpLink，当您向 ApolloClient 构造函数提供 uri 选项时。

HttpLink 支持POST和GET请求，并且可以在每个操作级别上配置HTTP选项。您可以使用这些选项进行身份验证、持久化查询、动态URI和其他细粒度更新。

用法

导入 HttpLink 类并初始化链接如下：

1
import { HttpLink } from '@apollo/client';
2

3
const link = new HttpLink({
4
  uri: "https://127.0.0.1:4000/graphql"
5
  // Additional options
6
});

`HttpLink` 构造函数选项

该 HttpLink 构造函数接受一个选项对象，该对象可以包括以下字段。请注意，您还可以使用操作上下文在每个操作的基础上覆盖这些选项。

名称类型	描述
`uri` `String` 或 `Function`	要发送请求的 GraphQL 端点的 URL。也可以是一个函数，该函数接受一个 `Operation` 对象并返回用于该操作的字字符串 URL。默认值为 `/graphql`。
`includeExtensions` `布尔值`	如果为真，则在发送到您的 GraphQL 端点的操作中包含 `extensions` 字段。默认值为 `false`。
`fetch` `函数`	发送 HTTP 请求到您的 GraphQL 端点时，而不是直接调用 Fetch API 时使用函数。此函数必须符合 `fetch` 的签名。默认情况下，如果您的运行环境不可用，则使用 Fetch API。请参阅自定义 `fetch`。
`headers` `对象`	表示包含在每个 HTTP 请求中的头部的对象，如 `{Authorization: 'Bearer abc123'}`。
`preserveHeaderCase` `布尔值`	如果设置为 true，则头部名称不会自动转换为小写。这允许非 http-spec-compliant 服务器，这些服务器可能期望使用大写名称的头部。默认值为 `false`。
`credentials` `字符串`	为每个 `fetch` 调用使用的凭据策略。可以是 `omit`、`include` 或 `same-origin`。
`fetchOptions` `对象`	包含用于每个 `fetch` 调用的选项的对象。如果此对象中未包含特定选项，则默认值将用于该选项。请注意，如果您将 `fetchOptions.method` 设置为 `GET`， `HttpLink` 将遵循标准的 GraphQL HTTP GET 编码。查看可用选项
`useGETForQueries` `布尔值`	如果 `true`，链接在向您的 GraphQL 端点发送查询操作时使用 HTTP GET 请求。变体操作仍然使用 `POST` 请求。如果您想所有操作都使用 `GET` 请求，请设置 `fetchOptions.method`。默认值为 `false`。
`print` `函数`	一个可选的函数，用于将查询或变体转换为字符串。它接受一个 `ASTNode`（通常是一个 `DocumentNode`），以及原始的 `print` 函数作为参数，并期望返回一个字符串。此选项可以与 `stripIgnoredCharacters` 一起使用，以删除查询中的空白字符。 import { stripIgnoredCharacters } from 'graphql'; const httpLink = new HttpLink({ uri: '/graphql', print: (ast, originalPrint) => stripIgnoredCharacters(originalPrint(ast)), }); 默认情况下，使用裸露的 GraphQL `print` 函数。

上下文选项

HttpLink在向您的 GraphQL 端点发送请求之前检查当前操作的 context 中的某些值。先前链接链中的链接可以设置这些值以自定义 HttpLink 对每个操作的行为。

其中一些值也可以作为选项提供给 HttpLink 构造函数。如果两个都提供了值，则 context 中的值优先。

名称类型	描述
`uri` `String` 或 `Function`	要发送请求的 GraphQL 端点的 URL。也可以是一个函数，该函数接受一个 `Operation` 对象并返回用于该操作的字字符串 URL。默认值为 `/graphql`。
`headers` `对象`	代表要在 HTTP 请求中包含的标题的对象，例如 `{Authorization: 'Bearer abc123'}`。
`credentials` `字符串`	为此 `fetch` 调用应用的凭据策略。可以是 `omit`， `include`，或 `same-origin`。
`fetchOptions` `对象`	一个对象，包含用于调用 `fetch` 的选项。如果该对象中不包含特定选项，将使用该选项的默认值。请注意，如果您将 `fetchOptions.method` 设置为 `GET`， `HttpLink` 将遵循标准的 GraphQL HTTP GET 编码。查看可用选项
`http` `对象`	一个对象，配置高级 `HttpLink` 功能，例如对持久化查询的支持。选项列在 `http` 选项字段。

`http` 选项字段

名称类型	描述
`includeExtensions` `布尔值`	如果为真，会在发送到你的 GraphQL 终端的操作中包含 `extensions` 字段。默认值为 `false`。
`includeQuery` `布尔值`	如果为 `false`，则不会在请求中包含 GraphQL 查询字符串。如果你正在发送使用持久化查询的请求，请设置此选项。默认值是 `true`。
`preserveHeaderCase` `布尔值`	如果设置为 true，则头部名称不会自动转换为小写。这允许非 http-spec-compliant 服务器，这些服务器可能期望使用大写名称的头部。默认值为 `false`。

操作结果

在你的 GraphQL 终端（成功）响应了发送的操作的结果后， HttpLink 将其设置为操作 context 的 response 字段。这允许链中的每个前置链接在响应返回之前与之交互。

处理错误

HttpLink 区分客户端错误、服务器错误和 GraphQL 错误。你可以将 onError 链接添加到你的链接链中，通过回调处理这些错误。

以下类型的错误可能发生

Error	描述	回调	Error 类型
Client Parse	请求正文不可序列化，例如由于循环引用。	`error`	`ClientParseError`
Server Parse	服务器响应无法解析（response.json()）	`error`	`ServerParseError`
Server Network	服务器响应该非 2xx 的 HTTP 状态码。	`error`	`ServerError`
Server Data	服务器响应中没有包含 `data` 或 `errors`。	`error`	`ServerError`
GraphQL Error	解析 GraphQL 操作至少出现一个错误，它出现在 `errors` 字段中。	`next`	`对象`

因为许多服务器实现可以在服务器网络错误时返回有效的 GraphQL 结果，因此抛出的 Error 对象包含了解析后的服务器结果。服务器数据错误也会接收到解析后的结果。

所有错误类型都继承了从泛型javascript Error 对象继承的 name、 message 和 nullable stack 属性。

1
//type ClientParseError
2
{
3
  parseError: Error;                // Error returned from response.json()
4
};
5

6
//type ServerParseError
7
{
8
  response: Response;               // Object returned from fetch()
9
  statusCode: number;               // HTTP status code
10
  bodyText: string                  // text that was returned from server
11
};
12

13
//type ServerError
14
{
15
  result: Record<string, any>;      // Parsed object from server response
16
  response: Response;               // Object returned from fetch()
17
  statusCode: number;               // HTTP status code
18
};

自定义 `fetch`

您可以将 fetch 选项提供给 HttpLink 构造函数以启用许多自定义网络需求。例如，您可以根据计算得到的头部信息修改请求，或者基于操作's 的详细信息计算端点 URI。

如果您针对的环境不支持 Fetch API（例如旧版本的浏览器或服务器）您可以根据需要提供不同的 fetch 实现。我们建议对旧版本的浏览器使用 unfetch，在 Node 中运行时使用 node-fetch。

自定义认证

此示例在调用 fetch 之前向每个请求添加自定义的 Authorization 头部：

1
const customFetch = (uri, options) => {
2
  const { header } = Hawk.client.header(
3
    "http://example.com:8000/resource/1?b=1&a=2",
4
    "POST",
5
    { credentials: credentials, ext: "some-app-data" }
6
  );
7
  options.headers.Authorization = header;
8
  return fetch(uri, options);
9
};
10

11
const link = new HttpLink({ fetch: customFetch });

动态 URI

此示例在调用 fetch 之前自定义端点 URL 的查询参数：

1
const customFetch = (uri, options) => {
2
  const { operationName } = JSON.parse(options.body);
3
  return fetch(`${uri}/graph/graphql?opname=${operationName}`, options);
4
};
5

6
const link = new HttpLink({ fetch: customFetch });

概览

HTTP批处理

HTTP 链接

使用 HTTP 获取 GraphQL 结果。

用法

`HttpLink` 构造函数选项

`uri`

`includeExtensions`

`fetch`

`headers`

`preserveHeaderCase`

`credentials`

`fetchOptions`

`useGETForQueries`

`print`