GraphQL на Node.js: Полное руководство по библиотеке graphql-http

GraphQL библиотека JavaScript (Node.js): graphql-http

GraphQL — это язык запросов для API, разработанный Facebook, который предоставляет клиентам возможность запрашивать только те данные, которые им нужны. В экосистеме Node.js одной из ключевых библиотек для реализации GraphQL-серверов является graphql-http. Это легковесный, но мощный инструмент, который позволяет создавать высокопроизводительные API с минимальными накладными расходами. В отличие от более тяжеловесных решений, таких как Apollo Server, graphql-http предлагает гибкость и полный контроль над HTTP-обработчиками.

Что такое graphql-http?

graphql-http — это официальная библиотека от сообщества GraphQL, которая предоставляет простой способ подключения GraphQL к любому HTTP-серверу Node.js. Она не зависит от конкретного фреймворка (Express, Koa, Fastify и т.д.), что делает её универсальным выбором. Основная задача библиотеки — взять входящий HTTP-запрос, распарсить его, выполнить GraphQL-запрос и вернуть структурированный ответ.

Установка и настройка

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

npm install graphql-http graphql

Минимальный пример сервера на чистом Node.js (без Express):

const http = require('http');
const { createHandler } = require('graphql-http');
const { buildSchema } = require('graphql');

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

// Резолверы
const rootValue = {
  hello: () => 'Привет, мир!',
  user: ({ id }) => ({
    id,
    name: `Пользователь ${id}`,
    email: `user${id}@example.com`
  })
};

// Создаём обработчик
const handler = createHandler({ schema, rootValue });

// HTTP-сервер
const server = http.createServer((req, res) => {
  if (req.url === '/graphql') {
    handler(req, res);
  } else {
    res.writeHead(404);
    res.end('Not Found');
  }
});

server.listen(4000, () => {
  console.log('Сервер запущен на http://localhost:4000/graphql');
});

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

Большинство разработчиков используют Express. Интеграция graphql-http с Express тривиальна:

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

const schema = buildSchema(`
  type Query {
    books: [Book]
  }
  type Book {
    title: String
    author: String
  }
`);

const books = [
  { title: 'Война и мир', author: 'Лев Толстой' },
  { title: 'Преступление и наказание', author: 'Фёдор Достоевский' }
];

const rootValue = {
  books: () => books
};

const app = express();

app.all('/graphql', createHandler({ schema, rootValue }));

app.listen(3000, () => {
  console.log('Express + GraphQL на http://localhost:3000/graphql');
});

Основные возможности и преимущества

• Гибкость маршрутизации: вы сами решаете, на каком эндпоинте будет доступен GraphQL.
• Поддержка всех HTTP-методов: GET и POST запросы обрабатываются корректно.
• Встроенная валидация: библиотека автоматически проверяет запросы на соответствие схеме.
• Производительность: минимальное потребление памяти и высокая скорость обработки.
• Расширяемость: можно добавлять middleware для аутентификации, логирования и кэширования.

Работа с мутациями и подписками

Помимо запросов (Query), graphql-http поддерживает мутации (Mutation) для изменения данных. Пример схемы с мутацией:

const schema = buildSchema(`
  type Query {
    message: String
  }
  type Mutation {
    setMessage(newMessage: String!): String
  }
`);

let message = 'Стартовое сообщение';

const rootValue = {
  message: () => message,
  setMessage: ({ newMessage }) => {
    message = newMessage;
    return message;
  }
};

Для подписок (Subscriptions) в реальном времени рекомендуется использовать WebSocket-библиотеки, такие как graphql-ws, но graphql-http отлично справляется с HTTP-запросами.

Обработка ошибок

Библиотека автоматически форматирует ошибки в стандартном GraphQL-формате. Вы можете кастомизировать обработку ошибок, передав функцию formatError:

const handler = createHandler({
  schema,
  rootValue,
  formatError: (err) => {
    console.error('Ошибка GraphQL:', err);
    return { message: 'Внутренняя ошибка сервера', code: 500 };
  }