Bonnes Pratiques avec GraphQL AutoGen

Ce guide présente les meilleures pratiques pour concevoir, implémenter et optimiser vos APIs GraphQL avec GraphQL AutoGen.

Architecture et Structure

Organisation des packages

Organisez votre code par domaine métier plutôt que par couche technique :

Structure recommandée

com.example.ecommerce/
  ├─ product/
  │  ├─ Product.java
  │  ├─ ProductRepository.java
  │  ├─ ProductService.java
  │  ├─ ProductController.java
  │  └─ dto/
  │     ├─ ProductInput.java
  │     └─ ProductOutput.java
  │
  ├─ order/
  │  ├─ Order.java
  │  ├─ OrderRepository.java
  │  └─ ...
  │
  └─ user/
     ├─ User.java
     └─ ...

Séparation des préoccupations

Maintenez une séparation claire entre vos entités JPA et vos DTOs GraphQL :

Entités JPA : Représentent votre modèle de données persistant
DTOs GraphQL : Adaptent les données pour l'API GraphQL

Conseil: Évitez d'exposer directement vos entités JPA dans l'API GraphQL pour les applications complexes. Utilisez @GraphQLType sur des DTOs dédiés.

Conception du Schéma

Nommage cohérent

Suivez ces conventions de nommage pour assurer la cohérence :

Types : PascalCase (ex: Product, OrderItem)
Champs & requêtes : camelCase (ex: productName, getAllProducts)
Énumérations : SCREAMING_SNAKE_CASE pour les valeurs (ex: ORDER_STATUS avec PENDING, SHIPPED)

Description des types et champs

Documentez toujours vos types et champs pour une meilleure expérience développeur :

Exemple de documentation

@GraphQLType(description = "Représente un produit dans le catalogue")
public class Product {
    @GraphQLField(description = "Identifiant unique du produit")
    private Long id;

    @GraphQLField(description = "Nom commercial du produit")
    private String name;

    @GraphQLField(description = "Prix actuel du produit en euros")
    private BigDecimal price;
}

Performance

Utilisation des DataLoaders

GraphQL AutoGen génère automatiquement des DataLoaders pour vos relations, mais assurez-vous de les configurer correctement :

Configuration optimale des DataLoaders

@GraphQLType
public class Order {
    // ...

    @GraphQLField
    @ManyToOne
    @GraphQLDataLoader // Active le DataLoader automatique
    private Customer customer;

    @GraphQLField
    @OneToMany(mappedBy = "order")
    @GraphQLDataLoader(batchSize = 100) // Configure la taille du batch
    private List items;
}

Conseil: Pour les relations complexes ou personnalisées, implémentez vos propres DataLoaders avec @GraphQLDataLoaderRegistration.

Pagination

Utilisez toujours la pagination pour les listes potentiellement grandes :

Pagination avec Relay

@GraphQLQuery
public Connection getProducts(@GraphQLArgument int first,
                                     @GraphQLArgument String after,
                                     @GraphQLArgument ProductFilter filter) {
    // Implémentation avec Page de Spring Data
}

Sécurité

Autorisations

Intégrez Spring Security avec GraphQL AutoGen :

Sécurisation des requêtes

@GraphQLQuery
@PreAuthorize("hasRole('ADMIN')")
public List getAllUsers() {
    return userRepository.findAll();
}

Validation des entrées

Utilisez Bean Validation avec GraphQL AutoGen :

Validation d'entrée

@GraphQLType
public class ProductInput {
    @NotBlank(message = "Le nom ne peut pas être vide")
    private String name;

    @NotNull
    @Min(value = 0, message = "Le prix doit être positif")
    private BigDecimal price;

    // Getters et setters
}

Consultez notre guide de configuration avancée pour des options supplémentaires.

Documentation