Logo
配置 Schema
配置 Schema使用多字段指令

使用多字段指令

多字段指令是一种可应用于多个字段（而非仅一个字段）的指令。启用后，所有指令都会新增一个参数 affectAdditionalFieldsUnderPos，用于指定需要应用该指令的其他字段的相对位置。

例如，在以下 query 中，指令 @strTranslate 仅应用于字段 content：

{
  posts {
    excerpt
    content @strTranslate
  }
}

要将指令 @strTranslate 同时应用于字段 excerpt，可在指令参数 affectAdditionalFieldsUnderPos 中传入值 [1]（1 为从指令 @strTranslate 到字段 excerpt 的相对位置）：

{
  posts {
    excerpt
    content
      @strTranslate(
        affectAdditionalFieldsUnderPos: [1]
      )
  }
}

可添加的字段数量没有限制。在以下 query 中，dateStr 也被纳入翻译范围：

{
  posts {
    dateStr
    excerpt
    content
      @strTranslate(
        affectAdditionalFieldsUnderPos: [1, 2]
      )
  }
}

指令本身自然作用的字段（如上述所有 query 中的 content）无需在参数中指定。

在上述 query 中，从指令 @strTranslate 到前面各字段的相对位置如下：

  • 位置 2：dateStr
  • 位置 1：excerpt
  • 位置 0：content <= 隐式，始终应用

使用场景

此功能主要有两种使用场景：

  1. 性能优化
  2. 扩展功能

性能优化

对于需要调用外部 API 的指令，请求次数越少，解析速度越快。

指令 @strTranslate 就是一个典型示例，它会连接 Google Translate API。通常，要翻译一批文章的 content 和 excerpt 字段，query 如下：

query {
  posts {
    excerpt @strTranslate
    content @strTranslate
  }
}

由于添加了两次 @strTranslate，该 query 会向 Google Translate API 发送两次请求（一次翻译所有 excerpt 的值，一次翻译所有 content 的值）。

借助 Multi-Field Directives 功能，以下 query 同样可以翻译 content 和 excerpt 两个字段的全部值，但只需向 Google Translate API 发送一次请求：

query {
  posts {
    excerpt
    content
      @strTranslate(
        affectAdditionalFieldsUnderPos: [1]
      )
  }
}

扩展功能

接收额外字段的指令可以提供附加的计算能力。

例如，指令 @export 通常用于导出单个字段的值，例如当前登录用户的姓名：

query GetLoggedInUserName {
  me {
    name @export(as: "userName")
  }
}

通过参数 affectAdditionalFieldsUnderPos，@export 可以接收多个字段，并将这些字段作为条目导出为一个字典：

query GetLoggedInUserNameAndSurname {
  me {
    name
    surname
      @export(
        as: "userProps"
        affectAdditionalFieldsUnderPos: [1]
      )
  }
}

@export 将在变量 $userProps 中生成以下值：

{
  "name": "Leo",
  "surname": "Loso"
}

配置

要在 GraphQL schema 中启用或禁用多字段指令，请前往设置页面的「Multi-Field Directives」模块，勾选或取消勾选 Enable multi-field directives? 复选框：

Multi-Field Directives 的设置
Multi-Field Directives 的设置

要在特定端点上启用或禁用多字段指令，请在对应 Schema Configuration 的「Multi-Field Directives」区块中选择所需选项：

Schema Configuration 中的 Multi-Field Directives
Schema Configuration 中的 Multi-Field Directives