MongoDB e GraphQL: l'abbinamento perfetto

GraphQL è un modo potente ed efficiente per creare API. Il client interroga l'API in modo simile a come farebbe con un database e l'API restituisce solo i dati richiesti, spesso riducendo il payload di risposta e migliorando i tempi di risposta. Tempi di risposta bassi sono fondamentali nel mondo moderno.

Quando l'API GraphQL è abbinata a MongoDB, non solo ottieni tempi di risposta rapidi, ma anche un formato dei dati coerente dall'inizio alla fine.

Immagina questo: il tuo client esegue una query GraphQL e quella query assomiglia a JSON. Quando i dati raggiungono la tua applicazione—che, in questo esempio, supponiamo sia TypeScript—stai lavorando in applicazione con un formato dati simile a JSON. Facendo un passo oltre, quando lavori con MongoDB, i dati che invii da e verso MongoDB saranno anch'essi simili a JSON. Quello che ottieni, quindi, è un'esperienza dati coerente insieme alle prestazioni. Non c'è bisogno di preoccuparti troppo di manipolare e formattare i tuoi dati: puoi concentrarti sull'esperienza utente della tua applicazione, non sul database e sugli strumenti.

In questo tutorial vedremo quanto è semplice usare MongoDB nella tua API GraphQL, questa volta costruita con TypeScript.

Prerequisiti

Per questo tutorial, dobbiamo assicurarci di avere pronti alcuni elementi prima di iniziare:

• Un cluster MongoDB Atlas
• Node.js 22+
• MongoDB Node.js Driver 6.x

In questo tutorial non faremo nulla di particolarmente complesso dal punto di vista del database, quindi andrà bene qualsiasi tier di cluster MongoDB, anche quello gratuito. Tuttavia, non vedremo il provisioning di un cluster MongoDB Atlas in questo tutorial. Si presume che tu abbia già pronte le regole utente e di rete. Se ti serve aiuto per iniziare, dai un'occhiata alla documentazione Introduzione ad Atlas sull'argomento.

Dovrai avere un'applicazione Node.js creata. Se vuoi, puoi eseguire i seguenti comandi:

mkdir graphql_example
cd graphql_example
npm init -y

I comandi sopra creano una nuova directory di progetto e un file package.json di base. In questo progetto useremo TypeScript, il framework Express, MongoDB e Apollo. Possiamo installarli con i seguenti comandi:

npm install @apollo/server@4 body-parser cors dotenv express@4 graphql mongodb
npm install @types/cors @types/express@4 @types/node tsx typescript --save-dev

I comandi installeranno le dipendenze e le definizioni di tipo da usare in TypeScript.

Come ultima parte dei prerequisiti, ti servirà un file di configurazione per TypeScript. Alla radice del progetto, crea un file tsconfig.json con il seguente JSON:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Se in qualsiasi momento vuoi vedere il progetto completo o provarlo, puoi trovarlo su GitHub.

Crea le basi con Apollo, Express e le dipendenze MongoDB

Dal punto di vista della struttura del progetto, useremo quanto segue:

• src/database/connection.ts
• src/database/userService.ts
• src/resolvers/index.ts
• src/schema/typeDefs.ts
• src/types/index.ts
• src/index.ts
• .env

Il file src/index.ts conterrà tutto il bootstrap di Express e Apollo. Questo significa avviare il server, definire gli endpoint GraphQL, ecc. Il file src/types/index.ts conterrà le definizioni TypeScript per lavorare con il modello dati del database all'interno dell'applicazione. Da non confondere con il file src/schema/typeDefs.ts che, sebbene simile, si concentra sulle definizioni di tipo GraphQL.

Questo ci lascia con le directory database e resolvers. La maggior parte della logica dell'applicazione e del database sarà in questi file, che vedremo tra poco.

Per ora, concentriamoci sulla configurazione del server nel file src/index.ts:

import 'dotenv/config';
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';
import express from 'express';
import http from 'http';
import cors from 'cors';
import bodyParser from 'body-parser';
import { typeDefs } from './schema/typeDefs';
import { resolvers } from './resolvers';

async function startServer() {
  try {

    const app = express();
    
    const httpServer = http.createServer(app);

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

    await server.start();

    app.use(
      '/graphql',
      cors<cors.CorsRequest>(),
      bodyParser.json(),
      expressMiddleware(server)
    );

    const PORT = process.env.PORT || 3000;
    await new Promise<void>((resolve) => httpServer.listen({ port: PORT }, resolve));
    
    console.log(Server ready at http://localhost:${PORT}/graphql);

  } catch (error) {
    console.error('Error starting server:', error);
    process.exit(1);
  }
}

startServer();

Amplieremo il file sopra man mano che procediamo.

Per cominciare, importiamo tutte le dipendenze del progetto. Poi configuriamo il server Express e il middleware Apollo.

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

Non abbiamo ancora aggiunto nulla ai file src/schema/typeDefs.ts e src/resolvers/index.ts, ma in questa fase stiamo preparando tutto. Non riusciremo ad avviare il server senza errori finché non colmeremo le lacune negli altri file.

Vale la pena menzionare che in questo esempio consentiamo richieste da tutte le origini a causa di quanto segue:

cors<cors.CorsRequest>(),

Va bene per un ambiente di sviluppo, ma in produzione considera di consentire solo le origini necessarie.

Interagire con MongoDB da un'app TypeScript con Node.js

Sebbene abbiamo predisposto le basi con Express e il server Apollo, non abbiamo ancora configurato MongoDB nell'applicazione. Prima di passare al codice, dobbiamo aggiungere le informazioni di connessione al file .env:

MONGODB_URI="mongodb+srv://<USERNAME>:<PASSWORD>@<HOST>/?appName=devrel-graphql"
DB_NAME="graphql_example"

I campi <USERNAME>, <PASSWORD> e <HOST> vanno sostituiti con le informazioni del tuo cluster MongoDB Atlas, che trovi nella tua dashboard di MongoDB Atlas.

Ora impostiamo la logica di connessione al database per la nostra applicazione. All'interno del file **src/database/connection.ts**, aggiungi il seguente codice:

import { MongoClient, Db } from 'mongodb';

let db: Db | null = null;
let client: MongoClient | null = null;

export async function connectToDatabase(): Promise<Db> {
  if (db) {
    return db;
  }

  try {
    const MONGODB_URI = process.env.MONGODB_URI;
    if (!MONGODB_URI) {
      throw new Error('MONGODB_URI is not set');
    }
    const DB_NAME = process.env.DB_NAME || 'graphql_example';
    const APP_NAME = process.env.APP_NAME || 'devrel-graphql';

    console.log('Connecting to MongoDB...');
    
    client = new MongoClient(MONGODB_URI, { appName: APP_NAME });
    await client.connect();
    
    db = client.db(DB_NAME);
    
    console.log(Successfully connected to MongoDB database: ${DB_NAME});
    
    return db;
  } catch (error) {
    console.error('MongoDB connection error:', error);
    throw error;
  }
}

export function getDatabase(): Db {
  if (!db) {
    throw new Error('Database not initialized. Call connectToDatabase() first.');
  }
  return db;
}

export async function closeDatabase(): Promise<void> {
  if (client) {
    await client.close();
    db = null;
    client = null;
    console.log('MongoDB connection closed');
  }
}

L'idea qui è creare una connessione singleton. Esistono molti altri modi per usare MongoDB nella tua applicazione, ma per questa in particolare scegliamo questa strada.

La funzione connectToDatabase prenderà le informazioni di connessione dal file **.env**, si connetterà e restituirà il database che hai definito. Se fallisce, l'errore verrà intercettato e rilanciato. Dovresti aver bisogno di usare connectToDatabase solo quando configuri il server, come visto nel file precedente.

La funzione getDatabase verrà usata ogni volta che viene fatta una richiesta alla nostra applicazione. Ci permetterà di ottenere l'istanza corrente della connessione.

Infine, per tenere tutto in ordine, abbiamo una funzione closeDatabase per chiudere la connessione al database quando il server si arresta. Sta a te decidere se includere una funzione del genere, ma è una buona pratica.

Prima di arrivare alla logica del database, è probabilmente una buona idea definire i tipi TypeScript per i nostri DTO (data transfer object):

export interface User {
  id: string;
  name: string;
  email: string;
  age?: number;
  createdAt: string;
}

export interface CreateUserInput {
  name: string;
  email: string;
  age?: number;
}

export interface UpdateUserInput {
  id: string;
  name?: string;
  email?: string;
  age?: number;
}

Le interfacce sopra, presenti in **src/types/index.ts**, sono gestite dalla nostra API, ma la logica del database deve comunque conoscerle. Lo vedrai tra un attimo.

Questo ci porta alle interazioni reali con il database per create, retrieve, update, delete (CRUD), effettuate nel file src/database/userService.ts. L'idea è che i resolver GraphQL gestiscano la logica applicativa e chiamino le funzioni in questo service, mentre il service gestisce la logica del database.

Nel file src/database/userService.ts abbiamo il seguente codice:

import { Collection, ObjectId } from 'mongodb';
import { getDatabase } from './connection';
import { User, CreateUserInput, UpdateUserInput } from '../types';

interface UserDocument {
  _id: ObjectId;
  name: string;
  email: string;
  age?: number;
  createdAt: Date;
}

export class UserService {
  private collection: Collection<UserDocument>;

  constructor() {
    const db = getDatabase();
    this.collection = db.collection<UserDocument>('users');
  }

  private toUser(doc: UserDocument): User {
    return {
      id: doc._id.toString(),
      name: doc.name,
      email: doc.email,
      age: doc.age,
      createdAt: doc.createdAt.toISOString(),
    };
  }

  async getAllUsers(): Promise<User[]> {
    const users = await this.collection.find().toArray();
    return users.map(doc => this.toUser(doc));
  }

  async getUserById(id: string): Promise<User | null> {
    try {
      const doc = await this.collection.findOne({ _id: new ObjectId(id) });
      return doc ? this.toUser(doc) : null;
    } catch (error) {
      return null;
    }
  }

  async createUser(input: CreateUserInput): Promise<User> {
    const newUser: Omit<UserDocument, '_id'> = {
      name: input.name,
      email: input.email,
      age: input.age,
      createdAt: new Date(),
    };

    const result = await this.collection.insertOne(newUser as UserDocument);
    
    const createdUser = await this.collection.findOne({ _id: result.insertedId });
    
    if (!createdUser) {
      throw new Error('Failed to create user');
    }

    return this.toUser(createdUser);
  }

  async updateUser(input: UpdateUserInput): Promise<User | null> {
    try {
      const updateFields: Partial<Omit<UserDocument, '_id'>> = {};
      
      if (input.name !== undefined) updateFields.name = input.name;
      if (input.email !== undefined) updateFields.email = input.email;
      if (input.age !== undefined) updateFields.age = input.age;

      const result = await this.collection.findOneAndUpdate(
        { _id: new ObjectId(input.id) },
        { $set: updateFields },
        { returnDocument: 'after' }
      );

      return result ? this.toUser(result) : null;
    } catch (error) {
      return null;
    }
  }

  async deleteUser(id: string): Promise<boolean> {
    try {
      const result = await this.collection.deleteOne({ _id: new ObjectId(id) });
      return result.deletedCount > 0;
    } catch (error) {
      return false;
    }
  }

  async createIndexes(): Promise<void> {
    await this.collection.createIndex({ email: 1 }, { unique: true });
    await this.collection.createIndex({ createdAt: -1 });
    console.log('Database indexes created');
  }
}

La prima cosa che noterai sopra è la seguente interfaccia:

interface UserDocument {
  _id: ObjectId;
  name: string;
  email: string;
  age?: number;
  createdAt: Date;
}

Sembra simile alla nostra interfaccia User, ma non è proprio la stessa. UserDocument è modellata più rigorosamente su ciò con cui lavora il database. Nel database usiamo ObjectId, mentre nell'applicazione usiamo stringhe hash. In MongoDB l'id è rappresentato come _id invece di id, come nella nostra interfaccia User.

Questo ci porta alla classe UserService.

Dopo aver ottenuto un handle alla nostra collection dall'istanza del database tramite il metodo constructor, abbiamo la seguente serie di funzioni:

• toUser
• getAllUsers
• getUserById
• createUser
• updateUser
• deleteUser
• createIndexes

La funzione toUser è sostanzialmente un helper che converte tra User e UserDocument. Inviamo e riceviamo UserDocument da e verso il database e dobbiamo convertirlo per poter inviare e ricevere User dall'applicazione.

async createIndexes(): Promise<void> {
	await this.collection.createIndex({ email: 1 }, { unique: true });
	await this.collection.createIndex({ createdAt: -1 });
	console.log('Database indexes created');
}

La funzione createIndexes creerà alcuni indici di esempio che potrebbero esserci utili. Per impostazione predefinita, esiste un indice solo sul campo _id, che va bene per una demo con poche decine di documenti, ma man mano che l'app cresce non ignorare la creazione di indici adeguati in base ai tuoi dati e alle tue query. I due indici sopra sono solo esempi di ciò che potresti voler creare.

Ora possiamo guardare ogni funzione del service partendo da getAllUsers:

async getAllUsers(): Promise<User[]> {
	const users = await this.collection.find().toArray();
	return users.map(doc => this.toUser(doc));
}

La funzione troverà tutti i documenti nella collection perché non c'è alcun criterio di filtro in find. I risultati vengono convertiti con la nostra funzione toUser e restituiti all'applicazione, che in seguito saranno i resolver Apollo.

async getUserById(id: string): Promise<User | null> {
	try {
	  const doc = await this.collection.findOne({ _id: new ObjectId(id) });
	  return doc ? this.toUser(doc) : null;
	} catch (error) {
	  return null;
	}
}

La funzione getByUserId è simile, ma qui usiamo findOne specificando un criterio di filtro—in questo caso vogliamo un singolo utente basato sul campo univoco _id. Poiché il campo id nell'interfaccia User è una stringa, dobbiamo racchiuderlo in ObjectId per renderlo adatto alle query in MongoDB.

Passiamo alla creazione dei dati in MongoDB tramite la funzione createUser:

async createUser(input: CreateUserInput): Promise<User> {
	const newUser: Omit<UserDocument, '_id'> = {
	  name: input.name,
	  email: input.email,
	  age: input.age,
	  createdAt: new Date(),
	};
	
	const result = await this.collection.insertOne(newUser as UserDocument);
	
	const createdUser = await this.collection.findOne({ _id: result.insertedId });
	
	if (!createdUser) {
	  throw new Error('Failed to create user');
	}
	
	return this.toUser(createdUser);
}

Dopo aver usato insertOne per inserire i dati, usiamo l'insertedId restituito per poi interrogarli. Lo facciamo perché, in una GraphQL API, quando si crea un dato, ci si aspetta generalmente di poterlo interrogare nella stessa mutation.

La funzione updateUser è un po' diversa:

async updateUser(input: UpdateUserInput): Promise<User | null> {
	try {
	  const updateFields: Partial<Omit<UserDocument, '_id'>> = {};
	  
	  if (input.name !== undefined) updateFields.name = input.name;
	  if (input.email !== undefined) updateFields.email = input.email;
	  if (input.age !== undefined) updateFields.age = input.age;
	
	  const result = await this.collection.findOneAndUpdate(
		{ _id: new ObjectId(input.id) },
		{ $set: updateFields },
		{ returnDocument: 'after' }
	  );
	
	  return result ? this.toUser(result) : null;
	} catch (error) {
	  return null;
	}
}

In questa applicazione permettiamo aggiornamenti solo sui campi name, email e age. Tutti questi campi sono opzionali, quindi dobbiamo impostarli nei criteri di aggiornamento se presenti. 

Questo ci porta alla funzione findOneAndUpdate.

Il primo parametro oggetto di questa funzione è il criterio di filtro. Ci interessa fare un update solo dove _id corrisponde. Per ogni corrispondenza, usiamo l'operatore $set per sostituire o creare eventuali campi nel nostro oggetto updateFields. I campi che non compaiono nell'oggetto non verranno cambiati. Infine, dato che stiamo trovando e aggiornando, e non solo aggiornando, impostiamo returnDocument su after perché vogliamo il documento modificato come risposta, non quello originale. Se avessimo usato updateOne invece di findOneAndUpdate, avremmo ricevuto solo informazioni sull'operazione di aggiornamento, non i dati.

L'ultima operazione CRUD di questa API è la rimozione di dati da MongoDB, tramite la funzione deleteUser:

async deleteUser(id: string): Promise<boolean> {
	try {
	  const result = await this.collection.deleteOne({ _id: new ObjectId(id) });
	  return result.deletedCount > 0;
	} catch (error) {
	  return false;
	}
}

La funzione deleteOne sopra assomiglia a findOne perché usiamo un criterio di filtro basato su _id. La differenza è che ogni corrispondenza—in questo caso, al massimo un documento—verrà eliminata.

A questo punto, la logica del database è pronta. Per completarla, dobbiamo connetterci dal file **src/index.ts**:

// Previous imports here...
import { connectToDatabase, closeDatabase } from './database/connection';
import { UserService } from './database/userService';

async function startServer() {
  try {

    await connectToDatabase();
    
    const userService = new UserService();
    await userService.createIndexes();
    
    // The rest of the file here...
}

Nel frammento sopra, gran parte del file src/index.ts è stata omessa. L'obiettivo era solo mostrare l'uso di connectToDatabase e la creazione degli indici. Per chiarezza, inserisci pure quelle tre righe verso l'inizio della funzione startServer.

A questo punto possiamo concentrarci sulla logica dell'API.

Definisci i tipi GraphQL, i resolver e la logica applicativa personalizzata

Abbiamo già definito i tipi TypeScript per lavorare con il database e per passare i dati nell'applicazione. Tuttavia non abbiamo ancora creato le definizioni di tipo GraphQL, che definiscono con cosa l'utente può interagire quando usa la nostra API.

Nel file src/schema/typeDefs.ts, aggiungi quanto segue:

export const typeDefs = #graphql
  type User {
    id: ID!
    name: String!
    email: String!
    age: Int
    createdAt: String!
  }

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

  type Mutation {
    createUser(name: String!, email: String!, age: Int): User!
    updateUser(id: ID!, name: String, email: String, age: Int): User
    deleteUser(id: ID!): Boolean!
  }
;

Il tipo User è ciò che il client può richiedere in una data query. In questo esempio corrisponde all'interfaccia User, ma non è obbligatorio. Ad esempio, la tua interfaccia User potrebbe contenere dati che non vuoi mai restituire al client, come una password.

Il tipo Query definisce i tipi di query che possono essere eseguite nella nostra API. Ogni query restituirà un User o un array di User, ma possiamo avere logica specifica in mezzo.

Il tipo Mutation è simile a Query, ma è pensato per query che manipolano i dati.

Con le definizioni di tipo GraphQL in posizione, possiamo concentrarci sulla logica dei resolver per l'applicazione. Nel file src/resolvers/index.ts del progetto, includi il seguente codice:

import { UserService } from '../database/userService';
import { User, CreateUserInput, UpdateUserInput } from '../types';

export const resolvers = {
  Query: {
    users: async (): Promise<User[]> => {
      const userService = new UserService();
      return await userService.getAllUsers();
    },

    user: async (_: unknown, { id }: { id: string }): Promise<User | null> => {
      const userService = new UserService();
      return await userService.getUserById(id);
    },
  },

  Mutation: {
    createUser: async (
      _: unknown,
      { name, email, age }: CreateUserInput
    ): Promise<User> => {
      const userService = new UserService();
      return await userService.createUser({ name, email, age });
    },

    updateUser: async (
      _: unknown,
      { id, name, email, age }: UpdateUserInput
    ): Promise<User | null> => {
      const userService = new UserService();
      return await userService.updateUser({ id, name, email, age });
    },

    deleteUser: async (_: unknown, { id }: { id: string }): Promise<boolean> => {
      const userService = new UserService();
      return await userService.deleteUser(id);
    },
  },
};

I resolver sopra sono semplicemente un'estensione di quanto visto nel file delle definizioni di tipo per query e mutation.

Guarda la query users:

users: async (): Promise<User[]> => {
  const userService = new UserService();
  return await userService.getAllUsers();
},

Questa query GraphQL utilizzerà il nostro UserService, parte della logica di database, per ottenere tutti gli utenti. La risposta User[] verrà inviata all'utente, ma solo con i pezzi richiesti che corrispondono alle definizioni di tipo GraphQL.

Ad esempio, supponiamo che il client invii questa query:

query {
	users {
		name
		email
	}
}

Nell'esempio sopra abbiamo più campi con cui lavorare, ma il client vuole solo i campi name ed email. Questo è gestito in base alle nostre definizioni di tipo GraphQL con cui il client lavora. Apollo si occupa della magia per farlo accadere.

Le stesse regole si applicano a ogni query e mutation nel nostro file **src/resolvers/index.ts**.

createUser: async (
  _: unknown,
  { name, email, age }: CreateUserInput
): Promise<User> => {
  const userService = new UserService();
  return await userService.createUser({ name, email, age });
},

Per la definizione di tipo createUser, abbiamo visto che il client può passare i campi name, email e age. Nella funzione resolver createUser facciamo lo stesso e chiamiamo la funzione createUser dal nostro service del database. La risposta viene restituita al client in base ai campi che ha richiesto.

Compila ed esegui la GraphQL API

A questo punto, la GraphQL API dovrebbe essere in ottima forma. Ci sono diversi modi per compilare ed eseguire l'applicazione.

Per esempio, potresti aggiungere quanto segue al tuo **package.json**:

"scripts": {
	"build": "tsc",
	"start": "node dist/index.js",
	"dev": "tsx src/index.ts",
	"dev:watch": "tsx watch src/index.ts",
	"watch": "tsc -w"
},

Se scegli questa strada, puoi eseguire npm run build per compilare il progetto e npm run start per servirlo. La porta predefinita è 3000 e puoi testare con cURL o con qualsiasi strumento preferisci.

Conclusione

Hai appena visto come creare una GraphQL API con TypeScript e MongoDB come database. Anche se l'esempio è volutamente semplice, abbiamo visto come costruire query e mutation per eseguire operazioni CRUD contro il nostro database. MongoDB è un abbinamento perfetto in una GraphQL API perché i dati con cui lavori hanno un formato simile dall'inizio alla fine. Per esempio, il client esegue una query che assomiglia a JSON. I dati passati nella query possono essere usati con una formattazione minima e, allo stesso modo, quando vengono inviati da e verso il database. L'esperienza è fluida, permettendoti di concentrarti sull'esperienza utente e meno sulla manipolazione dei dati per soddisfare il database.

Se ti sei bloccato in qualsiasi punto del tutorial, assicurati di dare un'occhiata al progetto finito su GitHub.