Conception de schémas GraphQL : Patrons évolutifs pour les API globales

GraphQL s'est imposé comme une alternative puissante aux API REST traditionnelles, offrant aux clients la flexibilité de demander précisément les données dont ils ont besoin. Cependant, à mesure que votre API GraphQL gagne en complexité et en portée – en particulier lorsqu'elle dessert un public mondial avec des exigences de données diverses – une conception de schéma soignée devient cruciale pour la maintenabilité, l'évolutivité et la performance. Cet article explore plusieurs patrons de conception de schémas GraphQL évolutifs pour vous aider à construire des API robustes capables de gérer les exigences d'une application mondiale.

L'importance d'une conception de schéma évolutive

Un schéma GraphQL bien conçu est le fondement d'une API réussie. Il dicte la manière dont les clients peuvent interagir avec vos données et services. Une mauvaise conception de schéma peut entraîner un certain nombre de problèmes, notamment :

• Goulots d'étranglement des performances : Des requêtes et des résolveurs inefficaces peuvent surcharger vos sources de données et ralentir les temps de réponse.
• Problèmes de maintenabilité : Un schéma monolithique devient difficile à comprendre, à modifier et à tester à mesure que votre application grandit.
• Vulnérabilités de sécurité : Des contrôles d'accès mal définis peuvent exposer des données sensibles à des utilisateurs non autorisés.
• Évolutivité limitée : Un schéma fortement couplé rend difficile la distribution de votre API sur plusieurs serveurs ou équipes.

Pour les applications mondiales, ces problèmes sont amplifiés. Différentes régions peuvent avoir des exigences de données, des contraintes réglementaires et des attentes de performance différentes. Une conception de schéma évolutive vous permet de relever ces défis efficacement.

Principes clés d'une conception de schéma évolutive

Avant de nous plonger dans des patrons spécifiques, décrivons quelques principes clés qui devraient guider la conception de votre schéma :

• Modularité : Décomposez votre schéma en modules plus petits et indépendants. Cela facilite la compréhension, la modification et la réutilisation des parties individuelles de votre API.
• Composabilité : Concevez votre schéma de manière à ce que différents modules puissent être facilement combinés et étendus. Cela vous permet d'ajouter de nouvelles fonctionnalités sans perturber les clients existants.
• Abstraction : Masquez la complexité de vos sources de données et services sous-jacents derrière une interface GraphQL bien définie. Cela vous permet de changer votre implémentation sans affecter les clients.
• Cohérence : Maintenez une convention de nommage, une structure de données et une stratégie de gestion des erreurs cohérentes dans tout votre schéma. Cela facilite l'apprentissage et l'utilisation de votre API par les clients.
• Optimisation des performances : Tenez compte des implications sur les performances à chaque étape de la conception du schéma. Utilisez des techniques comme les data loaders et les alias de champs pour minimiser le nombre de requêtes à la base de données et de requêtes réseau.

Patrons de conception de schémas évolutifs

Voici plusieurs patrons de conception de schémas évolutifs que vous pouvez utiliser pour construire des API GraphQL robustes :

1. Schema Stitching

Le schema stitching vous permet de combiner plusieurs API GraphQL en un schéma unique et unifié. C'est particulièrement utile lorsque différentes équipes ou services sont responsables de différentes parties de vos données. C'est comme avoir plusieurs mini-API et les joindre via une API 'gateway' (passerelle).

Comment ça marche :

1. Chaque équipe ou service expose sa propre API GraphQL avec son propre schéma.
2. Un service de passerelle central utilise des outils de schema stitching (comme Apollo Federation ou GraphQL Mesh) pour fusionner ces schémas en un seul schéma unifié.
3. Les clients interagissent avec le service de passerelle, qui achemine les requêtes vers les API sous-jacentes appropriées.

Exemple :

Imaginez une plateforme de e-commerce avec des API séparées pour les produits, les utilisateurs et les commandes. Chaque API a son propre schéma :

  
    # API Produits
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }

    # API Utilisateurs
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    # API Commandes
    type Order {
      id: ID!
      userId: ID!
      productId: ID!
      quantity: Int!
    }

    type Query {
      order(id: ID!): Order
    }
  

Le service de passerelle peut assembler ces schémas pour créer un schéma unifié :

  
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Order {
      id: ID!
      user: User! @relation(field: "userId")
      product: Product! @relation(field: "productId")
      quantity: Int!
    }

    type Query {
      product(id: ID!): Product
      user(id: ID!): User
      order(id: ID!): Order
    }
  

Remarquez comment le type Order inclut maintenant des références à User et Product, même si ces types sont définis dans des API séparées. Ceci est réalisé grâce à des directives de schema stitching (comme @relation dans cet exemple).

Avantages :

• Propriété décentralisée : Chaque équipe peut gérer ses propres données et API de manière indépendante.
• Évolutivité améliorée : Vous pouvez faire évoluer chaque API indépendamment en fonction de ses besoins spécifiques.
• Complexité réduite : Les clients n'ont besoin d'interagir qu'avec un seul point de terminaison d'API.

Considérations :

• Complexité : Le schema stitching peut ajouter de la complexité à votre architecture.
• Latence : L'acheminement des requêtes via le service de passerelle peut introduire de la latence.
• Gestion des erreurs : Vous devez mettre en œuvre une gestion des erreurs robuste pour faire face aux pannes dans les API sous-jacentes.

2. Fédération de schémas (Schema Federation)

La fédération de schémas est une évolution du schema stitching, conçue pour remédier à certaines de ses limitations. Elle fournit une approche plus déclarative et standardisée pour composer des schémas GraphQL.

Comment ça marche :

1. Chaque service expose une API GraphQL et annote son schéma avec des directives de fédération (par ex., @key, @extends, @external).
2. Un service de passerelle central (utilisant Apollo Federation) utilise ces directives pour construire un supergraphe – une représentation de l'ensemble du schéma fédéré.
3. Le service de passerelle utilise le supergraphe pour acheminer les requêtes vers les services sous-jacents appropriés et résoudre les dépendances.

Exemple :

En utilisant le même exemple de e-commerce, les schémas fédérés pourraient ressembler à ceci :

  
    # API Produits
    type Product @key(fields: "id") {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }

    # API Utilisateurs
    type User @key(fields: "id") {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    # API Commandes
    type Order {
      id: ID!
      userId: ID!
      productId: ID!
      quantity: Int!
      user: User! @requires(fields: "userId")
      product: Product! @requires(fields: "productId")
    }

    extend type Query {
      order(id: ID!): Order
    }
  

Remarquez l'utilisation des directives de fédération :

• @key : Spécifie la clé primaire pour un type.
• @requires : Indique qu'un champ nécessite des données d'un autre service.
• @extends : Permet à un service d'étendre un type défini dans un autre service.

Avantages :

• Composition déclarative : Les directives de fédération facilitent la compréhension et la gestion des dépendances de schéma.
• Performances améliorées : Apollo Federation optimise la planification et l'exécution des requêtes pour minimiser la latence.
• Sécurité des types améliorée : Le supergraphe garantit que tous les types sont cohérents entre les services.

Considérations :

• Outillage : Nécessite l'utilisation d'Apollo Federation ou d'une implémentation de fédération compatible.
• Complexité : Peut être plus complexe à mettre en place que le schema stitching.
• Courbe d'apprentissage : Les développeurs doivent apprendre les directives et les concepts de la fédération.

3. Conception de schéma modulaire

La conception de schéma modulaire consiste à décomposer un grand schéma monolithique en modules plus petits et plus gérables. Cela facilite la compréhension, la modification et la réutilisation des parties individuelles de votre API, même sans recourir à des schémas fédérés.

Comment ça marche :

1. Identifiez les frontières logiques au sein de votre schéma (par ex., utilisateurs, produits, commandes).
2. Créez des modules séparés pour chaque frontière, en définissant les types, les requêtes et les mutations liés à cette frontière.
3. Utilisez des mécanismes d'import/export (en fonction de votre implémentation de serveur GraphQL) pour combiner les modules en un seul schéma unifié.

Exemple (avec JavaScript/Node.js) :

Créez des fichiers séparés pour chaque module :

  
    // users.graphql
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    // products.graphql
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }
  

Ensuite, combinez-les dans votre fichier de schéma principal :

  
    // schema.js
    const { makeExecutableSchema } = require('graphql-tools');
    const { typeDefs: userTypeDefs, resolvers: userResolvers } = require('./users');
    const { typeDefs: productTypeDefs, resolvers: productResolvers } = require('./products');

    const typeDefs = [
      userTypeDefs,
      productTypeDefs,
      ""
    ];

    const resolvers = {
      Query: {
        ...userResolvers.Query,
        ...productResolvers.Query,
      }
    };

    const schema = makeExecutableSchema({
      typeDefs,
      resolvers,
    });

    module.exports = schema;
  

Avantages :

• Maintenabilité améliorée : Les modules plus petits sont plus faciles à comprendre et à modifier.
• Réutilisabilité accrue : Les modules peuvent être réutilisés dans d'autres parties de votre application.
• Meilleure collaboration : Différentes équipes peuvent travailler sur différents modules de manière indépendante.

Considérations :

• Surcharge : La modularisation peut ajouter une certaine surcharge à votre processus de développement.
• Complexité : Vous devez définir soigneusement les frontières entre les modules pour éviter les dépendances circulaires.
• Outillage : Nécessite l'utilisation d'une implémentation de serveur GraphQL qui prend en charge la définition de schéma modulaire.

4. Types Interface et Union

Les types Interface et Union vous permettent de définir des types abstraits qui peuvent être implémentés par plusieurs types concrets. C'est utile pour représenter des données polymorphes – des données qui peuvent prendre différentes formes selon le contexte.

Comment ça marche :

• Définissez un type interface ou union avec un ensemble de champs communs.
• Définissez des types concrets qui implémentent l'interface ou sont membres de l'union.
• Utilisez le champ __typename pour identifier le type concret à l'exécution.

Exemple :

  
    interface Node {
      id: ID!
    }

    type User implements Node {
      id: ID!
      name: String!
      email: String!
    }

    type Product implements Node {
      id: ID!
      name: String!
      price: Float!
    }

    union SearchResult = User | Product

    type Query {
      node(id: ID!): Node
      search(query: String!): [SearchResult!]!
    }
  

Dans cet exemple, User et Product implémentent tous deux l'interface Node, qui définit un champ id commun. Le type union SearchResult représente un résultat de recherche qui peut être soit un User, soit un Product. Les clients peuvent interroger le champ `search` puis utiliser le champ `__typename` pour déterminer quel type de résultat ils ont reçu.

Avantages :

• Flexibilité : Permet de représenter des données polymorphes de manière sûre au niveau des types.
• Réutilisation du code : Réduit la duplication de code en définissant des champs communs dans les interfaces et les unions.
• Interrogations améliorées : Facilite pour les clients l'interrogation de différents types de données à l'aide d'une seule requête.

Considérations :

• Complexité : Peut ajouter de la complexité à votre schéma.
• Performance : La résolution des types interface et union peut être plus coûteuse que la résolution des types concrets.
• Introspection : Nécessite que les clients utilisent l'introspection pour déterminer le type concret à l'exécution.

5. Patron de connexion (Connection Pattern)

Le patron de connexion est une manière standard d'implémenter la pagination dans les API GraphQL. Il fournit un moyen cohérent et efficace de récupérer de grandes listes de données par morceaux.

Comment ça marche :

• Définissez un type de connexion avec les champs edges et pageInfo.
• Le champ edges contient une liste d'arêtes (edges), chacune contenant un champ node (la donnée réelle) et un champ cursor (un identifiant unique pour le nœud).
• Le champ pageInfo contient des informations sur la page actuelle, comme s'il y a d'autres pages et les curseurs pour les premier et dernier nœuds.
• Utilisez les arguments first, after, last et before pour contrôler la pagination.

Exemple :

  
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type UserEdge {
      node: User!
      cursor: String!
    }

    type UserConnection {
      edges: [UserEdge!]!
      pageInfo: PageInfo!
    }

    type PageInfo {
      hasNextPage: Boolean!
      hasPreviousPage: Boolean!
      startCursor: String
      endCursor: String
    }

    type Query {
      users(first: Int, after: String, last: Int, before: String): UserConnection!
    }
  

Avantages :

• Pagination standardisée : Fournit un moyen cohérent d'implémenter la pagination dans toute votre API.
• Récupération de données efficace : Permet de récupérer de grandes listes de données par morceaux, réduisant la charge sur votre serveur et améliorant les performances.
• Pagination basée sur le curseur : Utilise des curseurs pour suivre la position de chaque nœud, ce qui est plus efficace que la pagination basée sur le décalage (offset).

Considérations :

• Complexité : Peut ajouter de la complexité à votre schéma.
• Surcharge : Nécessite des champs et des types supplémentaires pour implémenter le patron de connexion.
• Implémentation : Nécessite une implémentation soignée pour garantir que les curseurs sont uniques et cohérents.

Considérations globales

Lors de la conception d'un schéma GraphQL pour un public mondial, tenez compte de ces facteurs supplémentaires :

• Localisation : Utilisez des directives ou des types scalaires personnalisés pour prendre en charge différentes langues et régions. Par exemple, vous pourriez avoir un scalaire personnalisé LocalizedText qui stocke les traductions pour différentes langues.
• Fuseaux horaires : Stockez les horodatages en UTC et permettez aux clients de spécifier leur fuseau horaire à des fins d'affichage.
• Devises : Utilisez un format de devise cohérent et permettez aux clients de spécifier leur devise préférée à des fins d'affichage. Envisagez un scalaire personnalisé Currency pour représenter cela.
• Résidence des données : Assurez-vous que vos données sont stockées conformément aux réglementations locales. Cela pourrait nécessiter de déployer votre API dans plusieurs régions ou d'utiliser des techniques de masquage de données.
• Accessibilité : Concevez votre schéma pour qu'il soit accessible aux utilisateurs handicapés. Utilisez des noms de champs clairs et descriptifs et fournissez des moyens alternatifs d'accéder aux données.

Par exemple, considérons un champ de description de produit :

type Product {
 id: ID!
 name: String!
 description(language: String = "en"): String!
}

Cela permet aux clients de demander la description dans une langue spécifique. Si aucune langue n'est spécifiée, la valeur par défaut est l'anglais (`en`).

Conclusion

Une conception de schéma évolutive est essentielle pour construire des API GraphQL robustes et maintenables capables de gérer les exigences d'une application mondiale. En suivant les principes décrits dans cet article et en utilisant les patrons de conception appropriés, vous pouvez créer des API faciles à comprendre, à modifier et à étendre, tout en offrant d'excellentes performances et une grande évolutivité. N'oubliez pas de modulariser, composer et abstraire votre schéma, et de prendre en compte les besoins spécifiques de votre public mondial.

En adoptant ces patrons, vous pouvez libérer tout le potentiel de GraphQL et construire des API qui pourront alimenter vos applications pour les années à venir.