网关迁移指南

了解如何迁移...超级图 使用 @apollo/gateway 库迁移到 GraphOS 路由器 或 Apollo 路由器核心 因此在保持子图不变的条件下可以获得显著性能提升。

有什么不同？

与 @apollo/gateway 是一个 npm 库不同，路由器 集成为一个 静态独立二进制文件。

路由器通过声明性配置公开最常用的关键特征。您可以使用 YAML 配置文件

尽管 可以 下载 Apollo Router Core 源代码并将其作为库在更大的项目中使用，并作为自托管 GraphOS 路由器的基础，但您可能不需要这样做，因为通过在代码中实现的特性可能是路由器的标准、受支持的功能。

盘点您的网关配置

@apollo/gateway 库是 Apollo Server 库的扩展，并且在迁移到路由器时需要考虑网关和服务器库的现有配置。例如，您可能需要考虑子图从客户端请求接收到的 HTTP 头的自定义更改，或者将特定头从特定子图 回传 到客户端。

由于路由器使用的是完全不同的配置机制，因此您应该列出网关的自定义行为的清单，以确保您的迁移完成后这些行为都得以保留。

首先寻找以下位置中的配置和自定义

• 环境变量
• 非 Apollo遥测和仪表化（例如，OpenTelemetry 或 Datadog）
• 传递到 new ApolloGateway({ ... })
• 传递到 new ApolloServer({ ... })
• 传递到 new ApolloServer({ plugins: [ ... ] })
• 自定义中间件（例如，Express、Koa、Fastify）

以下各节提供了有关在每个此类别中应寻找什么的更多详细信息。

环境变量

许多 Apollo 工具使用以 APOLLO_ 为前缀的环境变量来设置某些值，例如与 GraphOS Studio 通信的 API 密钥。

务必注意您在现有网关环境中设置的任何环境变量，特别是以 APOLLO_ 为前缀的变量。

该路由器支持以下由 @apollo/gateway 使用的环境变量：

• APOLLO_KEY
• APOLLO_GRAPH_REF

该路由器 重命名 由 @apollo/gateway 使用的以下环境变量：

• APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT → APOLLO_UPLINK_ENDPOINTS
  • 此 参数 支持提供逗号分隔的 URL 列表。

ApolloGateway 构造函数选项

您目前提供给您的 ApolloGateway 构造函数的选项数量取决于您是否正在使用 托管联邦。如果您 在使用托管联邦，您甚至可能为此构造函数提供 零 个选项！

supergraphSdl

在非 托管 联邦中，supergraphSdl 选项 用于通过文件或其他字符串提供组合的 supergraph 模式。通常，该模式是通过 Rover CLI 组合的。

您可以通过以下方式使用此选项的效果：在路由器中

• 将您的应用程序移到托管联邦，并迁移到路由器。

• 在路由器启动时提供 --supergraph 命令行参数：

  文本

  1
  ./router --supergraph supergraph-schema.graphql

  复制

  该路由器会监视此模式文件，并在它发生变化时随时进行热重载。

serviceList / IntrospectAndCompose

如果您提供了这些构造函数选项之一，您的网关将在启动时执行其 自己的 supergraph 架构 组合。路由器不支持在此过程中进行组合。

相反，您需要使用 组合 功能，例如 托管联盟 或 Rover CLI。使用这两种方法中的任何一种，路由器都可以在不重新启动的情况下热重载其 supergraph 架构，避免因组合失败而导致停机。

buildService

The buildService 函数 允许您自定义网关发送到子图的数据传输时使用的HTTP请求。

常用场景包括

• 在运行时覆盖 子图 URL
  • 在路由器中，您可以使用 override_subgraph_urls 选项。
• 通过 RemoteGraphQLDataSource 将头信息传播到子图
  • 在路由器中，您可以使用 headers 选项。

logger

The logger 构造函数选项 允许您为 ApolloGateway 产生的消息指定不同的记录器。默认情况下，它继承自您的 ApolloServer 实例使用的记录器。此选项还可以用于更改日志详细程度。

在生产环境中，路由器默认将日志以JSON结构进行记录，并且您可以调整详细程度。更高级的日志可以通过使用 插件 来启用。

更多信息，请参阅 路由器中的日志记录。

ApolloServer 构造函数选项

The ApolloServer 构造函数支持大量选项，但为了迁移到路由器，我们将重点关注以下内容：

• 上下文
• 插件

有关选项的完整列表，请参阅 ApolloServer 选项。如果您使用其他选项，可能需要额外的步骤来复制相同的行为。请在我们的 GitHub 仓库 上发起讨论，以便我们了解您的需求并为您提供解决方案。

上下文

此构造函数选项是一个对象，您可以使用它实现在请求生命周期内传播信息。用例包括：

• 身份验证信息
• 头部传播

路由器提供 类似的功能。（查看详情）。

插件

此构造函数选项是一个由内置或自定义 插件 组成的数组，这些插件扩展了 Apollo Server 的功能。 如果您向您的 ApolloServer 实例提供插件，请注意每个插件的功能，并将其添加到您的迁移清单中。

在您尝试通过路由器 自定义 复制插件的功能之前，请检查是否有任何 路由器 配置选项 提供相同的功能。 例如，路由器支持将 HTTP 头部信息传播到 子图 以及启用 OpenTelemetry 工具化的选项。

如果您的任何 @apollo/gateway 插件 需要相应的 路由器 自定义，我们鼓励您在路由器存储库的 GitHub 讨论中描述您的用例。

对于不太常见的用例，我们还想帮助建立一个共享自定义的路由器生态系统，以便团队在原生支持可用之前更快速地添加他们需要的功能。

支持的自定义

路由器支持两种类型自定义，可以钩入请求处理管道：

• Rhai 脚本
  • Rhai 是一种针对 Rust 应用程序设计的脚本语言。
• 外部协同处理

每个例子都提供了相应的文档，并在 路由器仓库中。

克伦斯部署

有关迁移到部署在 Kubernetes 上的路由器，请参阅关于如何 配置路由器部署 的一些提示。

报告迁移问题

如果您遇到本文章无法解决的迁移问题，请搜索现有的 GitHub 讨论区，如果没有找到所需内容，请开启新的讨论。