合约参考

规则@tag和合约

有效的@tag位置

在第一个联邦和第二个联邦中，您可以应用标签到以下 schema 元素来筛选您的合约架构：

• 对象、接口和联合类型定义
• 对象类型的字段
  • 第一个联邦不支持为接口类型字段标签
  • 在第一个联邦中，您仍然可以通过给接口定义添加标签或确保实现接口字段的对象字段被删除，使接口字段不可访问。

仅在第二个联邦中，您还可以将这些应用于以下

• 接口类型的字段
• 枚举类型及其值
• 输入类型及其字段
• 自定义标量类型的定义
• 字段的参数，但不能是指令参数

有效的@tag名称

• @tag名称可以包含字母数字字符（a-z、A-Z、0-9），以及连字符（-）和正斜杠（/）。
• 每个标签名称不能超过128个字符。

1
type User {
2
  id: ID!
3
  name: String! @tag(name: "a/b/c/1-2-3")
4
}

依赖的 @tag

• 当你对对象或接口类型的定义进行标记时，GraphOS会自动将该标记应用到该类型的所有字段上：

  GraphQL

  1
  type InternalUser @tag(name: "internal") {
  2
    id: ID! # Also considered to have @tag(name: "internal")
  3
  }

  拷贝

• 当对对象、接口或联合类型的定义进行标记时，应始终将相同标记应用到返回该类型的每个字段上：

  GraphQL

  1
  type BillingAccount @tag(name: "internal") {
  2
    id: ID!
  3
    acctNumber: String!
  4
  }
  5
  
  6
  type Query {
  7
    billingAccounts: [BillingAccount!]! @tag(name: "internal")
  8
  }

  拷贝

  ⚠️ 注意

  如果您不这样做，可能会出现合同排除某个类型，同时包括返回该类型的字段的情况。这将产生无效的合同架构。

• 如果合同排除了实现接口或作为联合体一部分的对象：

  • 只要至少有一个相关联的对象类型仍然存在，则合同无需排除返回该接口或联合的架构字段：

    GraphQL

    1
    # Two object types implement this interface.
    2
    interface Identity {
    3
      id: ID!
    4
      name: String!
    5
    }
    6
    
    7
    # If this implementing type is excluded...
    8
    type InternalUser implements Identity @tag(name: "internal") {
    9
      id: ID!
    10
      name: String!
    11
    }
    12
    
    13
    # ...but this implementing type remains...
    14
    type ExternalUser implements Identity {
    15
      id: ID!
    16
      name: String!
    17
    }
    18
    
    19
    type Query {
    20
      # ...then this field doesn't need to be excluded.
    21
      currentIdentity: Identity
    22
    }

    拷贝

  • 然而，如果子图通过返回排除类型对象解决其中一个字段，则在路由器中发生运行时错误，并且操作失败。

过滤的特殊情况

• 如果合同定义了一个包含的@tags的列表，任何没有包含标记的对象或接口类型在合同架构中仍然包括，如果至少有一个其字段是包含的：

  GraphQL

  1
  # This type definition is included because one if its fields is included.
  2
  type User {
  3
    id: ID! @tag(name: "includeMe")
  4
  }

  拷贝

• 如果合同排除了对象或接口类型的每个字段，整个类型定义将排除在合同架构之外：

  GraphQL

  1
  # This object type is excluded because all its fields are excluded.
  2
  type User {
  3
    id: ID! @tag(name: "excludeMe")
  4
  }

  拷贝

  ⚠️ 注意

  如果任何返回排除类型的字段被包含，则可能会产生无效的合同架构。

• 如果合同排除了联合类型中包含的每个对象类型，整个联合类型定义将排除在合同架构之外：

  GraphQL

  1
  # This union type is excluded because all its possible types are excluded.
  2
  union Media = Book | Movie
  3
  
  4
  type Book @tag(name: "excludeMe") {
  5
    title: String!
  6
  }
  7
  
  8
  type Movie @tag(name: "excludeMe") {
  9
    title: String!
  10
  }

  拷贝

  ⚠️ 注意

  如果包含任何返回排除联合类型的字段，则可能会生成一个无效的合同模式。

• 即使标记了，合同无法排除以下任何内容：

  • 内置 标量（Int, Float等。）
  • 内置 指令（@skip, @include等。）
  • 应用于 类型系统位置的 自定义指令（查看列表）

• 合同可以排除用于计算字段的对象字段，而不会导致运行时错误。

错误

GraphOS在创建或更新合同模式时可能会遇到以下错误。错误描述包括创建过程中发生错误的位置：