Travailler avec des directives GraphQL intégrées

Les directives sont l'une des caractéristiques des meilleures - et les plus tacites de GraphQL.

Explorons le travail avec les directives de schéma et d'opération intégrées de GraphQL que toutes les API conformes aux spécifications GraphQL doivent implémenter. Ils sont extrêmement utiles si vous travaillez avec un frontal dynamique, car vous avez le contrôle pour réduire la charge utile de réponse en fonction de ce avec quoi l'utilisateur interagit.

Un aperçu des directives

Imaginons une application où vous avez la possibilité de personnaliser les colonnes affichées dans un tableau. Si vous cachez deux ou trois colonnes, il n'est vraiment pas nécessaire de récupérer les données de ces cellules. Avec les directives GraphQL, cependant, nous pouvons choisir d'inclure ou de sauter ces champs.

La spécification GraphQL définit ce que sont les directives et l'emplacement de l'endroit où ils peuvent être utilisés. Plus précisément, les directives peuvent être utilisées par les opérations de consommation (comme une requête) et par le schéma sous-jacent lui-même. Ou, en termes simples, les directives sont basées sur le schéma ou le fonctionnement. Les directives de schéma sont utilisées lorsque le schéma est généré et que les directives d'opération s'exécutent lorsqu'une requête est exécutée.

En bref, les directives peuvent être utilisées aux fins des métadonnées, des conseils d'exécution, de l'analyse d'exécution (comme des dates de retour dans un format spécifique) et des descriptions étendues (comme obsolètes).

Quatre types de directives

GraphQL possède quatre directives principales telles que définies dans le projet de travail des spécifications, dont l'une n'établies comme un projet de travail.

• @inclure
• @sauter
• @Deprecated
• @SpecifiedBy (Draft de travail)

Si vous suivez de près GraphQL, vous remarquerez également que deux directives supplémentaires ont été fusionnées à l'implémentation JavaScript que vous pouvez essayer aujourd'hui - @Stream et @Defer. Ceux-ci ne font pas encore partie des spécifications officielles tandis que la communauté les teste dans des applications réelles.

@inclure

La directive @include, fidèle à son nom, nous permet d'inclure conditionnelle des champs en passant un argument IF. Puisqu'il est conditionnel, il est logique d'utiliser une variable dans la requête pour vérifier la vérité.

Par exemple, si la variable dans les exemples suivants est la vérité, le champ Nom sera inclus dans la réponse de la requête.

 Query GetUsers ($ closeDame: Boolean) {
  utilisateurs {
    identifiant
    nom @include (si: $ closedame)
  }
}

À l'inverse, nous pouvons choisir de ne pas inclure le champ en passant la variable $ closeDame comme faux avec la requête. Nous pouvons également spécifier une valeur par défaut pour la variable $ closedame, il n'est donc pas nécessaire de le transmettre à chaque demande:

 Query GetUsers ($ closedame: boolean = true) {
  utilisateurs {
    identifiant
    nom @include (si: $ closedame)
  }
}

@sauter

Nous pouvons exprimer le même genre de chose avec JUST DID, mais en utilisant la directive @skip à la place. Si la valeur est la vraie, alors elle peut, comme vous pouvez vous y attendre, sauter ce champ.

 Query GetUsers ($ Hidename: Boolean) {
  utilisateurs {
    identifiant
    nom @skip (si: $ Hidename)
  }
}

Bien que cela fonctionne très bien pour les champs individuels, il y a des moments où nous pouvons vouloir inclure ou sauter plus d'un champ. Nous pourrions dupliquer l'utilisation de @include et @skip sur plusieurs lignes comme celle-ci:

 Query GetUsers ($ includeFields: booléen) {
  utilisateurs {
    identifiant
    nom @include (si: $ inclusefields)
    Email @include (si: $ inclusefields)
    rôle @include (si: $ inclusefields)
  }
}

Les directives @skip et @include peuvent être utilisées sur les champs, les écarts de fragments et les fragments en ligne, ce qui signifie que nous pouvons faire autre chose, comme celui-ci à la place avec des fragments en ligne:

 Query GetUsers ($ exclusefields: booléen) {
  utilisateurs {
    identifiant
    ... sur l'utilisateur @skip (if: $ exclusefields) {
      nom
      e-mail
      rôle
    }
  }
}

Si un fragment est déjà défini, nous pouvons également utiliser @skip et @include lorsque nous réparons un fragment dans la requête:

 Fragment User sur l'utilisateur {
  nom
  e-mail
  rôle
}

Query GetUsers ($ exclusefields: booléen) {
  utilisateurs {
    identifiant
    ... utilisateur @skip (si: $ exclusefields)
  }
}

@Deprecated

La directive @Deprecated n'apparaît que dans le schéma et n'est pas quelque chose qu'un utilisateur fournirait dans le cadre d'une requête comme nous l'avons vu ci-dessus. Au lieu de cela, la directive @Deprecated est spécifiée par le développeur conservant le schéma API GraphQL.

En tant qu'utilisateur, si nous essayons de récupérer un champ qui a été obsolète dans le schéma, nous recevrons un avertissement comme celui-ci qui fournit une aide contextuelle.

Pour marquer un champ déprécié, nous devons utiliser la directive @deprecated dans le langage de définition du schéma (SDL), passant une raison à l'intérieur des arguments, comme ceci:

 Tapez l'utilisateur {
  je l'ai fait!
  Titre: String @Deprecated (Raison: "Utilisez le nom à la place")
  Nom: String!
  Email: String!
  rôle: rôle
}

Si nous le juridions avec la directive @include, nous pourrions réapprovisionner conditionnellement le champ obsolète en fonction d'une variable de requête:

 Fragment User sur l'utilisateur {
  titre @include (si: $ inclus
  nom
  e-mail
  rôle
}

requête getUsers ($ inclus
  utilisateurs {
    identifiant
    ...Utilisateur
  }
}

@SpecifiedBy

@SpecifiedBy est le quatrième des directives et fait actuellement partie du projet de travail. Il doit être utilisé par les implémentations scalaires personnalisées et prendre un argument URL qui devrait indiquer une spécification pour le scalaire.

Par exemple, si nous ajoutons un scalaire personnalisé pour l'adresse e-mail, nous voulons passer l'URL à la spécification pour le regex que nous utilisons dans le cadre de cela. En utilisant le dernier exemple et la proposition définie dans RFC # 822, un scalaire pour EmailAddress serait défini dans le schéma comme tel:

 Scalar EmailAddress @SpecifiedBy (URL: "https://www.w3.org/protocols/rfc822/")

Il est recommandé que les directives personnalisées aient un nom préfixé pour empêcher les collisions avec d'autres directives supplémentaires. Si vous recherchez un exemple de directive personnalisée et comment il est créé, jetez un œil au schéma public GraphQL. Il s'agit d'une directive GraphQL personnalisée qui a à la fois un support de code et de schéma d'abord pour annotation, laquelle d'une API peut être consommée en public.

Emballage

C'est donc un regard de haut niveau sur les directives GraphQL. Encore une fois, je crois que les directives sont une sorte de héros méconnu qui est éclipsé par d'autres fonctionnalités GraphQL. Nous avons déjà beaucoup de contrôle avec le schéma GraphQL, et les directives nous donnent un contrôle encore plus fin pour obtenir exactement ce que nous voulons des requêtes. C'est le genre d'efficacité et cela rend l'API GraphQL si rapide et finalement plus convivial à travailler.

Et si vous construisez une API GraphQL, assurez-vous d'inclure ces directives à la requête d'introspection. Pensez-vous à quel point il serait utile de correctement @Deprecate Fields afin que les développeurs sachent quoi faire sans jamais avoir besoin de quitter le code? C'est puissant en soi.

Graphique en tête grâce à Isabel Gonçalves sur Unsplash

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!