Apollo Federation 2 中的向下兼容性

导航从 Apollo Federation 1 至 Federation 2 的过渡

对于`@apollo/gateway` v0.x 的官方支持是否结束？

是的。截至 2022 年 11 月 15 日，@apollo/gateway v0.x 已正式弃用，预计于 2023 年 9 月 22 日停止支持。 @apollo/gateway v2.x 仍全面支持。

了解更多关于弃用和生命周期的信息。

我需要修改我的子图模式以使用 Federation 2 吗？

最终需要。迁移到 Federation 2 的过程有三个步骤：

升级您的网关以支持 Federation 2（我们推荐转向 GraphOS 路由器）。
开始使用 Federation 2 构造您的超级图模式逻辑。
更新您的各个子图以使用 Federation 2 功能和指令。

步骤 1 和 2 通常不需要修改您的子图模式。需要修改的模式是那些会导致某些构造错误（见下文。）的 schema。

第3步需要对您的子图模式进行一些更改，具体描述在这里。

破坏性更改

如上所述，以下 Federation 1 的示例应该会引发组合错误，但并未检测到。如果您的子图模式包含与这些匹配的语法，您需要在迁移到 Federation 2 之前更新这些模式。

无效的 `@key` 指令

一个实体的@key 由一个或多个实体的字段组成。如果其中任何一个字段有子字段，则@key也应该包含至少一个这些子字段：

✅

1
type User @key(fields: "id organization { id }") {
2
 id: ID!
3
 organization: Organization!
4
}
5

6
type Organization {
7
 id: ID!
8
 name: String!
9
}

在此示例中，User's 的键字段是User.id和User.organization.id。

Federation 1 的组合不正确地允许以下此类@key：

❌

1
type User @key(fields: "id organization") {
2
 id: ID!
3
 organization: Organization!
4
}
5

6
type Organization {
7
 id: ID!
8
 name: String!
9
}

此@key应破坏组合，因为它不包含至少一个组织的子字段。

无效的 `@requires` 指令

一个子图可以标记一个实体字段，使用@requires指示它依赖于另一个子图的字段和子字段：

✅

子图A

1
type Product @key(fields:"sku") {
2
  sku: ID!
3
  dimensions: ProductDimensions!
4
}
5

6
type ProductDimensions {
7
  size: Int!
8
  weight: Int!
9
}

子图B

1
extend type Product @key(fields:"sku") {
2
  sku: ID! @external
3
  dimensions: ProductDimensions! @external
4
  shippingEstimate: Int! @requires(fields: "dimensions { size weight }")
5
}
6

7
type ProductDimensions {
8
  size: Int!
9
  weight: Int!
10
}

在这个例子中，子图B的shippingEstimate字段依赖于子图A的dimensions.size和dimensions.weight字段。

Federation 1 错误地允许以下类似的@requires指令：

❌

子图A

1
type Product @key(fields:"sku") {
2
  sku: ID!
3
  dimensions: ProductDimensions!
4
}
5

6
type ProductDimensions {
7
  size: Int!
8
  weight: Int!
9
}

子图B

1
extend type Product @key(fields:"sku") {
2
  sku: ID! @external
3
  dimensions: ProductDimensions! @external
4
  shippingEstimate: Int! @requires(fields: "dimensions { length depth }")
5
}
6

7
type ProductDimensions {
8
  size: Int!
9
  weight: Int!
10
}

这个@requires指令应该破坏组合，因为它依赖于不存在的子字段（length和depth）。

无效的`@provides`指令

一个子图可以注解一个实体字段，使用@provides指令以指示该子图可以独立解决通常标记为@external的实体字段。

✅

子图A

1
type Product @key(fields: "id") {
2
  id: ID!
3
  info: ProductInfo @external
4
}
5

6
type ProductInfo {
7
  name: String! @external
8
  inStock: Boolean! @external
9
}
10

11
type Query {
12
  outOfStockProducts: [Product!]! @provides(fields: "info { name }")
13
  discontinuedProducts: [Product!]!
14
}

在上面的例子中，子图 A可以通过outOfStockProducts查询解决Product.info.name字段。任何其他通往Product.info.name的路径都会导致额外的子图调用。

Federation 1 错误地允许以下类似的@provides使用：

❌

子图A

1
type Product @key(fields: "id") {
2
  id: ID!
3
  info: ProductInfo @external
4
}
5

6
type ProductInfo {
7
  name: String! @external
8
  inStock: Boolean! @external
9
}
10

11
type Query {
12
  outOfStockProducts: [Product!]! @provides(fields: "info")
13
  discontinuedProducts: [Product!]!
14
}

这个@provides的使用应该破坏组合，因为它没有指定它可以解决哪个子字段。这在Federation v2中被正确捕获和暴露为错误，但Federation v1错误地允许这种使用。

Federation 1能否将我的Federation 2子图模式进行组合

不，在你至少将一个子图架构转换为真正的Federation 2架构之前不可以。

Federation 2提供了相对Federation 1而言更灵活的组合规则。修改你的子图架构以利用这种灵活性之后，你的图将不能再与Federation 1进行组合。你需要撤销这些更改才能回到Federation 1。

《@apollo/gateway》v2版本支持Federation 1吗？

在将图转移到Federation 2之前，你可以阅读如何转移到Federation 2的官方文档。

对于@apollo/gateway v0.x的插件和自定义，在@apollo/gateway v2.x将按预期继续工作。

兼容性表格

路由器/网关版本	Federation 1 Composition	Federation 2 Composition
Apollo Router Core v1.x	🟢	🟢
`@apollo/gateway` v2.x	🟢	🟢
`@apollo/gateway` v0.x (已弃用)	🟢	❌

移动步骤