Aller au contenu principal

Développement d'API GraphQL dans Cursor

GraphQL API Development in Cursor

GraphQL a révolutionné notre manière de construire des API en permettant aux clients de demander exactement les données dont ils ont besoin. Associé à Cursor, un éditeur IDE piloté par l'IA, votre flux de travail de développement GraphQL devient considérablement plus rapide et intelligent. Ce guide couvre tout, de la conception de schémas à l'implémentation de résolveurs prêts pour la production, en utilisant les fonctionnalités avancées de Cursor.

Premiers pas avec GraphQL dans Cursor​

Cursor offre un environnement exceptionnel pour le développement GraphQL grâce à sa complétion de code intelligente, sa génération de code pilotée par l'IA et sa compréhension approfondie des relations entre schémas. Que vous construisiez une nouvelle API à partir de zéro ou que vous mainteniez une API existante, les fonctionnalités de Cursor vous aident à écrire un meilleur code GraphQL avec moins d'effort.

L'intégration de Cursor avec les outils GraphQL vous permet de :

  • Générer automatiquement des schémas à partir des types TypeScript
  • Recevoir des suggestions intelligentes pour l'implémentation des résolveurs
  • Valider les requêtes en temps réel par rapport au schéma
  • Refactoriser de grands schémas avec l'aide de l'IA
  • Générer de la documentation directement depuis le code

Avant de plonger dans les détails de l'implémentation, assurez-vous que les outils suivants sont installés dans votre espace de travail :

  • Node.js 18 ou supérieur
  • IDE Cursor (la dernière version est recommandée)
  • Extension client GraphQL pour tester les requêtes

Configuration d'un projet GraphQL dans Cursor​

Un projet bien structuré est essentiel pour un développement GraphQL évolutif. Cursor excelle pour vous aider à organiser votre base de code dès le départ.

Créez la structure de dossiers suivante dans ce répertoire avec Cursor ouvert :

src/
  schema/
    typeDefs.ts
    resolvers/
      index.ts
      userResolver.ts
      postResolver.ts
  prisma/
    schema.prisma
  server.ts

Cette structure sépare clairement les préoccupations et permet à l'IA de Cursor de comprendre les limites entre les définitions de schéma, la logique des résolveurs et les modèles de base de données. Lorsque vous ouvrez cette structure dans Cursor, l'éditeur indexe automatiquement toutes les relations de types et fournit des suggestions inter-fichiers.

Installez les dépendances principales pour Apollo Server et la configuration Prisma :

npm install @apollo/server graphql
npm install @prisma/client
npm install -D prisma typescript ts-node @types/node

Après l'installation, initialisez Prisma dans votre projet. L'intégration du terminal de Cursor rend ce processus transparent, et l'IA aide à déboguer tout problème de configuration qui survient pendant la configuration.

astuce

Utilisez le chat intégré de Cursor pour poser des questions sur la compatibilité des packages. Par exemple, sélectionnez votre package.json et demandez : « Ces dépendances GraphQL sont-elles compatibles avec la dernière version d'Apollo Server ? » Cursor analysera les versions et suggérera des mises à jour.

Conception de schémas assistée par l'IA​

La conception du schéma est le fondement de toute API GraphQL. Les fonctionnalités d'IA de Cursor rendent ce processus plus intuitif en suggérant des types, des champs et des relations en fonction des besoins de votre application.

Création de définitions de types​

Commencez par définir vos types principaux dans src/schema/typeDefs.ts. Cursor fournit une complétion automatique intelligente pour la syntaxe GraphQL SDL (Schema Definition Language), y compris les scalaires intégrés, les directives et les types personnalisés.

export const typeDefs = `#graphql
  type User {
    id: ID!
    email: String!
    name: String
    posts: [Post!]!
    createdAt: String!
    updatedAt: String!
  }

  type Post {
    id: ID!
    title: String!
    content: String!
    published: Boolean!
    author: User!
    createdAt: String!
    updatedAt: String!
  }

  type Query {
    users: [User!]!
    user(id: ID!): User
    posts: [Post!]!
    post(id: ID!): Post
  }

  type Mutation {
    createUser(email: String!, name: String): User!
    createPost(title: String!, content: String!, authorId: ID!): Post!
    publishPost(id: ID!): Post!
    deletePost(id: ID!): Post!
  }
`;

Lorsque vous tapez des définitions de types dans Cursor, l'éditeur reconnaît la syntaxe GraphQL et offre des suggestions contextuelles. L'IA comprend les relations entre les types et peut suggérer des champs manquants lorsque vous définissez de nouvelles entités.

Génération de schémas à partir des modèles Prisma​

L'un des flux de travail les plus puissants de Cursor consiste à générer des schémas GraphQL directement à partir de vos modèles Prisma. Après avoir défini votre schéma de base de données dans prisma/schema.prisma, vous pouvez utiliser la fonction de chat IA de Cursor pour convertir ces modèles en définitions de types GraphQL.

Voici un exemple de schéma Prisma :

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(uuid())
  email     String   @unique
  name      String?
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        String   @id @default(uuid())
  title     String
  content   String
  published Boolean  @default(false)
  authorId  String
  author    User     @relation(fields: [authorId], references: [id])
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Sélectionnez le schéma Prisma dans Cursor et utilisez la fonction de chat IA avec une invite comme : « Générez les définitions de types GraphQL correspondantes pour ces modèles Prisma, y compris les types Query et Mutation. » Cursor générera un SDL qui reflète fidèlement votre structure de base de données.

attention

Examinez toujours les schémas générés par l'IA pour vous assurer que les exigences de la logique métier sont satisfaites. L'IA comprend la structure mais peut manquer des règles de validation spécifiques au domaine ou des scalaires personnalisés requis par votre application.

Implémentation de résolveurs dans Cursor​

Les résolveurs sont l'endroit où une API GraphQL prend vie. L'intégration TypeScript de Cursor rend l'écriture de résolveurs type-safe considérablement plus efficace.

Écriture de résolveurs type-safe​

Créez des fichiers de résolveurs avec une prise en charge TypeScript complète. Cursor comprend la relation entre vos schémas et les types de résolveurs, offrant une complétion automatique pour les objets parents, les arguments et le contexte.

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export const userResolver = {
  Query: {
    users: async () => {
      return await prisma.user.findMany({
        include: { posts: true },
      });
    },

    user: async (_: unknown, { id }: { id: string }) => {
      return await prisma.user.findUnique({
        where: { id },
        include: { posts: true },
      });
    },
  },

  User: {
    posts: async (parent: { id: string }) => {
      return await prisma.post.findMany({
        where: { authorId: parent.id },
      });
    },
  },

  Mutation: {
    createUser: async (
      _: unknown,
      { email, name }: { email: string; name?: string }
    ) => {
      return await prisma.user.create({
        data: { email, name },
      });
    },
  },
};

L'IntelliSense de Cursor fournit des informations de type précises pour les arguments des résolveurs basées sur vos définitions de schéma. Lorsque vous survolez des paramètres ou des valeurs de retour, vous voyez les types GraphQL exacts mappés à TypeScript.

Utilisation de l'IA pour générer des résolveurs complexes​

Pour la logique de résolveur complexe impliquant des transformations de données, des agrégations ou des appels à des API tierces, la fonction de génération d'IA de Cursor est inestimable. Sélectionnez une partie de votre schéma et demandez à Cursor de générer l'implémentation du résolveur correspondante.

Par exemple, étant donné cette définition de schéma avancée :

type Query {
  searchPosts(query: String!, filters: PostFilters): SearchResult!
}

input PostFilters {
  publishedOnly: Boolean
  dateFrom: String
  dateTo: String
  authorIds: [ID!]
}

type SearchResult {
  posts: [Post!]!
  totalCount: Int!
  hasMore: Boolean!
}

Vous pouvez inviter Cursor : « Implémentez un résolveur pour searchPosts qui filtre selon les conditions fournies, prend en charge la pagination avec une limite par défaut de 20, et retourne les valeurs totalCount et hasMore. » L'IA générera une implémentation complète utilisant l'API de filtrage de Prisma.

searchPosts: async (
  _: unknown,
  {
    query,
    filters,
  }: {
    query: string;
    filters?: {
      publishedOnly?: boolean;
      dateFrom?: string;
      dateTo?: string;
      authorIds?: string[];
    };
  },
  context: { userId?: string }
) => {
  const limit = 20;
  const where: any = {
    OR: [
      { title: { contains: query, mode: 'insensitive' } },
      { content: { contains: query, mode: 'insensitive' } },
    ],
  };

  if (filters?.publishedOnly) {
    where.published = true;
  }

  if (filters?.dateFrom || filters?.dateTo) {
    where.createdAt = {};
    if (filters.dateFrom) where.createdAt.gte = new Date(filters.dateFrom);
    if (filters.dateTo) where.createdAt.lte = new Date(filters.dateTo);
  }

  if (filters?.authorIds?.length) {
    where.authorId = { in: filters.authorIds };
  }

  const [posts, totalCount] = await Promise.all([
    prisma.post.findMany({
      where,
      take: limit,
      include: { author: true },
    }),
    prisma.post.count({ where }),
  ]);

  return {
    posts,
    totalCount,
    hasMore: totalCount > limit,
  };
},
astuce

Lors de la génération de résolveurs complexes, examinez toujours les requêtes Prisma pour détecter les problèmes N+1. L'IA de Cursor génère souvent une implémentation de base qui peut ne pas inclure le modèle DataLoader pour le chargement par lots des entités liées.

Intégration Apollo Server​

Connecter vos schémas et résolveurs à Apollo Server est simple avec l'aide de Cursor. L'éditeur vous aide à configurer le serveur avec les bons types TypeScript et le middleware.

Configuration du serveur​

Créez votre fichier server.ts avec la configuration Apollo Server 4 :

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { typeDefs } from './schema/typeDefs';
import { resolvers } from './schema/resolvers';

interface MyContext {
  token?: string;
  userId?: string;
}

const server = new ApolloServer<MyContext>({
  typeDefs,
  resolvers,
});

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
  context: async ({ req }): Promise<MyContext> => {
    const token = req.headers.authorization || '';
    // Ajoutez la logique d'authentification ici
    return { token };
  },
});

console.log(`Server ready at: ${url}`);

Cursor fournit une complétion automatique pour l'API Apollo Server et vous aide à maintenir les bons types tout au long de la configuration. L'IA peut également suggérer des modèles de middleware pour l'authentification, la journalisation et la gestion des erreurs.

Ajout de scalaires et de directives personnalisés​

Les API GraphQL avancées nécessitent souvent des scalaires personnalisés pour gérer des types de données spécialisés. Cursor vous aide à les implémenter avec une sécurité de type complète.

import { GraphQLScalarType, Kind } from 'graphql';

export const dateScalar = new GraphQLScalarType({
  name: 'Date',
  description: 'Custom Date scalar',
  serialize(value: unknown) {
    if (value instanceof Date) {
      return value.toISOString();
    }
    throw Error('GraphQL Date Scalar serializer expected a Date object');
  },
  parseValue(value: unknown) {
    if (typeof value === 'string') {
      return new Date(value);
    }
    throw new Error('GraphQL Date Scalar parser expected a string');
  },
  parseLiteral(ast) {
    if (ast.kind === Kind.STRING) {
      return new Date(ast.value);
    }
    return null;
  },
});

Lorsque vous définissez des scalaires personnalisés, le serveur de langage TypeScript de Cursor s'assure que vos fonctions de sérialisation et d'analyse gèrent les bons types, prévenant les erreurs d'exécution.

Meilleures pratiques d'intégration Prisma​

La combinaison de Prisma et GraphQL dans Cursor crée une expérience de développement full-stack puissante. Cette section couvre les meilleures pratiques pour intégrer ces technologies efficacement.

Génération des types Prisma Client​

Après avoir modifié votre schéma Prisma, exécutez la commande generate. L'intégration du terminal de Cursor capture la sortie, et si des erreurs surviennent, l'IA vous aide à corriger les problèmes de syntaxe du schéma.

npx prisma generate

Les types Prisma Client générés s'intègrent de manière transparente à l'IntelliSense de Cursor. Lors de l'écriture des résolveurs, vous obtenez une complétion automatique complète pour les champs des modèles, les options de filtrage et les requêtes de relations.

Utilisation de DataLoader pour les relations​

Pour éviter le problème des requêtes N+1 dans les résolveurs GraphQL, intégrez DataLoader dans votre projet Cursor. L'IA vous aide à configurer des fonctions de chargement par lots que Prisma exécutera efficacement.

import DataLoader from 'dataloader';
import { PrismaClient, User } from '@prisma/client';

const prisma = new PrismaClient();

export const createUserLoader = () => {
  return new DataLoader<string, User | null>(async (userIds) => {
    const users = await prisma.user.findMany({
      where: { id: { in: [...userIds] } },
    });

    const userMap = new Map(users.map((user) => [user.id, user]));
    return userIds.map((id) => userMap.get(id) || null);
  });
};

Dans le contexte de votre serveur, initialisez les chargeurs et passez-les aux résolveurs :

interface MyContext {
  userLoader: ReturnType<typeof createUserLoader>;
  postLoader: ReturnType<typeof createPostLoader>;
}

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
  context: async (): Promise<MyContext> => {
    return {
      userLoader: createUserLoader(),
      postLoader: createPostLoader(),
    };
  },
});
attention

Les instances DataLoader doivent être créées par requête pour éviter les problèmes de cache entre différents utilisateurs. L'IA de Cursor suggère parfois un modèle singleton pour les chargeurs ; vérifiez toujours que votre implémentation crée de nouvelles instances pour chaque requête GraphQL.

Génération et tests de requêtes IA​

L'une des fonctionnalités les plus remarquables de Cursor est la capacité à générer et tester des requêtes GraphQL basées sur votre schéma. Cela accélère les flux de travail de développement et de débogage.

Génération de requêtes à partir du schéma​

Sélectionnez vos définitions de types dans Cursor et demandez à l'IA de générer des requêtes et des mutations d'exemple. Cela est particulièrement utile pour les développeurs front-end qui ont besoin de comprendre les interfaces API disponibles.

Pour le schéma User et Post ci-dessus, Cursor pourrait générer :

query GetUserWithPosts($userId: ID!) {
  user(id: $userId) {
    id
    email
    name
    posts {
      id
      title
      published
      createdAt
    }
  }
}

mutation CreateNewPost($title: String!, $content: String!, $authorId: ID!) {
  createPost(title: $title, content: $content, authorId: $authorId) {
    id
    title
    author {
      id
      name
    }
  }
}

Ces requêtes générées sont entièrement typées et validées par rapport à votre schéma, réduisant la probabilité d'erreurs d'intégration front-end.

Test des résolveurs avec des requêtes générées​

Utilisez l'IA de Cursor pour générer des suites de tests complètes pour vos résolveurs. Sélectionnez une fonction de résolveur et demandez : « Générez des tests Jest pour le résolveur incluant des appels Prisma simulés et des cas limites. »

import { userResolver } from './userResolver';
import { PrismaClient } from '@prisma/client';

jest.mock('@prisma/client', () => {
  const mockPrisma = {
    user: {
      findMany: jest.fn(),
      findUnique: jest.fn(),
      create: jest.fn(),
    },
  };
  return { PrismaClient: jest.fn(() => mockPrisma) };
});

describe('User Resolver', () => {
  const prisma = new PrismaClient();

  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('should return all users with their posts', async () => {
    const mockUsers = [
      { id: '1', email: '[email protected]', posts: [] },
      { id: '2', email: '[email protected]', posts: [] },
    ];
    (prisma.user.findMany as jest.Mock).mockResolvedValue(mockUsers);

    const result = await userResolver.Query.users();

    expect(prisma.user.findMany).toHaveBeenCalledWith({
      include: { posts: true },
    });
    expect(result).toEqual(mockUsers);
  });

  it('should return a single user by id', async () => {
    const mockUser = { id: '1', email: '[email protected]', posts: [] };
    (prisma.user.findUnique as jest.Mock).mockResolvedValue(mockUser);

    const result = await userResolver.Query.user(null, { id: '1' });

    expect(prisma.user.findUnique).toHaveBeenCalledWith({
      where: { id: '1' },
      include: { posts: true },
    });
    expect(result).toEqual(mockUser);
  });
});

Gestion des erreurs et validation​

Une API GraphQL robuste nécessite une gestion des erreurs complète. Cursor vous aide à implémenter des modèles d'erreur cohérents dans vos résolveurs.

Classes d'erreur personnalisées​

Définissez des classes d'erreur personnalisées qui étendent les types d'erreur Apollo GraphQL :

import { GraphQLError } from 'graphql';

export class AuthenticationError extends GraphQLError {
  constructor(message: string = 'Not authenticated') {
    super(message, {
      extensions: { code: 'UNAUTHENTICATED', http: { status: 401 } },
    });
  }
}

export class ValidationError extends GraphQLError {
  constructor(message: string) {
    super(message, {
      extensions: { code: 'VALIDATION_FAILED', http: { status: 400 } },
    });
  }
}

export class NotFoundError extends GraphQLError {
  constructor(resource: string) {
    super(`${resource} not found`, {
      extensions: { code: 'NOT_FOUND', http: { status: 404 } },
    });
  }
}

Utilisez ces erreurs dans vos résolveurs avec la prise en charge de la complétion automatique de Cursor :

user: async (_: unknown, { id }: { id: string }) => {
  const user = await prisma.user.findUnique({
    where: { id },
    include: { posts: true },
  });

  if (!user) {
    throw new NotFoundError('User');
  }

  return user;
},
astuce

Créez un plugin d'erreur pour Apollo Server qui journalise les erreurs et les formate pour les clients. Cursor peut générer ce plugin en fonction de vos classes d'erreur personnalisées.

Conclusion​

Le développement d'API GraphQL dans Cursor combine la puissance d'un IDE moderne avec l'assistance intelligente de l'IA. De la conception de schémas à l'implémentation de résolveurs, en passant par les tests et le déploiement, Cursor rationalise tous les aspects du développement GraphQL.

Points clés de ce guide :

  • Utilisez l'IA de Cursor pour générer des schémas à partir de modèles Prisma et de types TypeScript
  • Exploitez l'intégration TypeScript pour le développement de résolveurs type-safe
  • Implémentez le modèle DataLoader pour éviter les requêtes N+1
  • Générez automatiquement des tests et des requêtes à partir des définitions de schéma
  • Maintenez une gestion des erreurs cohérente avec des classes d'erreur personnalisées

En continuant à construire avec GraphQL et Cursor, essayez la fonction de chat IA pour refactoriser de grands schémas, optimiser les requêtes de base de données et générer de la documentation. La combinaison de l'expertise humaine et de l'assistance de l'IA produit des API robustes, performantes et maintenables.