Apollo Federation指令

Apollo Federation定义了一组指令，您可以在您的子图模式中使用这些指令以启用某些功能。

导入指令

要在Federation 2子图模式中使用联邦指令，将以下格式的@link指令应用于schema类型：@link 指令的以下格式应用于schema类型：

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

如果您有一个现有的schema声明，则可以应用此指令，或者应用新的extend schema声明（如上图所示）。

修改import数组以包含你的子图模式所需的任何联盟指令。上面的例子中导入的是@key和@shareable指令（这些是最常用的）。

重命名指令

如果导入的指令的默认名称与你的自定义指令之一相匹配，你可以使用以下语法重命名导入的指令：

1
extend schema
2
  @link(url: "https://specs.apollo.dev/federation/v2.3",
3
        import: [{ name: "@key", as: "@uniqueKey"}, "@shareable"])

此例子图模式使用@uniqueKey用于联盟指令（通常名为@key）。

命名空间指令

如果你没有从链接的规范中导入特定的指令，你仍然可以在你的子图模式中使用该指令。然而，该指令具有前缀：

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

5
type Book @federation__shareable {
6
  title: String!
7
}

在上面的例子中，@shareable没有从联盟规范中导入。因此，它以@federation__shareable的形式可用。

导入的@link指令的默认命名空间前缀是其关联规范（通过url的倒数第二个组件指示）的名称，加两个下划线（__）。对于 Apollo Federation 指令，此前缀是federation__。

你可以通过为@link提供参数来自定义特定规范的命名空间前缀：

1
extend schema
2
  @link(url: "https://specs.apollo.dev/federation/v2.3",
3
        as: "fed")
4

5
type Book @fed__shareable {
6
  title: String!
7
}

如图所示，自定义命名空间前缀以两个下划线结束。

1
directive @link(
2
  url: String!,
3
  as: String,
4
  for: link__Purpose,
5
  import: [link__Import]
6
) repeatable on SCHEMA

此指令将外部规范的定义链接到此模式。每个 Federation 2 子图都使用@link指令来导入本文中描述的其它联盟特定指令（参见导入指令中的语法）。

有关更多关于@link的信息，请参阅官方规范。

管理类型

1
directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE

指定一个对象类型为一个实体并指定其键字段。键字段是一组子图可以使用以唯一标识实体的任何实例的字段。

1
type Product @key(fields: "id") {
2
  id: ID!
3
  name: String!
4
  price: Int
5
}

如果您使用的子图库支持可重复指令，则可以为单个实体应用多个 @key 指令以指定多个有效的键字段集：

1
type Product @key(fields: "upc") @key(fields: "sku") {
2
  upc: ID!
3
  sku: ID!
4
  name: String
5
}

在 Apollo Federation 2.3 及更高版本中，您还可以将 @key 应用到 interface 定义中来创建 实体接口。如果在 Federation 2 的早期版本中将 @key 应用到 interface 上，会发生 组合 错误。

参数

1
directive @interfaceObject on OBJECT

表示一个对象定义是一个子图实体的接口抽象。这种抽象使子图能够自动向实现特定实体接口的所有实体贡献字段。

在构成过程中，每个@interfaceObject的字段既被添加到其相应的接口定义中，也被添加到实现该接口的所有实体类型中。

了解有关实体接口的更多信息。

1
directive @extends on OBJECT | INTERFACE

表示一个对象或接口定义是该类型另一个定义的扩展。

此指令用于与不支持extend关键字，且通常通过程序生成其模式而不是使用静态.graphql文件的GraphQL子图库一起使用。

管理共享字段

1
directive @shareable repeatable on FIELD_DEFINITION | OBJECT

表示允许多个子图解析对象类型的字段（默认情况下，Federation 2中，对象字段只能由一个子图解析）。

1
type Position {
2
  x: Int! @shareable
3
  y: Int! @shareable
4
}

如果应用于对象类型定义，则该类型的所有字段都视为@shareable：

1
type Position @shareable {
2
  x: Int!
3
  y: Int!
4
}

如果一个字段在某个子图中标记了@shareable，则必须在每个定义该字段的Federation 2子图中将其标记为@shareable或@external。

如果一个 字段 包含在实体的 @key 指令 中，那么该字段自动被认为是 @shareable 并且相应的子图（s）中不需要该指令。

另请参阅 Apollo Federation 中的值类型 以及 解析另一个子图的字段。

关于 @shareable 指令，它用于指示一个对象 字段 可以被多个 子图 解析。由于接口字段不是直接解析的（它们的实现是）， @shareable 在接口字段上没有意义，并且不允许（至少从联盟 2.2 版起；早期联盟版本错误地在接口字段上忽略了 @shareable）。

1
directive @inaccessible on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION

指示子图模式中的定义应从路由器的 API 模式 中省略，即使该定义也存在于其他子图。这意味着该字段根本不会暴露给客户端。

使用 @inaccessible 的常见用例包括：

• 在更新跨越多个 子图 共享的定义（例如，值类型）时避免 组合错误）
• 在不将 字段 暴露给客户端的情况下，将字段作为实体 @key 的一部分使用

type Position @shareable {
  x: Int!
  y: Int!
  z: Int! @inaccessible
}

type Position @shareable {
  x: Int!
  y: Int!
  # Subgraph is not yet updated
}

通常，当您在某个子图中添加一个附加值类型字段时，组合将失败，因为该字段在其他子图中不可解析。使用 @inaccessible，您可以在将字段添加到其他子图中时保留组合。当推广完成时，您可以删除指令并开始使用该字段。

一个不可访问的字段或类型未被省略在图模式中，因此路由器仍然知道它的存在（但客户端不能将其包括在 操作）。这使得路由器可以在组合来自多个子图的实体字段时，使用不可访问的字段作为实体 @key 的一部分。

如果一个类型被标记为 @inaccessible，则必须将该类型返回的所有字段也标记为 @inaccessible。否则，将发生组合错误。

有关更多信息，请参阅 使用 @inaccessible。

1
directive @override(from: String!) on FIELD_DEFINITION

表明一个对象字段现在由该子图而不是另一个已定义的子图解析。这使得您可以迁移一个字段从一个子图到另一个子图。

您可以将 @override 应用于 实体字段 以及根 操作 类型（如 Query 和 Mutation）的字段。

type Product @key(fields: "id") {
  id: ID!
  inStock: Boolean!
}

type Product @key(fields: "id") {
  id: ID!
  inStock: Boolean! @override(from: "Products")
}

在上面的例子中，我们将 Product.inStock 字段从产品 子图迁移到库存子图。组合的图模式显示，即使在产品子图中也定义了该字段，但 Product.inStock 的解决是通过库存子图而非产品子图。

您可以将 @override 应用到 @shareable 字段。如果这样做，则只有一个提供的子图的 from 参数不再解析该字段。其他子图仍然可以解析该字段。

只能有一个子图可以 @override 某个给定的字段。如果多个子图尝试 @override 相同字段，则发生组合错误。

有关更多信息，请参阅 迁移实体和根字段。

在生产 subgraph 上推出任何更改，包括字段迁移，可能会降低图的表现。一次性将所有流量从一个 subgraph 转到另一个 subgraph 可能会超载覆盖 subgraph。

渐进式 @override 特性允许以渐进式、逐步部署带有 @override 字段的 subgraph。作为 subgraph 开发者，您可以为覆盖和被覆盖 subgraph 对字段各自解决流量比例进行自定义。您可以为 @override 字段应用标签以设置应该由覆盖 subgraph 解决的流量百分比，其余部分由被覆盖的 subgraph 解决。然后您可以在 Studio 中监控 subgraph 的性能，解决问题，并迭代地逐步增加百分比，直到所有流量都被覆盖 subgraph 解决。

有关更多信息，请参阅 使用 @override 的增量迁移指南。。

参数

控制访问

1
directive @authenticated on
2
    FIELD_DEFINITION
3
  | OBJECT
4
  | INTERFACE
5
  | SCALAR
6
  | ENUM

表示目标元素仅供身份验证的超级图用户访问。欲了解更多精确访问控制，请参阅下面的@requiresScopes指令。有关更多详细信息，请参阅路由器文章

1
directive @requiresScopes(scopes: [[federation__Scope!]!]!) on
2
    FIELD_DEFINITION
3
  | OBJECT
4
  | INTERFACE
5
  | SCALAR
6
  | ENUM

表示目标元素仅供拥有适当JWT权限范围的已验证超级图用户访问。有关更多细节，请参阅路由器文章

参数

1
directive @policy(policies: [[federation__Policy!]!]!) on
2
  | FIELD_DEFINITION
3
  | OBJECT
4
  | INTERFACE
5
  | SCALAR
6
  | ENUM

表示目标元素基于在Rahi脚本或协处理器中评估的授权策略进行限制。有关更多详细说明，请参阅路由器文章

参数

引用外部字段

1
directive @external on FIELD_DEFINITION | OBJECT

表示该子图通常无法解析特定对象的字段，但仍然需要为了其他目的定义该字段。

该指令总是与引用对象字段的另一个指令结合使用，例如@provides或@requires

1
type Product @key(fields: "id") {
2
  id: ID!
3
  name: String! @external
4
  inStock: Boolean!
5
}
6

7
type Query {
8
  outOfStockProducts: [Product!]! @provides(fields: "name")
9
  discontinuedProducts: [Product!]!
10
}

本示例 子图 通常无法解析 Product.name 字段，但它可以在 Query.outOfStockProducts 查询 路径（由 @provides 指令 指示）解析这些字段。

如果应用于一个 对象类型 定义，该类型的所有 字段 都被视为 @external:

1
type Position @external {
2
  x: Int!
3
  y: Int!
4
}

1
directive @provides(fields: FieldSet!) on FIELD_DEFINITION

指定一组 实体字段，子图可以解析，但仅限于特定的模式路径（在其他路径上，子图无法解析这些字段）。

如果一个 子图始终可以解析特定的实体字段，请不要使用此指令。

使用此 指令始终是一个可选项优化。它可以减少路由器需要与之通信以解决某些操作的总子图数，从而提高性能。

1
type Product @key(fields: "id") {
2
  id: ID!
3
  name: String! @external
4
  inStock: Boolean!
5
}
6

7
type Query {
8
  outOfStockProducts: [Product!]! @provides(fields: "name")
9
  discontinuedProducts: [Product!]!
10
}

此示例子图可以解析 Query.outOfStockProducts 返回的产品的 Product.name，但不能解析 Query.discontinuedProducts。

有关更多信息，请参阅 使用 @provides。

参数

1
directive @requires(fields: FieldSet!) on FIELD_DEFINITION

表示特定实体字段的解析器依赖于由其他子图解析的其他实体字段的值。这告知路由器需要首先获取那些外部定义字段的值，即使原始客户端查询没有请求它们。

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

上面示例子图解析了Product对象的shippingEstimate字段，但它需要产品的size和weight来执行此操作。由于这两个字段由不同的子图解析，它们被标记为@external。

另请参阅贡献计算实体字段。

参数

应用元数据

1
directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION | SCHEMA

将任意字符串元数据应用到模式位置。自定义工具可以在模式交付流程的任何步骤中使用此元数据，包括组合、静态分析和文档。GraphOS Enterprise的合约功能使用@tag及其包括和排除过滤器。

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

4
type Query {
5
  customer(id: String!): Customer @tag(name: "team-customers")
6
  employee(id: String!): Employee @tag(name: "team-admin")
7
}
8

9
interface User @tag(name: "team-accounts") {
10
  id: String!
11
  name: String!
12
}
13

14
type Customer implements User @tag(name: "team-customers") {
15
  id: String!
16
  name: String!
17
}
18

19
type Employee implements User @tag(name: "team-admin") {
20
  id: String!
21
  name: String!
22
  ssn: String!
23
}

参数

管理自定义指令

1
directive @composeDirective(name: String!) repeatable on SCHEMA

指示组合将子图模式中特定自定义类型系统指令的所有使用情况都保留在超级图模式中（默认情况下，组合从超级图模式中省略大多数指令）。

1
extend schema
2
    @link(url: "https://specs.apollo.dev/link/v1.0")
3
    @link(url: "https://specs.apollo.dev/federation/v2.3", import: ["@composeDirective"])
4
    @link(url: "https://myspecs.dev/myDirective/v1.0", import: ["@myDirective", { name: "@anotherDirective", as: "@hello" }])
5
    @composeDirective(name: "@myDirective")
6
    @composeDirective(name: "@hello")
7

8
directive @myDirective(a: String!) on FIELD_DEFINITION
9
directive @hello on FIELD_DEFINITION

此指令有以下要求：

• 确保您的 子图库 支持 @composeDirective 或尝试手动将 @composeDirective 定义添加到您的子图模式中。
• 必须通过 @link 指令从核心规范导入，并定义和导入必须保留的指令。
• 指定的 name 必须与在此子图中用于指令的名称匹配。
  • 如果您在 @link 定义中使用了 as 参数以修改指令的名称，从规范默认名称变为修改后的名称，提供修改后的名称，而不是默认名称。
• 如果多个子图导入和使用该指令：
  • 所有这些子图使用的指令名称必须相同。
  • 所有这些子图应使用由指令定义的同一主要版本的规范。

如果上述要求有任何一项未满足，组合 将失败。

如果不同的子图使用了指令对应规范的不同的版本，则超图模式使用所有子图中版本号码最高的版本。 组合 将不会验证此版本的指令是否与使用较早版本的子图兼容。

参数

使用上下文保存和引用数据

企业试用版

1
directive @context(name: String!) on OBJECT | INTERFACE | UNION;

@context 指令定义了一个命名上下文，从该上下文中可以传递到一个带有 @fromContext 指令的字段接收器注解的字段。接收器必须是一个带有注解的字段 @fromContext。

每个 @context 都必须用名称进行定义，并且每个 @context 名称可以应用于子图内部的多个位置。例如：

1
type A @key(fields: "id") @context(name: "userContext") {
2
  id: ID!
3
  prop: String!
4
}
5

6
type B @key(fields: "id") @context(name: "userContext") {
7
  id: ID!
8
  prop: String!
9
}
10

11
type U @key(fields: "id") {
12
  id: ID!
13
  field (arg: String @fromContext(field: "$userContext { prop }")): String!
14
}

The @fromContext 指令用于设置从哪获取注解字段的值。该上下文必须已经使用 @context 指令进行了定义。

1
scalar ContextFieldValue;
2

3
directive @fromContext(field: ContextFieldValue) on ARGUMENT_DEFINITION;

在字段上必须使用 @fromContext 指令作为参数。其字段值——ContextFieldValue （标量）——必须包含定义的上下文名称和从上下文类型中选择字段的选项。

在 @fromContext 的 ContextFieldValue 中使用的选择语法类似于 GraphQL 字段选择语法，但有一些附加规则：

• 第一个元素必须是使用 @context 定义的一个上下文名称，前面加上 $ （例如，$myContext）。这是唯一可以被注解字段引用的上下文。
• 不能使用 @skip 和 @include 指令。
• 第二个元素必须是一个选择集，它可以解析为单个字段。
• 顶层数据类型条件不得相互重叠，以便字段可以解析为单个值。
• 在 ContextFieldValue 中引用的所有字段必须都在当前子图中表达。如果字段跨越多个子图引用，它们必须带有 @external 注释。
• 参数必须为可空。因为是按子图级进行验证，所以当合并子图时（比如当一个字段在一个子图中为可空，而在另一个子图中不可空时），所引用的字段可能会变成可空的。

当在多个地方设置相同的上下文值时，ContextFieldValue 必须将每个位置的每个类型解析为一个单一值，该值与参数类型相匹配。

有关使用 @context 和 @fromContext 的示例，请参阅 使用上下文在类型层级共享数据。