Schema 的自定义功能

GraphQL 规范中提议的多项功能已在 Gato GraphQL 中实现，无需等待。

Schema 命名空间

如果 WooCommerce 和 Easy Digital Downloads 这两个插件都为 GraphQL API 实现了 Product 类型，那么由于类型冲突，我们将无法同时安装这两个插件。

Schema 命名空间通过为所有类型名称添加命名空间前缀，避免 schema 中的冲突。因此，类型 Product 将分别变为 Woo_Product 和 EDD_Product，这些类型可以添加到同一个 schema 中。

下图展示了一个带命名空间的 schema，其中类型 Event 和 Location 添加了前缀 EM_ 以避免名称冲突：

Namespaced schema

全局字段

全局字段是可以在 GraphQL schema 中每个类型下访问的字段（只需定义一次）。

GraphQL schema 公开了 Post、User 和 Comment 等类型，以及每个类型可用的字段，例如 Post.title、User.name 和 Comment.responses。这些字段处理"数据"，因为它们从实体中检索特定的数据片段。

Gato GraphQL 还额外提供了另一种字段：提供"功能"而非数据的字段。

全局字段的一些示例：

_not
_if
_equals
_isEmpty
_echo
_sprintf
_arrayItem
_arrayAddItem
_arrayUnique
以及更多

功能字段对于获取存储在 WordPress 外部的数据以及在检索后对数据进行处理非常有用，允许我们以任何所需方式转换字段值，并赋予我们强大的数据导入/导出能力。

功能字段不属于 Post 或 User 等特定类型，而是属于 schema 中的所有类型。这就是为什么在 Gato GraphQL 中，这些字段以"全局字段"的名称以独特方式处理。

Field to input

在同一个 query 中获取字段的值、对其进行处理，然后将其作为输入传递给另一个字段。

query {
  posts {
    excerpt
 
    # Referencing previous field with name "excerpt"
    isEmptyExcerpt: _isEmpty(value: $__excerpt)
 
    # Referencing previous field with alias "isEmptyExcerpt"
    isNotEmptyExcerpt: _not(value: $__isEmptyExcerpt)
  }
}

可组合指令

通常情况下，指令无法应用于某个字段，因为其输入与字段的输出类型不同。例如，指令 @strUpperCase 接收字符串作为输入，因此无法应用于返回字符串数组的 User.capabilities 字段。

可组合指令允许一个指令扩展另一个指令以修改其行为或弥补不足。这消除了仅为更改输入或返回类型而复制字段或指令的需要，避免了冗余膨胀。

在此 query 中，指令 @underEachArrayItem 遍历字符串数组，并对每个元素应用嵌套指令 @strUpperCase，从而解决类型不匹配的问题：

query {
  users {
    capabilities
      @underEachArrayItem
        @strUpperCase
  }
}

多字段指令

将指令应用于多个字段（而不仅仅是一个字段），以提升性能并扩展使用场景。

启用后，所有指令都会添加一个参数 affectAdditionalFieldsUnderPos，可以在其中指定要应用指令的额外字段的相对位置。

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

query {
  posts {
    excerpt
    content @strTranslate
  }
}

字段 excerpt 也可以应用指令 @strTranslate，方法是添加值为 [1] 的指令参数 affectAdditionalFieldsUnderPos（1 是字段 excerpt 相对于指令 @strTranslate 的相对位置）：

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

基于字段和指令的版本控制

独立于 schema 对字段和指令进行版本管理。

无需演进整个 schema（这需要修改已更改字段或指令的名称），我们可以：

在同一字段或指令名称下保留不同的实现
使用语义化版本控制在标签下公开旧版实现
通过字段/指令参数 versionConstraint 访问特定版本

主动反馈

使用顶级条目 extensions 在 query 响应中发送有关弃用和警告的数据。

弃用： 弃用信息不仅在内省时返回，还会在涉及弃用字段的 query 执行时返回。
警告： 警告是可视为非阻塞的问题，即它们可以改善 query 但不会中断它。

例如，以下 query 使用相同的动态变量名 "prop" 导出两个字段，这将产生一个警告：

query {
  posts {
    excerpt @export(as: "prop")
    content @export(as: "prop")
  }
}

响应将在 extensions 下包含 warnings 部分及相应消息：

{
  "extensions": {
    "warnings": [
      {
        "message": "Dynamic variable with name 'props' had already been set, had its value overridden",
        "locations": [
          {
            "line": 4,
            "column": 25
          }
        ]
      }
    ]
  },
  "data": {
    "posts": {
      "excerpt": "Hello world!",
      "Content": "<p>Hello world!</p>"
    }
  }
}

功能：