使用可组合指令

让一个指令能够修改另一个指令的行为。

此功能使我们能够在原本因类型不匹配而无法使用的情况下使用某个指令（即当一个指令因其输入与字段输出不同而无法应用于该字段时）。

例如，字段 capabilities 返回 [String]（字符串数组），而指令 @strUpperCase 接收 String。因此，执行以下 query 会因类型不匹配而返回错误：

query {
  user(by: {id: 1}) {
    capabilities @strUpperCase
  }
}

使用可组合指令，我们可以借助指令 @underEachArrayItem（它会迭代元素数组，并将其嵌套指令应用于每个元素）在 @strUpperCase 执行前做好准备，使其接收单个元素（String 类型）。

上面的 query 可以这样实现：

query {
  user(by: {id: 1}) {
    capabilities
      @underEachArrayItem
        @strUpperCase
  }
}

元指令

每个元指令可以同时影响（或"嵌套"）多个指令。受影响的指令通过参数 affectDirectivesUnderPos 来指定，该参数接收一个正整数数组，每个整数定义受影响指令的相对位置。

默认情况下，参数 affectDirectivesUnderPos 的默认值为 [1]，意味着它将影响紧邻其后的指令。

在下面的示例中：

@underEachArrayItem 是元指令
@strTranslate 嵌套在 @underEachArrayItem 下（隐式默认值 affectDirectivesUnderPos: [1]）

{
  someField
    @underEachArrayItem
      @strTranslate
}

在下面的示例中，我们改为：

@strTranslate 和 @strUpperCase 嵌套在 @underEachArrayItem 下（由参数 affectDirectivesUnderPos 中的相对位置 [1, 2] 指定）

{
  someField
    @underEachArrayItem(affectDirectivesUnderPos: [1, 2])
      @strTranslate
      @strUpperCase
}

元指令也可以嵌套在元指令中。

在下面的示例中：

@underEachArrayItem 是最顶层的元指令
@underJSONObjectProperty 嵌套在 @underEachArrayItem 下
@strUpperCase 嵌套在 @underJSONObjectProperty 下

query UppercaseEntriesInsideObject {
  entries: _echo(value: [
    {
      text: "Hello my friends"
    },
    {
      text: "How do you like this software so far?"
    }
  ])
   @underEachArrayItem
      @underJSONObjectProperty(by: { key: "text" })
        @strUpperCase
  }

配置

要在 GraphQL schema 中启用或禁用可组合指令，请前往设置页面的「Composable Directives」模块，勾选或取消勾选 Enable composable directives? 复选框：

要在特定端点启用或禁用可组合指令，请在对应 Schema Configuration 的「Composable Directives」块中选择所需选项：

Schema Configuration 中的 Composable Directives

​元指令

​配置

元指令

配置