API 参考文档：@apollo/gateway

本 API 参考文档介绍了从@apollo/gateway包的导出。此包使您能够将Apollo Server用作联邦超级图网关。有关更多信息，请参阅使用 Apollo Server 实现 gateway。

我们建议所有 supergraphs 都使用 GraphOS Router而不是这个基于 Node.js 的网关。请参阅选择路由库。

`class ApolloGateway`

Apollo Server 联邦网关实现的核心类。有关使用 ApolloGateway 的示例，请参阅使用 Apollo Server 实现 gateway。

方法

`构造函数`

返回一个初始化的ApolloGateway实例，您可以将它作为gateway配置选项传递给ApolloServer构造函数，如以下示例所示：

1
const server = new ApolloServer({
2
  gateway: new ApolloGateway({
3
    serviceList: [
4
      // ...
5
    ],
6
  }),
7
});

1
const server = new ApolloServer({
2
  gateway: new ApolloGateway({
3
    serviceList: [
4
      // ...
5
    ],
6
  }),
7
});

接受一个options对象作为参数。以下描述了该对象支持的字段。

示例

提供 `buildService`函数以配置子图检索器

1
const gateway = new ApolloGateway({
2
  serviceList: [
3
    { name: 'products', url: 'https://products-service.dev/graphql' },
4
    { name: 'reviews', url: 'https://reviews-service.dev/graphql' },
5
  ],
6
  introspectionHeaders: {
7
    Authorization: 'Bearer abc123',
8
  },
9
});

1
const gateway = new ApolloGateway({
2
  serviceList: [
3
    { name: 'products', url: 'https://products-service.dev/graphql' },
4
    { name: 'reviews', url: 'https://reviews-service.dev/graphql' },
5
  ],
6

7
  introspectionHeaders: {
8
    Authorization: 'Bearer abc123',
9
  },
10
});

配置管理的联盟.fetcher

如果您向buildService函数提供给ApolloGateway构造函数，则此函数会为您的每个图的子图调用一次。此函数可以返回一个具有自定义fetcher的RemoteGraphQLDataSource，该检索器随后用于所有与子图的通信：

1
const gateway = new ApolloGateway({
2
  buildService({ url, name }) {
3
    return new (class extends RemoteGraphQLDataSource {
4
      fetcher = require('make-fetch-happen').defaults({
5
        onRetry() {
6
          console.log('We will retry!');
7
        },
8
      });
9
    })({
10
      url,
11
      name,
12
    });
13
  },
14
});

1
const gateway = new ApolloGateway({
2
  buildService({ url, name }) {
3
    return new (class extends RemoteGraphQLDataSource {
4
      fetcher = require('make-fetch-happen').defaults({
5
        onRetry() {
6
          console.log('We will retry!');
7
        },
8
      });
9
    })({
10
      url,
11
      name,
12
    });
13
  },
14
});

配置管理的联盟.fetcher

此managed federation配置只配置了您的网关用于从Apollo获取

配置子图检索器

1
const gateway = new ApolloGateway({
2
  fetcher: require('make-fetch-happen').defaults({
3
    onRetry() {
4
      console.log('We will retry!');
5
    },
6
  }),
7
});

1
const gateway = new ApolloGateway({
2
  fetcher: require('make-fetch-happen').defaults({
3
    onRetry() {
4
      console.log('We will retry!');
5
    },
6
  }),
7
});

选项

名称类型	描述
`supergraphSdl` `字符串 \| SupergraphSdlHook \| SupergraphManager`	您可以使用此选项将您的supergraph模式提供给网关。您可以选择将它作为一个`字符串`、通过一个`SupergraphSdlHook`或通过一个`SupergraphManager`。当 `supergraphSdl` 是一个 `字符串` 时：这是由 Rover CLI 生成的supergraph模式（从您的子图模式构建而成。）超级图模式包括指令，用于指定每个子图的路由信息。当 `supergraphSdl` 是一个 `SupergraphSdlHook` 时：这是一个返回包含`supergraphSdl`字符串以及一个`cleanup`函数的对象的`async`函数。钩子接受一个对象，该对象包含以下属性： `update`：一个更新超级图模式的函数 `healthCheck`：一个执行对子图的健壮性检查的函数 `getDataSource`：一个从网关获取特定数据源的函数当 `supergraphSdl` 是一个 `SupergraphManager` 时：一个包含`initialize`属性的`initialize`是一个`async`函数，它的类型与上面直接描述的`SupergraphSdlHook`相同。如果您正在使用托管联邦，请不要提供此字段。如果您没有使用托管联邦，则此字段或`serviceList`为必需。不要同时提供两者。
`serviceList` `Array<ServiceEndpointDefinition>`	此选项已被弃用， favore of the drop-in replacement, `IntrospectAndCompose`。一个对象数组，每个对象都指定了您的联邦图中一个子图的`name`和`url`。在启动时，网关使用此数组通过询问（introspection）和组合一个超级图模式来获取您的子图模式。您可以为此`name`字段指定任何字符串值，这用于在日志输出和错误消息中标识子图，并报告Apollo Studio中的指标。如果您正在使用托管联邦，请不要提供此字段。如果您没有使用托管联邦，则此字段或`supergraphSdl`为必需。不要同时提供两者。
`introspectionHeaders` `对象 \| (服务：ServiceEndpointDefinition) => (Promise`	此选项已被弃用， favore of the drop-in replacement, `IntrospectAndCompose`。一个对象（或一个返回对象的异步函数返回包含网关在向子图发送 introspection 请求时包括的 HTTP 头部的名称和值。仅当发送 introspection 请求时包括。如果您正在使用托管联邦，请不要提供此字段。如果您定义了 `buildService` 函数，请在这函数中指定这些头部，而不是提供此选项。这确保您的 `buildService` 函数不会意外地覆盖您在这里提供的任何头部值。
`debug` `布尔值`	如果为 `true`，则启用开发模式助手和记录所有严重级别（从 `debug` 到 `error`）的消息。如果 `false`，则只有 `warn` 和 `error` 级别的消息将被记录。默认值是 `false`。
`logger` `日志记录器`	用于替代 `console` 的对象。如果提供，此对象必须实现 Logger 接口的所有方法。如果提供了此值，网关将自动记录所有严重级别的消息（从 debug 到 `error`），无论 `debug` 选项是否设置为 `true`。日志记录器负责确定如何处理每个级别的日志。此日志记录器自动添加到所有传递给 Apollo Server 插件函数的 `GraphQLRequestContext` 对象中。
`fetcher` `Fetcher`	指定在从 Apollo 获取配置时用于与 Fetch API 实现使用的托管联邦。默认情况下，网关使用 `make-fetch-happen` 的默认配置。您可以通过设置此字段的值来指定另一个有效的实现（例如 `node-fetch`），将其更改为 `require('node-fetch')`。如上例所示，如果您想覆盖库的默认配置，也可以提供 `make-fetch-happen` 选项。
`服务健康检查` `布尔值`	如果 `true`，网关将在启动时向所有子图发送一个小查询（`{ __typename }`）。如果您在使用托管联邦，则每次实时模式更新时也会这样做。启动时，如果这些请求中的任何一个失败，网关将抛出一个错误。更新模式时，如果这些请求中的任何一个失败，网关将不会切换到新的模式或图配置。网关将在每次轮询间隔重试这些请求，直到成功为止。默认值是 `false`。
`上联端点` `Array<string>`	网关使用这些 Apollo Uplink URL 来轮询其托管的配置的列表。有关详情和默认值，请参阅 Apollo Uplink。仅在您使用托管联邦并且您的特定用例确实需要时，才提供此字段（这很少见）。
`上联最大重试次数` `number`	网关尝试失败轮询请求到达 Apollo Uplink 的最大次数，遍历其列表中的 `uplinkEndpoints`。默认情况下，将尝试每个 uplinkEndpoints 三次（即默认列表中的两个端点，总共 5 次重试）。仅在您使用托管联邦时才提供此字段。
`fallbackPollIntervalInMs`（仅限管理模式） `number`	指定此选项作为 Uplink 无法提供轮询间隔时的后备方案。如果 `fallbackPollIntervalInMs` 大于 Uplink 定义的间隔，此选项也将生效。
`构建服务` `功能`	定义此功能以自定义网关的数据传输到您的某些或全部子图。此自定义可以包括使用除了HTTP以外的协议。有关详细信息，请参阅The `buildService` function。

`buildService函数`

如果您提供了此函数，网关会为每个子图调用一次。此函数必须返回一个实现GraphQLDataSource接口的对象，例如RemoteGraphQLDataSource或其派生类。

以下示例演示了向网关发送到子图的所有请求中添加x-user-id HTTP头来：

1
class AuthenticatedDataSource extends RemoteGraphQLDataSource {
2
  willSendRequest({ request, context }) {
3
    request.http.headers.set('x-user-id', context.userId);
4
  }
5
}
6

7
const gateway = new ApolloGateway({
8
  // ...other options...
9
  buildService({ name, url }) {
10
    return new AuthenticatedDataSource({ url });
11
  },
12
});

1
class AuthenticatedDataSource extends RemoteGraphQLDataSource {
2
  willSendRequest({ request, context }) {
3
    request.http.headers.set('x-user-id', context.userId);
4
  }
5
}
6

7
const gateway = new ApolloGateway({
8
  // ...other options...
9
  buildService({ name, url }) {
10
    return new AuthenticatedDataSource({ url });
11
  },
12
});

`实验选项`

这些选项是实验性的。它们可能会在任何时候被删除或更改，即使在补丁版本中。

名称类型	描述
`experimental_approximateQueryPlanStoreMiB` `number`	设置网关的查询计划存储的近似大小（以 MiB 为单位）。此缓存用于保存查询计划以供后续查询重复使用，这些查询解析到之前观察到的新`queryHash`（传入操作的 SHA-256）。默认值是`30`，通常足以应对，除非服务器处理了大量独特的操作。

`服务健康检查`

当被调用时，网关会向每个子图发送一个小的查询（{ __typename }）以验证其响应性。此函数在失败时抛出异常，并返回一个需要await的 Promise。

`参数`

名称类型	描述
`serviceMap` `Object`（`DataSourceMap`）	如果提供，网关将只向地图中包含的数据源发送健康检查请求。默认情况下，网关使用`this.serviceMap`（即，它向所有已知的子图发送健康检查请求）。

`class RemoteGraphQLDataSource`

表示您的联邦网关与您的子图之一的连接。

您可以通过扩展此类并重写其willSendRequest和/或didReceiveResponse方法来自定义此连接：

覆盖 willSendRequest 以在发送之前修改您的网关对子图的请求。
覆盖 didReceiveResponse 来修改子图的响应，在网关将其传递给请求客户端之前。

以下详细描述了这些方法。

`方法`

`构造函数`

返回一个初始化的 RemoteGraphQLDataSource 实例：

1
const productsDataSource = new RemoteGraphQLDataSource({
2
  url: 'https://products-service.dev/graphql',
3
});

1
const productsDataSource = new RemoteGraphQLDataSource({
2
  url: 'https://products-service.dev/graphql',
3
});

接受一个 options 对象作为参数。以下是该对象的受支持字段：

`选项`

名称类型	描述
`url` `字符串`	必需。子图的 URL，用于通过 HTTP 发送获取请求。
`apq` `布尔值`	如果 `true`，网关在发送查询到此子图时尝试使用自动持久查询 (APQ)。 APQ 可以显著减少通过网络发送的请求大小，特别是对于更复杂的查询。此外，子图必须启用对 APQ 的支持，网关才能使用此功能（Apollo Server 默认启用 APQ）。

`willSendRequest`

在子类中覆盖此方法，以在发送到子图的每个获取请求之前对其进行修改：

1
// Adds an `x-user-id` header to each outgoing fetch request
2
class AuthenticatedDataSource extends RemoteGraphQLDataSource {
3
  willSendRequest({ request, context }) {
4
    request.http.headers.set('x-user-id', context.userId);
5
  }
6
}

1
// Adds an `x-user-id` header to each outgoing fetch request
2
class AuthenticatedDataSource extends RemoteGraphQLDataSource {
3
  willSendRequest({ request, context }) {
4
    request.http.headers.set('x-user-id', context.userId);
5
  }
6
}

此方法接收一个 requestContext 对象，该对象包含原始未修改的 request 以及当前的 context 对象（即 contextValue 对象）。

`didReceiveResponse`

在子类中覆盖此方法，以自定义网关完成对子图的获取后的行为，但在发送响应到请求客户端之前：

1
class CookieDataSource extends RemoteGraphQLDataSource {
2
  didReceiveResponse({ response, request, context }) {
3
    const cookie = request.http.headers.get('Cookie');
4
    if (cookie) {
5
      context.responseCookies.push(cookie);
6
    }
7

8
    // Return the response, even when unchanged.
9
    return response;
10
  }
11
}

1
class CookieDataSource extends RemoteGraphQLDataSource {
2
  didReceiveResponse({ response, request, context }) {
3
    const cookie = request.http.headers.get('Cookie');
4
    if (cookie) {
5
      context.responseCookies.push(cookie);
6
    }
7

8
    // Return the response, even when unchanged.
9
    return response;
10
  }
11
}

此方法接收一个 requestContext 对象，其中包含：

子图的 response
网关对子图的 request
当前操作的 context

这使得您能够修改操作的 contextValue 和获取响应的任何组合。

请求和响应对象的 http 属性包含额外的 HTTP 特定属性，例如 headers。

此方法必须返回一个与GraphQLResponseGraphQLResponse结构匹配的对象

`didEncounterError`

在子类中重写此方法以自定义网关在与其子图或解析其响应（例如，如果响应不是良好的JSON格式）通信时遇到错误后的行为

如果不重写此方法，则默认实现throw抛出错误，如下所示：

1
class MyDataSource extends RemoteGraphQLDataSource {
2
  didEncounterError(error, fetchRequest, fetchResponse, context) {
3
    throw error;
4
  }
5
}

1
class MyDataSource extends RemoteGraphQLDataSource {
2
  didEncounterError(error, fetchRequest, fetchResponse, context) {
3
    throw error;
4
  }
5
}

注意，如果您在这个方法中不抛出error（或者不同的Error）error将在此方法返回后立即抛出。

此方法接受以下位置参数

名称类型	描述
`error` `Error`	通信过程中发生的错误。
`fetchRequest` `Request`	发送到子图的`fetch`请求的细节。
`fetchResponse` `Response`	由子图发送的`fetch`响应的细节。
`context` `TContext`	The `contextValue` object传递给操作GraphQL的resolvers。

`class IntrospectAndCompose`

⚠️ 我们强烈建议不要在生产环境中使用IntrospectAndCompose。有关详情，请参阅《IntrospectAndCompose限制》。

IntrospectAndCompose是用于从子图SDL检索并组合成supergraph的开发工具，用于您的网关。IntrospectAndCompose将根据其子图及其URL列表发出查询，IntrospectAndCompose将它们组合成supergraph，并为此supergraph提供网关。IntrospectAndCompose还可以配置为通过轮询进行更新并执行子图健康检查，以确保supergraph安全更新。IntrospectAndCompose实现SupergraphManager接口，并将其传递给ApolloGateway构造函数的supergraphSdl选项。

IntrospectAndCompose是serviceList的替代品。

`方法`

`构造函数`

返回一个初始化的IntrospectAndCompose实例，然后您可以将该实例传递给ApolloGateway构造函数的supergraphSdl配置选项，如下所示：

1
const server = new ApolloServer({
2
  gateway: new ApolloGateway({
3
    supergraphSdl: new IntrospectAndCompose({
4
      subgraphs: [
5
        // ...
6
      ],
7
    }),
8
  }),
9
});

1
const server = new ApolloServer({
2
  gateway: new ApolloGateway({
3
    supergraphSdl: new IntrospectAndCompose({
4
      subgraphs: [
5
        // ...
6
      ],
7
    }),
8
  }),
9
});

接受一个 options 对象作为参数。此对象的受支持属性描述如下。

`示例`

`提供 subgraphs 列表和头信息以授权检查。`

1
const gateway = new ApolloGateway({
2
  supergraphSdl: new IntrospectAndCompose({
3
    subgraphs: [
4
      { name: 'products', url: 'https://products-service.dev/graphql' },
5
      { name: 'reviews', url: 'https://reviews-service.dev/graphql' },
6
    ],
7
    introspectionHeaders: {
8
      Authorization: 'Bearer abc123',
9
    },
10
  }),
11
});

1
const gateway = new ApolloGateway({
2
  supergraphSdl: new IntrospectAndCompose({
3
    subgraphs: [
4
      { name: 'products', url: 'https://products-service.dev/graphql' },
5
      { name: 'reviews', url: 'https://reviews-service.dev/graphql' },
6
    ],
7

8
    introspectionHeaders: {
9
      Authorization: 'Bearer abc123',
10
    },
11
  }),
12
});

`配置管理的联盟.fetcher`

IntrospectAndCompose 使用由 ApolloGateway 构造的数据源。要自定义网关的数据源，您可以将 buildService 函数传递给 ApolloGateway 构造函数。在下面的示例中，IntrospectAndCompose 通过网关的 buildService 函数中构造的 AuthenticatedDataSource 进行受认证的请求，来访问子图。

1
const gateway = new ApolloGateway({
2
  buildService({ name, url }) {
3
    return new AuthenticatedDataSource({ url });
4
  },
5
  supergraphSdl: new IntrospectAndCompose({
6
    subgraphs: [
7
      { name: 'products', url: 'https://products-service.dev/graphql' },
8
      { name: 'reviews', url: 'https://reviews-service.dev/graphql' },
9
    ],
10
  }),
11
});

1
const gateway = new ApolloGateway({
2
  buildService({ name, url }) {
3
    return new AuthenticatedDataSource({ url });
4
  },
5
  supergraphSdl: new IntrospectAndCompose({
6
    subgraphs: [
7
      { name: 'products', url: 'https://products-service.dev/graphql' },
8
      { name: 'reviews', url: 'https://reviews-service.dev/graphql' },
9
    ],
10
  }),
11
});

`选项`

名称类型	描述
`subgraphs` `Array<ServiceEndpointDefinition>`	一个对象数组，每个对象指定了在您的联邦图中一个子图 `name` 和 `url`。在启动时，`IntrospectAndCompose` 使用此数组通过检查来获取您的子图模式，并构建一个 superschema 模式。 `name` 字段是一个字符串，应被视为子图的唯一标识符。它用于查询计划、日志记录以及将度量报告给 Apollo Studio。对于 Studio 用户，子图名称必须：以字母开头（大写或小写）只包含字母、数字、下划线（_）和连字符（-）最大长度为 64 个字符
`introspectionHeaders` `对象 \| (服务：ServiceEndpointDefinition) => (Promise`	一个对象（或者一个返回对象的可选异步函数），其中包含网关在向您的子图发出检查请求时包含的 HTTP 头的名称和值。如果您在 `ApolloGateway` 配置中定义了一个 `buildService` 函数，在这些头信息中将指定这些头，而不是提供此选项。这确保了您的 `buildService` 函数不会意外地覆盖此处提供的任何头信息的值。
`pollIntervalInMs` `number`	指定此选项以启用通过子图轮询的 superschema 更新。 `IntrospectAndCompose` 在指定的时间间隔内轮询每个子图。
`subgraphHealthCheck` `布尔值`	此选项仅适用于通过 `pollIntervalInMs` 选项配置轮询的子图。如果 `true`，则在执行 superschema 更新之前，网关会对每个子图执行健康检查。健康检查期间出现的错误将导致跳过 superschema 更新，但轮询将继续。健康检查是一个简单的 `GraphQL` 查询 `query __ApolloServiceHealthCheck__ { __typename }`) 以确保子图可访问并能成功响应对 GraphQL 的请求。此选项是 `IntrospectAndCompose` 对 `ApolloGateway` 的 `serviceHealthCheck` 选项的等效项。如果您使用 `IntrospectAndCompose`，在您的 `ApolloGateway` 实例上启用 `serviceHealthCheck` 无任何影响。
`logger` `Logger`	用于替代 `console` 的对象。如果提供，此对象必须实现 Logger 接口的所有方法。 `IntrospectAndCompose` 不与它配置的 `ApolloGateway` 使用相同的日志记录器。在大多数情况下，你可能希望将相同的日志记录器传递给 `ApolloGateway` 和 `IntrospectAndCompose`。

上一页
设置

API 参考文档：@apollo/gateway

提供buildService函数以配置子图检索器

提供 `buildService`函数以配置子图检索器