创建和使用合约

了解如何在GraphOS中创建、使用和编辑合约

此功能仅在GraphOS企业计划中可用 GraphOS企业计划.
您可以通过免费注册来试用企业试用.

ⓘ 注意

以下GraphOS Studio步骤需要具有组织管理员或图形管理员角色的组织成员。了解成员角色。

创建合约

先决条件

更新您的路由器和子图

在您创建任何合约之前：

如果您使用Apollo Server：
- 对于Federation 2 合约变体，将您的Apollo Server子图更新到2.0.0或更高版本。@apollo/subgraph库。
- 对于Federation 1 合约变体，将@apollo/subgraph更新到0.1.1或更高版本。

ⓘ 注意

@apollo/subgraph已替换@apollo/federation用于充当子图的Apollo Server实例。符号名称保持不变。

如果您使用@apollo/gateway库而不是GraphOS Router：
- 对于Federation 2 合约变体，请将您的网关的 @apollo/gateway 库更新到v2.0.2或更高版本。
- 对于Federation 1 合约变体，请将您的网关的 @apollo/gateway 库更新到v0.34.0或更高版本。

ⓘ 注意

Apollo推荐使用 router 而不是 @apollo/gateway ，因为它显著提高了性能和安全。如果您正在使用 graph 的 @apollo/gateway ，您可以在不改变任何其他部分的情况下迁移到 router 。请参阅迁移指南。

上述库和工具的旧版本不完全支持所需的 @tag 指令。

(仅Fed1) 启用 `@tag` 的变体支持

ⓘ 注意

此步骤仅要求Federation 1 supergraph。如果您有Federation 2 supergraph，请继续到下一步。

合约使用您的图中的一个现有变体（称为源变体）来生成其合约模式。如果您的源变体使用Federation 1，则需要启用其对 @tag 指令的支持，在 GraphOS Studio：

打开要作为源变体使用的 Settings 页面，然后选择 variant 选项卡。
在 Build Configuration 部分，点击 Edit Configuration 并启用对 @tag 的支持。

1. 向子图模式添加 `@tag`

使用合约，您将@tag指令应用于类型和字段，以表示选择它们是否包含在您的合约模式中。

在您可以添加@tag指令之前，您需要在您的子图模式中定义指令。这种方式取决于您使用的是哪个联盟版本：

例如，让我们看一下这个联邦2子图模式：

products.graphql

1
extend schema
2
  @link(
3
    url: "https://specs.apollo.dev/federation/v2.0"
4
    import: ["@key", "@tag"]
5
  )
6

7
type Query {
8
  topProducts: [Product!]! @tag(name: "partner")
9
}
10

11
# All fields of the Product object type automatically inherit
12
# the "partner" tag so we can avoid tagging them individually
13
type Product @key(fields: "upc") @tag(name: "partner") {
14
  upc: ID!
15
  name: String!
16
  description: String!
17
  internalId: ID! @tag(name: "internal")
18
  percentageMatch: Float! @tag(name: "experimental")
19
}

该模式将该@tag指令应用于以下位置：

查询顶层产品字段（返回产品列表）Query.topProducts （字段）
产品对象类型Product （类别）
产品Product的两个字段（internalId和percentageMatch）

每个@tag都有一个字符串名称。你可以用相同的名称给类型和字段标记，如果应该将它们作为一个组包括或排除，由特定的契约处理。

💡 提示

有关有效@tag用法的详细信息，请参阅@tag和契约的规则。

。组成默认情况下会删除一些其他指令。了解更多。

2. 发布更新的子图模式

在你添加了标签后，通过将你的更新子图模式发布到GraphOS来更新你的源变体。

💡 提示

发布后，如果工作室没有反映你所添加的@tags，请确保你已经更新所有必需的库和工具。如果你通过勘探获取子图模式，旧的子图库可能会删除@tag指令。

3. 创建合同

打开你的源变体's设置页面并选择此变体标签。在左侧导航中打开合同。
单击创建合同以打开合同创建对话框。
对话框第一步中，提供以下内容
- 新的合同变体的名称
- 要使用的源变体
ⓘ 注意
合同创建后，您无法更改这些值。
单击继续。
指定基于标签的合同筛选条件。
- 对话框检测你的源变体模式中使用的所有标签名称，并将这些名称填充到排除标签和包括标签下拉列表中。你可以向每个列表添加任意数量的标签名称。
- 你还可以添加源变体模式中尚未出现的标签名称。如果你后来添加了具有该名称的标签，合同将尊重它们。

💡 提示

在Apollo Federation 2中，如果您想从您的源变体的API模式及其所有合同模式中排除类型或字段，您可以使用@inaccessible指令而不是@tag。有关详细信息，请参阅使用@inaccessible。

添加完标签名称后，单击生成预览。工作室将尝试根据您提供的过滤器生成合同模式并显示结果。生成预览后，单击审查以继续到下一步。
审查所有合同的细节。如果一切看起来都正确，请单击创建。这会启动您的启动合同变体及其初始合同模式。

ⓘ 注意

GraphOS可能在生成您的合同模式时遇到错误。有关这些错误的描述，请参阅错误。

使用合同变体

您可以使用您的合约变体为用户提供合约路由器或合约文档。contracts routers或contract documentation。例如，您可以完成一个新路由器实例的管理联邦配置，该实例使用您的合约变体。

自动更新

Apollo会在以下任何一种情况发生时自动更新您的合约模式：

GraphOS成功为合约的源变体更新supergraph模式。
您可以修改您的合约。

这些自动更新确保了您的合约模式反映了源变体的最新版本，并且包括和排除正确的类型和字段。

您的管理合约路由器会自动获取合约模式的更新。

编辑合约

ⓘ 注意

您不能更改现有合约的名称或源变体。相反，您可以创建一个新的合约，如果您不再需要它，可以删除现有的合约变体。

创建合约后，您可以编辑其包括和排除的标签列表：

从您图's设置页面中的'合约'列表，点击您要编辑的合约右侧的按钮。然后点击。这将打开一个与您用来创建合约的对话框类似的对话框。进行任何必要的更改。
如果您更改了合约的包括或排除标签，GraphOS将自动运行合约检查以确定这些更改是否会影响到使用您的合约变体的任何客户端。这些检查的结果将在合约编辑对话框的"Review Schema"步中显示。
更新完成后，对话框将显示"Contract Updated"。