graphql-builder

GraphQL Builder

Critères de décision : GraphQL vs REST

Critère	GraphQL	REST
Clients multiples (mobile/web/tiers) avec besoins différents	✅	❌ sur-fetch
API publique stable et versionnée	❌ complexe	✅
Upload de fichiers binaires	❌ multipart lourd	✅
CRUD simple sans nested data	❌ overhead	✅
Real-time natif (subscriptions)	✅	❌ SSE/WS manuel

Règle d'or : si un seul client consomme l'API et que les endpoints sont stables, REST suffit. GraphQL brille dès que plusieurs surfaces (mobile, web, partenaires) ont des besoins de champs divergents.

---

Workflow en étapes

1. Design du schéma SDL (Schema-First)

Définir le contrat avant le code. Partir du SDL, pas des modèles DB.

# types de base
type User {
  id: ID!
  email: String!
  role: UserRole!
  posts(first: Int = 10, after: String): PostConnection!
}

enum UserRole { ADMIN MEMBER GUEST }

# erreurs métier explicites — pas d'exceptions génériques
union CreateUserResult = User | EmailAlreadyExistsError | ValidationError

type EmailAlreadyExistsError { message: String! email: String! }
type ValidationError { message: String! field: String! }

type Mutation {
  createUser(input: CreateUserInput!): CreateUserResult!
}

input CreateUserInput {
  email: String!
  password: String!
  role: UserRole! = MEMBER
}

Check-list schéma

• Champs nullable par défaut → rendre ! uniquement ce qui est garanti
• Utiliser des input types pour toutes les mutations (jamais des scalaires inline)
• Documenter avec des commentaires SDL ("""description""") sur chaque type exposé
• Versionnement : préférer les champs @deprecated(reason: "…") plutôt qu'un v2

---

2. DataLoader — éliminer le N+1

Chaque résolveur de relation doit passer par un DataLoader. Sans ça, 100 posts = 100 requêtes DB.

// Apollo Server / TypeScript
import DataLoader from 'dataloader';

// Créer dans le contexte par requête (jamais en singleton global)
export function createLoaders(db: Db) {
  return {
    userById: new DataLoader<string, User>(async (ids) => {
      const users = await db.users.findMany({ where: { id: { in: [...ids] } } });
      const map = new Map(users.map(u => [u.id, u]));
      return ids.map(id => map.get(id) ?? new Error(`User ${id} not found`));
    }),
  };
}

// Résolveur
const resolvers = {
  Post: {
    author: (post, _args, ctx) => ctx.loaders.userById.load(post.authorId),
  },
};