Bases de GraphQL : types de schéma et d’objet

Apprenez-en davantage sur GraphQL, y compris ses types d’objets qui représentent le type d’objets que nous pouvons récupérer à partir de notre service et leurs champs.

Dans certains de nos articles précédents, nous avons discuté comment créer une API GraphQL dans Node.js et comment démarrer avec React et GraphQL. Dans l’article d’aujourd’hui, nous passerons un peu de temps à discuter de certains concepts fondamentaux des API GraphQL : le schéma GraphQL et ses types d’objets.

Pour rappel, GraphQL est un langage de requête permettant d’envoyer des requêtes aux API. Avec GraphQL, le client indique au serveur exactement ce dont il a besoin et le serveur répond avec les données demandées. Par exemple, supposons que nous puissions interroger le title et price champs sur un listing objet comme suit :

{
  listing {
    title
    price
  }
}

Cela pourrait renvoyer des données telles que les suivantes :

{
  "data": {
    "listing": {
      "title": "Beachfront condo...",
      "price": 50
    }
  }
}

S’il s’agissait d’une API avec laquelle nous travaillons, comment pourrions-nous savoir que le listing l’objet a le title et price propriétés? Est-ce que le listing L’objet a-t-il plus de propriétés que nous pouvons sélectionner ? C’est là que le Schéma GraphQL entre.

Chaque API GraphQL a un schéma qui décrit complètement toutes les données possibles que nous pouvons demander et constitue le modèle d’une API GraphQL. Lorsqu’une demande arrive, elle est validée par rapport à ce schéma et traitée en conséquence.

Au cœur de chaque schéma GraphQL se trouvent les types d’objetsqui représentent le type d’objets que nous pouvons récupérer à partir de notre service et les champs dont ils disposent.

Types d’objets

Pour notre exemple précédent ci-dessus, nous avions un listing type d’objet, qui contient title et price des champs. C’est ainsi qu’on pourrait définir le listing objet dans un schéma GraphQL :

type Listing {
  id: ID!
  title: String!
  address: String!
  price: Int!
}

Nous définissons un type d’objet GraphQL nommé Listing. Au sein de cet objet, il y a plusieurs propriétés :

• Un id propriété qui correspond à un GraphQL ID.
• title et address propriétés, toutes deux représentées sous forme de GraphQL String les types.
• UN price propriété caractérisée comme GraphQL Int.

Cette syntaxe est connue sous le nom de Langage de schéma GraphQL.

Dans un schéma GraphQL, il est possible d’établir des connexions entre différents types d’objets. Par exemple, le Listing le type d’objet peut comporter un tenant champ qui lui-même peut être représenté comme un autre type d’objet, tel que le User type d’objet.

type Listing {
  "..."
  tenant: User!
}

A l’inverse, le User Le type d’objet peut avoir une relation dans laquelle il contient un listing domaine, représentant du Listing type d’objet.

type User {
  "..."
  listing: Listing!
}

Ce qui précède illustre des connexions un à un, signifiant qu’une seule liste correspond à un utilisateur spécifique et vice versa. De plus, des connexions un à plusieurs peuvent être établies. Un exemple est le User type d’objet ayant un listings champ, qui donne un tableau de listes.

type User {
  "..."
  listings: [Listing!]!
}

Requête et mutation

Dans un schéma GraphQL, il existe deux types d’objets distincts nommés Query et Mutation. Un schéma GraphQL doit contenir un Query type, alors que l’inclusion d’un Mutation le type est facultatif.

Les deux Query et Mutation agir comme le points d’accès principaux pour toutes les interactions GraphQL. Le Query type décrit toutes les voies disponibles pour récupérer des donnéestandis que le Mutation type spécifie les entrées vers modifier les données.

Par exemple, nous pourrions concevoir un Query tapez pour récupérer un champ nommé listings. De même, un Mutation le type pourrait incorporer un deleteListing domaine qui attend un id paramètre.

type Query {
  listings: [Listing!]!
}

type Mutation {
  deleteListing(id: ID!): Listing!
}

Le listings requête et le deleteListing ci-dessus sont vus comme les deux variations de retour du Listing type d’objet.

Types scalaires

Dans GraphQL, lors de la définition de la structure de nos données, chaque attribut d’un objet finira par se résumer à une valeur fondamentale. Cette valeur fondamentale est représentée par ce que nous appelons types scalaires. Il s’agit de types de données élémentaires indivisibles : ils ne se décomposent pas en types plus spécifiques et n’ont pas d’attributs imbriqués.

Par défaut, GraphQL fournit une collection de types scalaires prédéfinis :

Booléen

Ceci représente un choix binaire de base et peut être soit true ou false.

Int

Désigne un nombre entier signé de 32 bits. Cela peut aller de petits entiers à des nombres entiers relativement grands, ce qui convient aux cas d’utilisation numérique les plus courants.

Flotter

Correspond à un chiffre à virgule flottante double précision signé. En termes plus simples, il représente des nombres décimaux qui peuvent être particulièrement utiles lorsqu’il s’agit de mesures, de valeurs monétaires ou d’autres calculs précis.

Chaîne

Reflète une séquence de caractères, codée au format UTF-8. Il est polyvalent et peut contenir n’importe quoi, des noms aux descriptions, voire des articles entiers.

IDENTIFIANT

Il s’agit d’un type scalaire spécial, principalement conçu pour signifier des identifiants uniques pour les objets. Bien que l’idée sous-jacente soit qu’ils ne sont pas principalement destinés à une interprétation humaine, en pratique, ils sont sérialisés de la même manière que String. Souvent, ce type aide à récupérer des entrées de données spécifiques ou à garantir la cohérence des données.

Types d’énumération

Types d’énumération, souvent appelés énumérations, sont des types scalaires uniques confinés à un ensemble prédéfini de valeurs. Par exemple, si nous devions ajouter un listingType attribuer à notre mentionné précédemment Listing objet et nous voulons nous assurer que cet attribut ne peut prendre que des valeurs spécifiques, nous utiliserions un enum taper:

enum ListingType {
  HOUSE
  APARTMENT
}

Listes

Bien que les objets, scalaires et énumérations représentent les types principaux, nous pouvons appliquer des modificateurs supplémentaires pour affecter leur comportement. Plus précisément, l’utilisation de crochets dans le langage de schéma GraphQL permet de définir les champs comme listes. Prenons cet exemple où nous introduisons un bookings attribut qui renvoie une liste comprenant les Booking type d’objet:

type Listing {
  "..."
  bookings: [Booking]
}

Observez la distinction entre les [Booking] notations et [Booking!]!. La présence de ! est un mécanisme dans GraphQL pour désigner les champs comme non nullable. Cela implique que le champ sera toujours résolu selon le type spécifié et ne renverra jamais de message. null valeur.

type Listing {
  "users will always be a non-empty list containing User type elements"
  users: [User!]!

  "bookings might be null, or individual elements in the bookings list might be null"
  bookings: [Booking]
}

Cette utilisation nuancée offre beaucoup de flexibilité et de précision lors de la conception de la structure des données dans GraphQL.

Arguments et types d’entrée

Dans GraphQL, les champs fonctionnent de la même manière que les fonctions des langages de programmation traditionnels, où ils peuvent accepter des arguments et renvoyer des valeurs basées sur ces entrées.

Considérons un scénario dans lequel nous souhaitons fournir plusieurs paramètres à un createListing Champ de mutation GraphQL pour générer un résultat souhaité (par exemple, pour créer une liste). Tout comme nous pouvons fournir plusieurs arguments à une fonction dans des langages comme JavaScript, nous pouvons faire de même avec un champ GraphQL.

type Mutation {
  createListing(
    id: ID!
    title: String!
    address: String!
    price: Int!
  ): Listing!
}

Une pratique largement adoptée dans des situations comme celle-ci consiste à utiliser types d’objets d’entrée. Dans la notation de schéma de GraphQL, ces types d’entrée ressemblent aux définitions d’objets standard mais sont préfixés par le input mot-clé, les distinguant des types d’objets normaux.

Par exemple, nous pouvons définir un createListing mutation qui impose un non nullable argument de CreateListingInput type d’entrée.

input CreateListingInput {
  id: ID!
  title: String!
  address: String!
  price: Int!
}

type Mutation {
  createListing(input: CreateListingInput!): Listing!
}

Cette structure rend non seulement le schéma plus lisible, mais simplifie également le processus d’extension ou de modification des paramètres d’entrée à l’avenir.

Conclure

GraphQL est un langage de requête polyvalent qui offre une grande flexibilité dans la demande et la manipulation de données. Sa structure basée sur un schéma garantit un contrat clair entre les clients et les serveurs, permettant au client d’avoir un contrôle précis sur les données auxquelles il souhaite accéder. Les types d’objets constituent la pierre angulaire de ce schéma facilitant la définition de diverses formes de données et leurs interactions.

Dans certains articles à venir, nous discuterons et couvrirons d’autres concepts fondamentaux de GraphQL tels que les fonctions de résolution, la pagination et la mise en cache.