GraphQL библиотека JavaScript (Node.js) — Полное руководство

GraphQL библиотека JavaScript (Node.js): Полное руководство

GraphQL — это язык запросов и среда выполнения для API, разработанная Facebook. В экосистеме Node.js основной библиотекой для работы с GraphQL является пакет graphql. Он предоставляет все необходимые инструменты для создания, валидации и выполнения GraphQL-запросов. Эта библиотека является фундаментом для таких популярных фреймворков, как Apollo Server, Express-GraphQL и других.

Что такое GraphQL и зачем он нужен?

В отличие от REST API, где каждый эндпоинт возвращает фиксированную структуру данных, GraphQL позволяет клиенту запрашивать только те поля, которые ему нужны. Это решает проблему over-fetching (получение лишних данных) и under-fetching (недостаток данных). Основные преимущества:

• Гибкость запросов: клиент сам определяет, какие данные получить.
• Единая точка входа: все запросы идут на один эндпоинт (например, /graphql).
• Строгая типизация: схема GraphQL определяет типы данных и их связи.
• Интроспекция: можно автоматически генерировать документацию и инструменты для тестирования (GraphiQL).

Установка GraphQL библиотеки для Node.js

Для начала работы установите пакет через npm или yarn:

npm install graphql

Также вам потребуется HTTP-сервер, например express, и промежуточное ПО express-graphql (или Apollo Server). Но сама библиотека graphql является ядром.

Создание первой схемы и резолвера

Схема — это описание типов данных и доступных операций (запросы, мутации). Резолверы — функции, которые выполняют реальную логику получения данных.

Пример простой схемы с одним типом User и запросом user:

const { graphql, buildSchema } = require('graphql');

// Определяем схему
const schema = buildSchema(`
  type User {
    id: ID!
    name: String
    email: String
  }

  type Query {
    user(id: ID!): User
  }
`);

// Данные (в реальном проекте — база данных)
const users = [
  { id: '1', name: 'Иван', email: 'ivan@example.com' },
  { id: '2', name: 'Мария', email: 'maria@example.com' }
];

// Резолверы
const root = {
  user: ({ id }) => users.find(user => user.id === id)
};

// Выполняем запрос
graphql({
  schema,
  source: '{ user(id: "1") { name email } }',
  rootValue: root
}).then(response => {
  console.log(JSON.stringify(response));
  // {"data":{"user":{"name":"Иван","email":"ivan@example.com"}}}
});

Типы данных в GraphQL

Библиотека graphql поддерживает все стандартные скалярные типы:

• String — строка;
• Int — целое число;
• Float — число с плавающей точкой;
• Boolean — логическое значение;
• ID — уникальный идентификатор (сериализуется как строка).

Также можно создавать собственные объектные типы, перечисления (enum), списки ([Type]) и ненулевые поля (Type!).

Мутации и подписки

Мутации используются для изменения данных (аналог POST/PUT/DELETE в REST). Подписки позволяют получать обновления в реальном времени через WebSocket.

Пример мутации для добавления пользователя:

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

const root = {
  addUser: ({ name, email }) => {
    const newUser = { id: String(users.length + 1), name, email };
    users.push(newUser);
    return newUser;
  }
};

// Выполнение мутации
graphql({
  schema,
  source: 'mutation { addUser(name: "Петр", email: "petr@example.com") { id name } }',
  rootValue: root
}).then(console.log);

Интеграция с Express

Для создания полноценного API используйте express-graphql:

npm install express express-graphql

Пример сервера:

const express = require('express');
const { graphqlHTTP } = require('express-graphql');
const { buildSchema } = require('graphql');

const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

const root = {
  hello: () => 'Hello, GraphQL!'
};

const app = express();
app.use('/graphql', graph