Utilisation de GraphQL

Introduction

GraphQL est une alternative aux API REST. Il est constitué d’un langage de requête et d’un environnement d’exécution. Il a été créé par Facebook en 2012, puis a été mis en open source en 2015.

Pour rappel, voici les évolutions des façons d’appeler un traitement distant :

GraphQL s’appuie sur des requêtes POST qui sont donc à mettre en cache du côté du client. Ces requêtes indiquent l’ordre et la sélection des champs à remonter du serveur. Le serveur définit le contrat d’échange...

Le schéma

Avant de voir les requêtes, nous devons étudier le schéma de GraphQL, qui a un format spécifique, sur lequel s’appuient les requêtes.

Le schéma permet de lister les données que les clients demandent via des types d’objets. Le développeur de l’API fait l’association entre chaque champ d’un schéma avec une fonction nommée resolver qui produit une valeur lors de l’exécution.

Le schéma se décompose en sections qui sont identifiées par leur type. Il y a les types propres aux opérations et ceux relatifs à la description des données.

Un schéma est un graphe qui est généralement conçu et décrit en quatre étapes :

Commençons par des nœuds de graphes qui représentent les données :

type Livre {  
}  
  
type Auteur {  
} 

Ajoutons ensuite les types scalaires (Scalar) en utilisant les types intégrés Int, Float, String, Boolean, and ID. Au niveau du type, nous pouvons indiquer que la variable est optionnelle via l’utilisation du « ! ».

type Livre {  
 titre: String!  
 Contenu: String!  
}  
  
type Auteur {  
 nom: String!  
} 

Ajoutons ensuite...

L’extension Spring Data Querydsl

Querydsl est une bibliothèque qui permet de simplifier la création des prédicats de requête en générant un méta-modèle à l’aide d’un préprocesseur d’annotations. La bibliothèque est indépendante de Spring et elle est disponible ici : http://querydsl.com/.

Voici un exemple simple pour illustrer son utilisation :

List<Person> persons = queryFactory.selectFrom(person)  
 .where(  
   person.firstName.eq("John"),  
   person.lastName.eq("Doe"))  
 .fetch(); 

Son utilisation avec GraphQL et Spring simplifie le code. Nous créons un Bean Repository de type QuerydslPredicateExecutor qui manipule des DataFetcher. Spring Data couvre JPA, MongoDB et LDAP pour l’utilisation QuerydslPredicateExecutor.

Par exemple :

Pour un résultat unique :

// For single result queries  
DataFetcher<Account> dataFetcher =  
       QuerydslDataFetcher.builder(repository).single(); 

Pour un résultat sous forme de liste :

// For multi-result queries  
DataFetcher<Iterable<Account>> dataFetcher =  
       QuerydslDataFetcher.builder(repository).many(); 

Le DataFetcher construit un Querydsl Predicate à partir des paramètres...

Les contrôleurs GraphQL

Les contrôleurs GraphQL sont des contrôleurs classiques REST qui sont personnalisés. Ces contrôleurs sont détectés par l’AnnotatedControllerConfigurer. Nous indiquons qu’une méthode du contrôleur correspond à un champ de requête via l’utilisation de l’annotation @QueryMapping. La requête est déterminée à partir du nom de la méthode si celle-ci n’est pas spécifiée en paramètre de l’annotation.

@Controller  
public class BonjourController {  
  
       @QueryMapping   
       public String bonjour() {   
           return "Bonjour à vous!";  
       }  
} 

Le RuntimeWiring.Builder est utilisé pour enregistrer en tant que graphql.schema.DataFetcher la requête nommée "bonjour".

@SchemaMapping

Il est possible de personnaliser le nom du type parent et le nom du champ dans l’annotation @SchemaMapping :

@Controller  
public class LivreController {  
  
   @SchemaMapping(typeName="Livre", field="auteur ")  
   public Auteur getAuteur(Livre livre) {  
   ...

Autoconfiguration

Nous ne détaillons que la version HTTP pour illustration. Un exemple complémentaire basé sur WebFlux est disponible dans les exemples téléchargeables. La configuration automatique se fait via le GraphQlWebMvcAutoConfiguration. Il y a un équivalent pour WebFlux : le GraphQlWebFluxAutoConfiguration.