La pagination par curseur dans une API GraphQL avec Prisma

Les API qui exposent de grandes collections utilisent une pagination par décalage. Le serveur ignore autant d’éléments avant de renvoyer la page demandée. Cette méthode est simple, mais son coût augmente avec la taille de la collection ; des insertions peuvent aussi provoquer des doublons ou des omissions.

La pagination basée sur un curseur remplace ce numéro par une position stable. Le client reçoit un jeton opaque, puis le transmet pour obtenir la page suivante. Avec Prisma, cette pagination par clé s’appuie sur un identifiant unique et un ordre de tri déterministe.

Concevoir une connexion paginée

GraphQL n’impose aucun format de pagination. Pour exposer un fil de publications, le schéma peut adopter le modèle de connexion Relay : chaque arête contient un nœud et son curseur, tandis que les informations de page indiquent s’il reste des éléments à lire.

Pour un modèle Publication déjà présent dans Prisma, le schéma GraphQL minimal serait :

type Query {
  publications(first: Int = 20, after: String): PublicationConnection!
}

type PublicationConnection {
  edges: [PublicationEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type PublicationEdge {
  cursor: String!
  node: Publication!
}

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

Chaque arête contient un cursor et un node. Les arguments first et after pilotent la navigation : le premier borne le nombre de résultats, le second désigne le dernier élément déjà reçu. Les curseurs de début et de fin permettent au client de construire une chaîne de pagination.

Encoder un curseur opaque et stable

Un curseur ne doit pas exposer la structure de la requête. Encodez un objet JSON contenant l’identifiant avec Base64URL, puis décodez-le avant l’accès à Prisma. Dans une architecture microservices avec services Node.js, ce décodage peut rester dans le service responsable de la collection.

import { GraphQLError } from "graphql";

function encodeCursor(id: string): string {
  return Buffer.from(JSON.stringify({ id })).toString("base64url");
}

function decodeCursor(cursor: string): string {
  try {
    const value = JSON.parse(
      Buffer.from(cursor, "base64url").toString("utf8")
    );
    if (typeof value.id !== "string") throw new Error("Identifiant absent");
    return value.id;
  } catch {
    throw new GraphQLError("Curseur de pagination invalide.");
  }
}

Base64URL n’est pas un chiffrement : un client peut fabriquer une chaîne, et le résolveur doit toujours vérifier les droits d’accès. Pour conserver un ordre stable, combinez un champ de date avec une clé unique, par exemple createdAt décroissant puis id décroissant. Ce couple de tri doit rester identique entre deux appels. Si le tri évolue, encodez ses valeurs et sa version dans le curseur.

Interroger Prisma avec une pagination par clé

Le curseur de Prisma doit pointer vers une ligne unique. Dans findMany, transmettez cursor: { id } lorsque le client fournit after, et ajoutez skip: 1 pour exclure cette ligne déjà affichée. La valeur take vaut first + 1 : la ligne supplémentaire révèle si une autre page existe.

Le résolveur reçoit l’instance Prisma par le contexte GraphQL :

async function publications(
  _parent: unknown,
  args: { first?: number | null; after?: string | null },
  context: { prisma: PrismaClient }
) {
  const prisma = context.prisma;
  const first = args.first ?? 20;

  if (first < 1 || first > 100) {
    throw new GraphQLError(
      "first doit être compris entre 1 et 100."
    );
  }

  const cursorId = args.after
    ? decodeCursor(args.after)
    : undefined;

  const [rows, totalCount] = await Promise.all([
    prisma.publication.findMany({
      take: first + 1,
      ...(cursorId
        ? { cursor: { id: cursorId }, skip: 1 }
        : {}),
      orderBy: [
        { createdAt: "desc" },
        { id: "desc" }
      ],
    }),
    prisma.publication.count(),
  ]);

  const hasNextPage = rows.length > first;
  const page = hasNextPage ? rows.slice(0, first) : rows;
  const edges = page.map((node) => ({
    cursor: encodeCursor(node.id),
    node,
  }));

  return {
    edges,
    totalCount,
    pageInfo: {
      hasNextPage,
      hasPreviousPage: cursorId !== undefined,
      startCursor: edges[0]?.cursor ?? null,
      endCursor: edges[edges.length - 1]?.cursor ?? null,
    },
  };
}

Le calcul de hasNextPage compare donc le nombre de lignes reçues à first. hasPreviousPage devient vrai dès qu’un curseur a été fourni. Pour des filtres, appliquez-les à la requête et au comptage, puis vérifiez que les identifiants correspondent bien à la collection accessible.

Comparer les stratégies selon le contexte

Le choix dépend du volume, de la fréquence de modification et du contrat GraphQL. Le comparatif ci-dessous oppose les trois approches usuelles.

Critère Décalage avec skip Curseur sur id Curseur composite
Coût de lecture Croît avec le décalage Accès direct à la position Accès direct à la position
Stabilité Fragile lors des insertions Stable avec un ordre déterministe Stable avec un ordre déterministe
Compatibilité Pagination classique Adaptée aux connexions Relay Adaptée aux tris multicritères
Cas courant Petits catalogues paginés Fil d’actualité Listes filtrées et classements

Dans un catalogue de films, le curseur permet d’afficher progressivement une sélection de films doublés en hindi sans dépendre d’un numéro de page. Pour des tris multicritères, une stratégie composite mémorise les dernières valeurs et reconstruit une condition de plage, au lieu de répéter un skip coûteux.

Calculer la navigation et ses métadonnées

PageInfo expose hasNextPage, hasPreviousPage, startCursor et endCursor. Le premier et le dernier curseur de la page permettent de construire l’URL suivante ou précédente. totalCount reste une somme indépendante : elle indique la taille de la collection, pas la position du curseur.

Le nombre total peut coûter cher sur de gros volumes. Vous pouvez retirer le champ du schéma, acceptant de ne pas connaître ce total, ou conserver un comptage exact si le produit l’exige. Dans une API de recommandation, les ressources consacrées à l’apprentissage automatique rappellent qu’un ordre dépendant d’un modèle doit être versionné pour éviter des positions incohérentes.

Sécuriser et tester le résolveur

Limitez la taille des pages et appliquez les règles d’autorisation avant la requête. Une taille hors bornes doit produire une erreur GraphQL explicite, jamais une requête sans limite. Base64URL n’offrant aucune intégrité, utilisez si nécessaire une signature HMAC du jeton, puis vérifiez-la avant de retrouver la ligne.

Testez la première page, la page suivante, le dernier curseur, un curseur malformé et l’absence de résultats. Insérez une publication entre deux appels pour vérifier l’absence de doublons. En environnement distribué, précisez que les pages ne forment pas forcément une transaction unique.

Pour les relations, chargez les données avec DataLoader afin d’éviter les requêtes N+1. Une analyse statique avec des règles ESLint personnalisées complète les tests en détectant les contrats de résolution incohérents et les erreurs de typage.

Déployer une API paginée

Créez un index composite sur createdAt et id pour que la requête reste rapide lorsque la collection grossit. Sélectionnez seulement les champs nécessaires et surveillez le nombre de requêtes. Le champ totalCount doit être évalué séparément, car il ne profite pas de la limite appliquée au curseur.

Pour distribuer le service, la zone cloud permet de comparer les options de déploiement, de cache et d’infrastructure de données. Un cache de réponses doit inclure first, after et le contexte d’autorisation dans sa clé, afin de ne pas mélanger deux positions ou exposer des données privées.

Implémentez maintenant le schéma de connexion, validez le résolveur avec de vrais curseurs, puis déployez la pagination par curseur dès que le flux dépasse quelques centaines d’éléments. Mesurez le temps de réponse avant et après le changement pour vérifier le gain attendu.