TypeScript et GraphQL : Construire des API fortement typées

TypeScript et GraphQL sont devenus des outils essentiels pour le développement web moderne, permettant aux développeurs de créer des applications fiables et évolutives. TypeScript ajoute un typage statique à JavaScript, tandis que GraphQL introduit une approche basée sur les schémas pour gérer les API, garantissant que les clients et les serveurs communiquent de manière transparente. Ensemble, ils constituent une force pour créer des API fortement typées, améliorant la productivité des développeurs et réduisant les erreurs.

Ce blog explore la complémentarité de TypeScript et de GraphQL, les avantages de leur utilisation conjointe et les meilleures pratiques pour la création d’API fortement typées.

Pourquoi TypeScript ?

TypeScript est un sur-ensemble de JavaScript qui introduit le typage statique dans le langage. Il fournit :

1. Sécurité: Détecte les erreurs liées au type pendant le développement plutôt qu’au moment de l’exécution.
2. Prise en charge améliorée de l’EDI: Des fonctionnalités telles que la saisie semi-automatique, la navigation dans le code et la refactorisation rendent le développement plus rapide et moins sujet aux erreurs.
3. Évolutivité: Un typage fort garantit que le code reste maintenable à mesure que les applications se développent.

Pourquoi GraphQL ?

GraphQL est un langage de requête et un environnement d’exécution pour les API qui permettent aux clients de demander uniquement les données dont ils ont besoin. Ses principales caractéristiques comprennent :

1. Schéma fortement typé: Les API GraphQL sont définies par des schémas écrits en SDL (Schema Definition Language), garantissant que l’API est auto-documentée et sécurisée.
2. Flexibilité: les clients peuvent interroger plusieurs ressources en une seule requête, optimisant ainsi les appels d’API.
3. Introspection: Les API GraphQL exposent leur schéma, permettant à des outils tels que GraphiQL ou Apollo Explorer de fournir des informations sur les requêtes, mutations et types disponibles.

Les éléments constitutifs des API fortement typées

• Conception Schema-First
  L’approche schématique de GraphQL permet aux développeurs de définir la structure de l’API, y compris les types de données qu’elle fournit, de manière déclarative. Ce schéma agit comme un contrat entre le client et le serveur, garantissant que les deux côtés sont alignés. Dans un projet basé sur TypeScript, ce schéma devient la base de la génération de types TypeScript.

1. Génération de types
   Pour éliminer la synchronisation manuelle entre les schémas GraphQL et les types TypeScript, des outils tels que GraphQL Code Generator peuvent générer automatiquement des définitions TypeScript à partir du schéma. Ce processus crée une source unique de vérité, garantissant que l’implémentation de l’API correspond exactement au schéma.

2. Résolveurs avec sécurité de type
   Les résolveurs GraphQL connectent le schéma aux sources de données, traitant les requêtes et renvoyant les réponses. Lors de l’utilisation de TypeScript, les résolveurs sont fortement typés, ce qui signifie que les développeurs peuvent détecter les incohérences ou les erreurs au moment de la compilation plutôt qu’au moment de l’exécution.

GraphQL vs Configuration CMS traditionnelle

Configuration CMS traditionnelle

Les plateformes CMS traditionnelles (comme WordPress ou Drupal) fonctionnent généralement avec des API REST ou des requêtes directes de base de données. Les configurations sont souvent rigides et peuvent nécessiter :

• Configuration manuelle pour les connexions aux points de terminaison.
• Code personnalisé pour mapper les données CMS aux structures de données frontales.

Exemple de flux de travail :

1. Le développeur back-end expose un point de terminaison (par exemple, /api/utilisateurs).
2. Le développeur frontend récupère les données avec l’API REST à l’aide de bibliothèques comme Axios ou Fetch.
3. Les ajustements du CMS nécessitent des changements à la fois dans le backend et le frontend.

Inconvénients :

• Manque de typage fort : les développeurs s’appuient souvent sur la documentation ou sur des tests manuels pour garantir la cohérence des données.
• Récupération excessive ou insuffisante : les API REST renvoient des ensembles de données fixes, qui peuvent inclure des champs inutiles ou manquer des champs obligatoires.

Avantages de TypeScript avec GraphQL

• Détection précoce des erreurs
  En tirant parti de l’analyse statique de TypeScript, les développeurs peuvent détecter les bogues liés au type pendant la phase de développement, bien avant le déploiement du code. Par exemple, si le serveur attend une chaîne mais que le client envoie un numéro, TypeScript signalera immédiatement cette incompatibilité.
  
  Exemple:

Schéma GraphQL :

type Query {
	user(id: ID!): User
}
type User {
	id: ID!
	name: String!
	age: Int!
}

Code TypeScript :

import { gql } from 'graphql-tag';
import { useQuery } from '@apollo/client';

const GET_USER = gql`
	query GetUser($id: ID!) {
		user(id: $id) {
			id
			name
			age
		}
	}
`;

interface User {
	id: string;
	name: string;
	age: number;
}

const UserProfile: React.FC<{ userId: string }> = ({ userId }) => {
	const { data, error } = useQuery<{ user: User }>(GET_USER, {
		variables: { id: userId },
	});
	
	if (error) {
		console.error("Error fetching user:", error);
		return <div>Error loading user data.</div>;
	}
	
	return (
		<div>
			<h1>{data?.user.name}</h1>
			<p>Age: {data?.user.age}</p>
		</div>
	);
};

Dans cet exemple :

• Si la variable id n’est pas une chaîne, ou si user.age n’est pas un nombre, TypeScript lèvera des erreurs.
• La requête GraphQL et l’interface TypeScript fonctionnent ensemble pour garantir la cohérence des types entre le frontend et l’API.

1. 1. Collaboration améliorée
      Avec un schéma fortement typé et des définitions TypeScript, les équipes travaillant sur différentes parties de l’application (par exemple, frontend et backend) peuvent collaborer plus efficacement. Les développeurs savent exactement à quelles structures de données s’attendre, réduisant ainsi les problèmes de communication et les incertitudes.

   2. Refonte améliorée
      À mesure que les applications se développent, des modifications du modèle de données sont inévitables. Avec TypeScript, effectuer ces modifications devient plus sûr et plus efficace car le compilateur identifie toutes les zones affectées dans la base de code, minimisant ainsi le risque d’introduction d’erreurs.

• Meilleure expérience du développeur
  Les environnements de développement intégrés (IDE) tels que Visual Studio Code fournissent la saisie semi-automatique, une documentation en ligne et des conseils d’erreur pour TypeScript et GraphQL. Cela accélère le développement et aide les développeurs à comprendre l’API sans avoir besoin de consulter une documentation externe.

Applications réelles

• Validation de la réponse de l’API
  TypeScript et GraphQL garantissent que les réponses de l’API correspondent au schéma défini. Ceci est particulièrement utile lorsque vous travaillez avec des données dynamiques, car les développeurs peuvent gérer les réponses en toute confiance sans se soucier des valeurs inattendues.

1. Alignement du front-end et du back-end
   Pour les équipes front-end, l’utilisation des API devient plus facile et plus sûre grâce aux types générés par TypeScript. Ces types fournissent une compréhension claire de la structure des données, réduisant ainsi le risque de mauvaise interprétation de l’API.

2. API auto-documentées
   Les capacités d’introspection de GraphQL, combinées aux définitions de types de TypeScript, créent des API essentiellement auto-documentées. Des outils tels que GraphQL Playground ou Apollo Studio peuvent afficher le schéma en temps réel, aidant ainsi les développeurs à comprendre rapidement les requêtes, mutations et types disponibles.

Meilleures pratiques d’intégration

1. Automatiser la génération de types: utilisez des outils pour générer des types TypeScript à partir de votre schéma GraphQL afin d’éviter les erreurs manuelles.
2. Utiliser des énumérations pour les constantes : remplacez les littéraux de chaîne par des énumérations GraphQL pour garantir la cohérence dans toute l’application.
3. Adoptez une approche axée sur le schéma: Commencez avec un schéma GraphQL bien défini et laissez-le piloter l’implémentation pour maintenir une source unique de vérité.
4. Activer les paramètres TypeScript stricts: utilisez le mode strict de TypeScript pour détecter les erreurs de type subtiles, en particulier lorsqu’il s’agit de champs facultatifs ou nullables.
5. Organiser les types de manière centralisée: conservez tous les types générés et personnalisés dans un seul répertoire pour une gestion et un accès faciles.

Conclusion

TypeScript et GraphQL sont un mariage parfait pour les développeurs qui accordent de l’importance à la sécurité des types, à la maintenabilité et à l’efficacité. Ensemble, ils créent une expérience de développement transparente, garantissant que les API sont fortement typées, bien documentées et faciles à utiliser.

En adoptant les meilleures pratiques et en exploitant des outils tels que GraphQL Code Generator, les développeurs peuvent exploiter tout le potentiel de cette intégration, en créant des API non seulement robustes, mais également pérennes. Que vous soyez un développeur frontal consommant des API ou un développeur dorsal les concevant, la combinaison de TypeScript et de GraphQL est un pas en avant vers des applications plus fiables et plus évolutives.