使用内置的GraphQL指令

指令是GraphQL最好，也是最不言而喻的功能之一。

让我们探索使用GraphQL的内置架构和操作指令，所有符合GraphQL规格API都必须实现。如果您使用动态前端，它们非常有用，因为您可以根据用户与用户交互的方式进行控制来减少响应有效载荷。

指令概述

让我们想象一个应用程序，您可以选择自定义表中显示的列。如果隐藏两个或三列，那么实际上无需为这些单元格获取数据。但是，使用GraphQL指令，我们可以选择包括或跳过这些字段。

GraphQL规范定义了什么是指令以及可以使用的位置。具体而言，指令可以由消费者操作（例如查询）以及基础架构本身使用。或者，简单地说，指令要么基于模式或操作。生成架构时使用架构指令，并且执行查询时运行指令运行。

简而言之，指令可用于元数据，运行时提示，运行时解析（例如以特定格式返回日期）和扩展描述（如弃用）。

四种指令

GraphQL拥有规范工作草案中定义的四个主要指令，其中一个未发行为工作草案。

• @包括
• @跳过
• @Deprecated
• @specifiedby（工作草案）

如果您密切关注GraphQL，您还会注意到，您可以在今天可以尝试的JavaScript实现合并了两个其他指令 - @Stream和@defer。当社区在现实世界应用中对其进行测试时，这些都不是官方规格的一部分。

@包括

@Include指令符合其名称，允许我们通过传递IF参数来有条件地包括字段。由于有条件的条件，因此在查询中使用变量检查真实性是有意义的。

例如，如果以下示例中的变量是真实的，则名称字段将包含在查询响应中。

查询getusers（$ dishame：boolean）{
  用户{
    ID
    名称@Include（如果：$ dispayame）
  }
}

相反，我们可以选择不将变量$与查询一起传递为false的变量$通过将字段包含在内。我们还可以指定$ showeame变量的默认值，因此无需在每个请求中传递它：

查询getusers（$ dishame：boolean = true）{
  用户{
    ID
    名称@Include（如果：$ dispayame）
  }
}

@跳过

我们可以用仅此功能来表达同样的事情，但是使用@SKIP指令。如果价值是真实的，那么它将像您期望的那样跳过该领域。

查询getusers（$ hidename：boolean）{
  用户{
    ID
    名称@skip（如果：$ hidename）
  }
}

尽管这适用于单个字段，但有时我们可能希望包括或跳过多个字段。我们可以在这样的多行中复制@include和@skip的用法：

查询getusers（$ include fields：boolean）{
  用户{
    ID
    名称@include（如果：$ include fields）
    电子邮件@include（如果：$ include fields）
    角色@include（如果：$ include fields）
  }
}

@skip和@include指令均可在字段，片段蔓延和内联片段上使用，这意味着我们可以做其他事情，例如使用Inline Fragments：

查询getusers（$ dubludefields：boolean）{
  用户{
    ID
    ...在用户@skip上（如果：$ dubludefields）{
      姓名
      电子邮件
      角色
    }
  }
}

如果已经定义了片段，当我们将片段扩展到查询中时，我们也可以使用@skip和@include：

用户上的fragment用户{
  姓名
  电子邮件
  角色
}

查询getusers（$ dubludefields：boolean）{
  用户{
    ID
    ...用户@skip（如果：$ dubludefields）
  }
}

@Deprecated

@deprectated指令仅出现在模式中，并且不是用户所提供的作为我们上面看到的查询的一部分。相反，@deprected指令是由维护GraphQL API架构的开发人员指定的。

作为用户，如果我们尝试获取架构中已弃用的字段，我们将收到这样的警告，提供上下文帮助。

为了标记不推翻的字段，我们需要在架构定义语言（SDL）中使用@Deprectated指令，并在此类参数中传递原因：

键入用户{
  id：id！
  标题：字符串@DepRecated（原因：“使用名称代替”）
  名称：字符串！
  电子邮件：字符串！
  角色：角色
}

如果我们将其与@include指令配对，则可以根据查询变量有条件地获取不弃用的字段：

用户上的fragment用户{
  标题@include（如果：$ incresseprecatedFields）
  姓名
  电子邮件
  角色
}

查询getusers（$ inccesseprecatedFields：boolean！= false）{
  用户{
    ID
    ...用户
  }
}

@specifiedby

@specifiedby是指令的第四个，目前是工作草案的一部分。它设置为自定义标量实现，并采用一个URL参数，该参数应指向标量的规范。

例如，如果我们为电子邮件地址添加自定义标量，我们将希望将URL传递给我们用作的正则条件的规范。使用最后一个示例和RFC＃822中定义的建议，将在架构中定义了emailaddress的标量：

标量emailaddress @specifiedby（url：“ https：//www.w3.org/protocols/rfc822/”）

建议定制指令具有前缀的名称，以防止与其他附加指令发生碰撞。如果您正在寻找一个示例自定义指令，以及它的创建方式，请查看GraphQl公共模式。这是一个自定义的GraphQL指令，具有代码和模式优先的支持，用于注释哪些API可以在公共场合消费。

总结

因此，这是GraphQL指令的高级外观。同样，我相信指示是一种被其他GraphQL功能所掩盖的无名英雄。我们已经对GraphQL模式有了很大的控制，指令为我们提供了更细粒度的控制，以便从查询中获得我们想要的东西。这就是这种效率，这使GraphQl API如此快速，最终更友好地使用。

而且，如果您要构建GraphQl API，请确保将这些指令包括在内省查询中。.拥有它们不仅使开发人员获得额外控制的好处，而且可以使总体更好的开发人员体验。试想一下，正确地@deprecate字段将有多大帮助，以便开发人员知道该怎么做，而不需要离开代码？这本身就是强大的。

标题图形由IsabelGonçalves在Unsplash上​​提供

以上是使用内置的GraphQL指令的详细内容。更多信息请关注PHP中文网其他相关文章！