Introduzione ad Apollo Server: Guida Completa per Creare un'API GraphQL

Codegrind Team•Aug 28 2024

Apollo Server è una delle soluzioni più popolari e potenti per costruire un’API GraphQL su Node.js. Grazie alla sua flessibilità, Apollo Server consente di creare API robuste e scalabili, integrandosi perfettamente con diverse librerie e strumenti, come Express, Koa, e persino standalone. In questa guida, esploreremo come configurare Apollo Server, definire schemi GraphQL, gestire le risoluzioni delle query, e implementare middleware personalizzati per aggiungere funzionalità avanzate.

Cos’è Apollo Server?

Apollo Server è una libreria open-source per costruire server GraphQL. Apollo Server facilita la definizione degli schemi, la gestione delle risoluzioni delle query (resolvers) e l’integrazione con vari framework HTTP. È progettato per essere semplice da configurare e potente da usare, supportando funzionalità avanzate come la gestione della cache, le sottoscrizioni in tempo reale, e l’integrazione con middleware per l’autenticazione e l’autorizzazione.

Caratteristiche Principali

Definizione di Schemi e Resolvers: Facilita la definizione di schemi GraphQL e la gestione delle risposte alle query.
Supporto per Middleware: Si integra facilmente con Express, Koa, e altri framework per l’aggiunta di middleware personalizzati.
Sottoscrizioni: Supporta aggiornamenti in tempo reale con GraphQL subscriptions.
Strumenti di Debugging: Include Apollo Studio e strumenti come Apollo Server Plugin per monitorare e migliorare le prestazioni dell’API.

Configurazione di Apollo Server

1. Creare un Progetto Node.js

Inizia creando un nuovo progetto Node.js:

mkdir my-apollo-server
cd my-apollo-server
npm init -y

2. Installare Apollo Server e GraphQL

Installa Apollo Server e la libreria GraphQL:

npm install apollo-server graphql

3. Definire lo Schema GraphQL

Uno schema GraphQL definisce la struttura dei dati disponibili nell’API, comprese le query, le mutazioni e i tipi di dati.

Crea un file chiamato schema.js:

const { gql } = require("apollo-server");

const typeDefs = gql`
  type Query {
    hello: String
    user(id: ID!): User
  }

  type User {
    id: ID!
    name: String!
    email: String!
  }

  type Mutation {
    addUser(name: String!, email: String!): User
  }
`;

module.exports = typeDefs;

4. Definire i Resolvers

I resolvers sono funzioni che gestiscono le richieste per i campi dello schema GraphQL. Essi definiscono come i dati devono essere recuperati o modificati.

Crea un file chiamato resolvers.js:

const users = [];

const resolvers = {
  Query: {
    hello: () => "Ciao, mondo!",
    user: (parent, args) => users.find((user) => user.id === args.id),
  },
  Mutation: {
    addUser: (parent, args) => {
      const newUser = {
        id: `${users.length + 1}`,
        name: args.name,
        email: args.email,
      };
      users.push(newUser);
      return newUser;
    },
  },
};

module.exports = resolvers;

5. Configurare Apollo Server

Crea un file principale chiamato index.js per configurare Apollo Server con lo schema e i resolvers definiti:

const { ApolloServer } = require("apollo-server");
const typeDefs = require("./schema");
const resolvers = require("./resolvers");

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

server.listen().then(({ url }) => {
  console.log(`Server pronto su ${url}`);
});

6. Avviare il Server

Avvia il server Node.js:

node index.js

Vedrai un messaggio come:

Server pronto su http://localhost:4000/

Puoi aprire questa URL nel browser per accedere a Apollo Studio Explorer, uno strumento interattivo per eseguire query GraphQL.

Esecuzione di Query e Mutazioni

Esempio di Query

Nel browser o con un client GraphQL, puoi eseguire una query come questa:

query {
  hello
  user(id: "1") {
    id
    name
    email
  }
}

Esempio di Mutazione

Puoi anche eseguire una mutazione per aggiungere un nuovo utente:

mutation {
  addUser(name: "Alice", email: "alice@example.com") {
    id
    name
    email
  }
}

Middleware e Integrazione con Express

Apollo Server può essere integrato con Express per aggiungere middleware, come l’autenticazione e il logging.

1. Installare Express

npm install express

2. Integrare Apollo Server con Express

Modifica index.js per integrare Apollo Server con Express:

const express = require("express");
const { ApolloServer } = require("apollo-server-express");
const typeDefs = require("./schema");
const resolvers = require("./resolvers");

const app = express();

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

server.start().then(() => {
  server.applyMiddleware({ app });

  app.listen({ port: 4000 }, () =>
    console.log(`Server pronto su http://localhost:4000${server.graphqlPath}`)
  );
});

3. Aggiungere Middleware Personalizzati

Puoi aggiungere middleware Express prima che Apollo Server gestisca le richieste GraphQL:

app.use((req, res, next) => {
  console.log(`Richiesta da ${req.ip}`);
  next();
});

Sottoscrizioni in Tempo Reale

Apollo Server supporta le sottoscrizioni per l’aggiornamento in tempo reale dei dati.

1. Installare WebSocket e Subscription

npm install graphql-ws subscriptions-transport-ws

2. Configurare le Sottoscrizioni

Modifica index.js per aggiungere il supporto alle sottoscrizioni:

const { ApolloServer } = require("apollo-server");
const { makeExecutableSchema } = require("@graphql-tools/schema");
const { useServer } = require("graphql-ws/lib/use/ws");
const { WebSocketServer } = require("ws");

const typeDefs = require("./schema");
const resolvers = require("./resolvers");

const schema = makeExecutableSchema({ typeDefs, resolvers });

const server = new ApolloServer({ schema });

server.listen().then(({ url }) => {
  console.log(`Server pronto su ${url}`);
});

const wsServer = new WebSocketServer({
  server,
  path: "/graphql",
});

useServer({ schema }, wsServer);

3. Definire una Sottoscrizione nello Schema

Aggiungi una sottoscrizione al tuo schema:

type Subscription {
  userAdded: User
}

E aggiungi un resolver per la sottoscrizione:

const { PubSub } = require("apollo-server");
const pubsub = new PubSub();

const resolvers = {
  Query: {
    /* ... */
  },
  Mutation: {
    addUser: (parent, args) => {
      const newUser = {
        /* ... */
      };
      users.push(newUser);
      pubsub.publish("USER_ADDED", { userAdded: newUser });
      return newUser;
    },
  },
  Subscription: {
    userAdded: {
      subscribe: () => pubsub.asyncIterator(["USER_ADDED"]),
    },
  },
};

4. Eseguire una Sottoscrizione

Nel client GraphQL:

subscription {
  userAdded {
    id
    name
    email
  }
}

Ora riceverai aggiornamenti in tempo reale ogni volta che viene aggiunto un nuovo utente.

Best Practices per Apollo Server

Modularizza lo Schema e i Resolvers: Organizza lo schema e i resolvers in moduli separati per una migliore manutenibilità.
Autenticazione e Autorizzazione: Usa middleware per gestire l’autenticazione e l’autorizzazione delle richieste.
Monitoraggio e Logging: Implementa strumenti di monitoraggio e logging per tracciare le performance e gli errori del server GraphQL.
Gestione degli Errori: Gestisci gli errori nei resolvers per fornire feedback utili ai client senza esporre informazioni sensibili.
Caching e Performance: Usa le funzionalità di caching di Apollo per migliorare le performance delle query più frequenti.

Conclusione

Apollo Server è uno strumento potente per costruire API Graph

QL scalabili e ricche di funzionalità. Con la sua facile integrazione con vari framework HTTP e il supporto per funzionalità avanzate come le subscriptions, Apollo Server ti permette di creare applicazioni moderne e reattive. Seguendo le best practices e le tecniche illustrate in questa guida, sarai in grado di sfruttare al meglio Apollo Server per creare API GraphQL robuste e scalabili.