Apollo GraphOS 快速入门

使用 Apollo Federation 和 GraphOS 构建 GraphQL 联邦 API

Apollo Federation 将微服务结合成一个 GraphQL API，为所有客户端应用提供对所有数据源的实时访问。 Apollo GraphOS 是构建、测试和部署联邦 GraphQL API（又称超级图）的平台。

在这个快速入门结束时，您将设置一个超级图，它集成了产品、用户和库存服务的数据。在这个过程中，您将学习关于 Rover CLI 和 GraphOS Studio 等工具。

要了解更多关于 Apollo Federation 和使用 GraphOS 的优势，请参阅以下资源：

先决条件

要完成此快速入门，您必须具备以下条件

Apollo 的零售演示的本地版本
- 从其 GitHub 仓库
最新 Long-Term Support (LTS) 版本的Node.js
ⓘ 注意
虽然零售演示使用 Node.js 为其所有服务提供支持，Apollo Federation 与许多 GraphQL 服务器库兼容。许多 GraphQL 服务器库兼容。您还可以整合使用不同编程语言和服务器库的服务。

如果尚未设置，请在继续之前设置这些。

概览

使用 GraphOS 设置 supergraph 需要进行几个步骤：

安装 Rover CLI。
开始本地开发。
将您的服务（在 supergraph 的上下文中称为子图）发布到 GraphOS。

发布您的子图后，您可以使用 GraphOS Studio 探索并更好地了解您的 supergraph。

第一步：安装 Rover CLI

Rover 是 Apollo 的 CLI，用于管理各种图，包括子图和超级图。您将在本快速入门的整个过程中使用它。

ⓘ 注意

即使您已经安装了Rover，也请通过完成此步骤来更新您的版本。

使用适合您系统的适当命令安装最新的 Rover 版本：

MacOS / 类 Unix 系统

curl -sSL https://rover.apollo.dev/nix/latest | sh

Windows

iwr 'https://rover.apollo.dev/win/latest' | iex

安装后，在您的终端中运行rover -V以确认它已成功安装。验证打印的版本号是否与最新版本相匹配。如果不匹配，您可能需要手动删除过时的安装。

现在您已安装 Rover，您就可以开始使用超级图进行本地开发了！

第二步：开始本地开发

运行 supergraph 包括运行其路由器。路由器是客户端访问超级图的唯一入口点。路由器接收传入的操作，并将它们智能地路由到组件服务，最后返回统一的响应。

在此步骤中，您将执行以下操作：

本地运行子图。
本地运行您的路由器。
查询您的路由器以确认其工作如预期所示。

运行子图

要开始本地开发，您必须首先从retail 演示运行并使之工作。从根目录安装依赖项：

npm install

然后运行子图：

npm run dev:subgraphs

在您的终端中，您应该能收到每个子图的通知：

Setting up [products] subgraph at https://127.0.0.1:4001/products/graphql
Setting up [orders] subgraph at https://127.0.0.1:4001/orders/graphql
Setting up [users] subgraph at https://127.0.0.1:4001/users/graphql
...

确保这些子图运行良好，以便路由器可以查询它们。

ⓘ 注意

retail 演示包含了这些子图背后的代码，包括它们的模式、解析器和模拟数据。这些文件仅供参考—理解它们不是完成此快速入门的必要条件。查看这些教程以了解更多有关GraphQL 模式和解析器的信息。

运行路由器

当您的子图正在运行时，您可以使用Rover在本地启动路由器。为此，使用带有rover dev命令并带有--supergraph-config和--router-config选项。

retail 演示附带supergraph-config-dev.yaml和router-config-dev.yamlYAML 配置文件，这些文件包含子图名称、URL 和路由器配置。

在运行子图的不同终端窗口中，运行此命令：

rover dev \
  --supergraph-config supergraph-config-dev.yaml \
  --router-config router-config-dev.yaml

您第一次启动rover dev过程时，您将在终端看到以下情况：

Rover获取提供的子图模式并为每个模式启动会话。

🛫 starting a session with the 'discovery' subgraph
🛫 starting a session with the 'checkout' subgraph
🛫 starting a session with the 'users' subgraph
🛫 starting a session with the 'inventory' subgraph
🛫 starting a session with the 'orders' subgraph
🛫 starting a session with the 'shipping' subgraph
🛫 starting a session with the 'products' subgraph
🛫 starting a session with the 'reviews' subgraph

Rover使用Apollo Federation通过逐个添加子图模式来构建supergraph 模式。
🎶 composing supergraph with Federation v2.8.0
✅ successfully composed after adding the 'products' subgraph
- Rover添加子图序列的顺序是未定义的，因此在中间步骤中，您可能会看到如下所示的组合错误。
error[E029]: Encountered 1 build error while trying to build a supergraph.
当组合成功完成时，Rover开始一个本地运行的路由器会话，并提供给它超级图模式。
🚀 your supergraph is running! head to https://127.0.0.1:4000 to query your supergraph
ⓘ 注意
此消息后面可能会跟随着组合错误和成功的组合通知。只要您能访问https://127.0.0.1:4000，您的路由器就在本地运行。
Rover开始监视提供的子图模式以检测更改。
👀 watching ./subgraphs/products/schema.graphql for changes
- Rover将在检测到其中一个时重新组合超级图模式。重新组合自动重新加载路由器。

太棒了！现在您已经本地运行了一个超级图。

查询您的路由器

为确保一切按预期工作，您可以在Apollo模拟器中查询您的路由器，这是Rover自动启动的。

在浏览器中打开localhost:4000，以访问您本地运行的路由器。它的外观可能如下所示：
通过复制粘贴以下查询到操作窗口，然后点击标签为示例查询的播放按钮。

query ExampleQuery {
  listAllProducts {
    id
    title
    description
    mediaUrl
    variants {
      id
      price
    }
  }
}

确认您运行操作后，您将在右侧的响应面板中看到以下内容：
{
"data": {
"listAllProducts": [
{
"id": "product:1",
"title": "Air Jordan 1 Mid",
"description": "Air Jordan 1 Mid is a blue, grey and white sneaker from the iconic jordan brand",
"mediaUrl": "https://sneakernews.com/wp-content/uploads/2022/06/air-jordan-1-mid-university-blue-grey-dx9276-100-6.jpg",
"variants": [
{
"id": "variant:1",
"price": 600.25
},
{
"id": "variant:2",
"price": 20.12
}
]
},
{
"id": "product:2",
"title": "Supreme x Tiffany & Co. Box Logo Tee",
"description": "A classic Supreme vbox t-shirt in the signature Tiffany blue.",
"mediaUrl": "https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcQWDHD3SSS98UAVKODaql7nrDTopfL4tcTnEltW8Yqy4hyDu4i5b70Wb3Y8-wACJIo5g-ZdRULPQKUmt7JfwiaSdgiOBz4pvU_YelKHUI4nhoXmMJPeh_tyWQ",
"variants": [
{
"id": "variant:4",
"price": 600.25
},
{
"id": "variant:5",
"price": 600.25
},
{
"id": "variant:6",
"price": 600.25
},
{
"id": "variant:7",
"price": 600.25
},
{
"id": "variant:8",
"price": 600.25
}
]
},
{
"id": "product:3",
"title": "THE MACKINAC 40MM",
"description": "Established by Detroit’s historic Bayview Yacht club, the days-long Port Huron to Mackinac Island regatta is one of the longest and most grueling freshwater races in the world.\n\nNamed for this legendary competition, the Shinola Mackinac is our first watch with automatic, single-eye chronograph yacht-timer functionality.\n\nIt’s a precision instrument designed to be passed on for generations—just like the tradition that inspires it.",
"mediaUrl": "https://shinola-m2.imgix.net/images/Products/20253783-sdt-012455107/S0120253783_F2_MAIN_01.png?h=1500&w=1500&bg=f7f7f7&auto=format,compress&fit=fillmax",
"variants": [
{
"id": "variant:9",
"price": 3499.99
}
]
},
]
},
...
}
此操作请求从产品子图请求所有产品的列表。您可以选择删除字段，例如mediaUrl，或者添加字段，例如releaseDate，以查看响应如何变化。
接下来，您将执行一个操作，以展示联盟的强大功能。

将操作窗口中的示例查询替换为以下内容。通过单击播放按钮，现在称为GetCart，来运行它。

# Get the current user's cart with all the items and their product info as well as the price.
  query GetCart {
    user {
      id
      username
      shippingAddress
      cart {
        subtotal
        items {
          price
          inventory {
            inStock
          }
          product {
            title
            description
            mediaUrl
          }
        }
      }
    }
  }

在响应面板中，您应该看到以下错误： Could not locate user by id. Please specify a valid x-user-id header like user:1。
此错误出现是因为操作根据用户的ID检索特定用户的购物车给定用户ID。此操作期望在请求头中包含用户ID。您可以在沙箱中通过以下方式包含它：
- 打开位于操作编辑器下方的头选项卡。
- 单击添加新头。
- 输入x-user-id作为头键，并user:1作为值。

重新运行请求。在响应面板中，确认您看到了以下内容：

Apollo Sandbox shows a query plan diagram for an operation.

APOLLO_KEY=service:Federation-Quickstart:••••••••••••••••••••• \
rover subgraph publish Federation-Quickstart@current \
--schema ./products-schema.graphql \
--name your-subgraph-name \
--routing-url http://products.prod.svc.cluster.local:4001/graphql
- 在APOLLO_KEY=之后显示的保护值以service:开头，是你的graph API密钥。
- 在rover subgraph publish之后显示的值是你的graph ref。默认情况下，它以@current结尾。
- 在下一步中，您将使用您的graph API密钥和graph ref。
⚠️ 注意
API密钥是秘密凭证。切勿在组织外部分享它们或将它们提交到版本控制。删除并替换您认为已泄露的API密钥。
保持对话框打开；您将使用Rover完成设置。

发布子图模式

返回终端完成下一步

确保您的子图仍在本地运行。
将您从Studio复制的多行命令复制并粘贴，并将最后三行替换为以下内容
--schema ./subgraphs/products/schema.graphql \
--name products \
--routing-url https://127.0.0.1:4001/products/graphql
它现在应该看起来像这样
APOLLO_KEY=service:<GRAPH_API_KEY> \
rover subgraph publish <GRAPH_REF> \
--schema ./subgraphs/products/schema.graphql \
--name products \
--routing-url https://127.0.0.1:4001/products/graphql
- –schema选项指定要发布的模式文件的路径。
- 选项指定子图的名字。
- 是路由器应发送针对此特定子图请求的地址。
  ⓘ 注意
  在生产supergraph中，子图的routing-url通常是其公开端点。
仍然位于零售演示的根目录中，打开一个新的终端窗口。粘贴并运行您的更新多行命令。
- 由于命令提供了localhost地址作为routing-url，终端将确认您想发布。输入Y。
- 如果命令成功，您将在终端看到以下内容
  A new subgraph called 'products' was created in <GRAPH_REF>
  The supergraph schema for <GRAPH_REF> was updated,
  composed from the updated 'products' subgraph
- 几秒钟后，您在创建空supergraph时留下的GraphOS Studio对话框左下角会显示Schema已发布。

为inventory子图运行rover subgraph publish命令，用您的graph ref替换。您不再需要包含包含您的graph API密钥的第一行：

rover subgraph publish <GRAPH_REF> \
--schema ./subgraphs/inventory/schema.graphql \
--name inventory \
--routing-url https://127.0.0.1:4001/inventory/graphql

同样为users子图做相同的事情，用您的graph ref替换：

rover subgraph publish <GRAPH_REF> \
--schema ./subgraphs/users/schema.graphql \
--name users \
--routing-url https://127.0.0.1:4001/users/graphql

恭喜！发布这些子图后，您可以在GraphOS Studio中探索和与之交互，以及由它们组成的supergraph。

ⓘ 注意

零售演示还包含其他子图——例如，reviews和shipping子图。您刚才发布的这三个足以了解GraphOS Studio有哪些功能，但您如果想探索它们的模式，可以发布其他子图。

探索您的supergraph

一旦您发布子图，从左侧导航打开 Schema 页面，Studio 来探索组合超级图模式以及各个子图模式以及它们之间的关系。

在参考标签下，您可以查看和过滤模式中类型的字段定义。例如，选择对象，然后用户，以查看所有 用户 类型的字段及其提供它们的子图。
在 SDL 标签中显示了您的超级图的 API 模式's 和超级图模式，可根据子图过滤。查看超级图的 SDL（模式定义语言）允许开发人员看到子图模式如何组合在一起。
在 可视化 标签中提供了一个可过滤、可导航的图表现形式，展示了您的超级图模式。一旦开始收集超级图上的指标，就可以使用可视化工具创建热图，以识别字段频繁使用、发生最高延迟或错误。

GraphOS 还提供了管理模式，包括模式提议、检查和代码格式清理。此外，GraphOS 模式交付工具有助于将模式发布集成到您的 DevOps 工作流程中。

部署后路由器，无论是自托管还是使用 Apollo 管理的云选项，都可以用它来收集和导出遥测数据到 GraphOS Studio 以及其他可观察性工具和应用性能监控（APM）工具。

下一步

根据您的目标，有多种方式可以了解 GraphOS' 的功能或将您的超级图更靠近生产：

了解不同的路由器类型，以确定哪种类型最适合您的用例。
了解更多关于 Studio 功能，包括提议、代码格式清理和检查。
- 如果您想对这些功能进行直观的浏览，请查看下面的视频。
了解 GraphOS 指标和路由遥测。
查看 rover template 命令，以快速开始新的 GraphQL 项目或探索不同库和语言中的实现。

简介

变更日志