GraphQL API с TypeScript: пошаговый туториал для начинающих

Введение в GraphQL и TypeScript

GraphQL — это язык запросов для API, который позволяет клиентам запрашивать только те данные, которые им действительно нужны. В сочетании с TypeScript, который добавляет статическую типизацию в JavaScript, вы получаете мощный инструмент для создания надежных и масштабируемых API. В этом туториале мы шаг за шагом создадим простой GraphQL API на TypeScript. Вы узнаете, как настроить проект, определить схему, написать резолверы и выполнить запросы.

Этот материал ориентирован на начинающих разработчиков, которые знакомы с основами JavaScript и хотят освоить современные технологии. К концу статьи вы сможете самостоятельно развернуть базовый GraphQL сервер.

Шаг 1: Настройка проекта

Прежде чем писать код, необходимо инициализировать проект и установить зависимости. Мы будем использовать Apollo Server — одну из самых популярных библиотек для работы с GraphQL в Node.js.

Инициализация npm

Создайте новую директорию и выполните инициализацию:

mkdir graphql-typescript-tutorial
cd graphql-typescript-tutorial
npm init -y

Установка зависимостей

Установите необходимые пакеты:

npm install apollo-server graphql
npm install typescript ts-node @types/node --save-dev

• apollo-server — сервер для обработки GraphQL запросов.
• graphql — ядро языка GraphQL.
• typescript и ts-node — для компиляции и запуска TypeScript.

Настройка TypeScript

Создайте файл tsconfig.json в корне проекта:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Создайте папку src и файл index.ts — в нем будет основной код сервера.

Шаг 2: Определение схемы и типов

Схема GraphQL описывает, какие данные доступны и как их можно запрашивать. В TypeScript мы будем использовать строку с синтаксисом gql для определения типов.

Базовая схема

Откройте src/index.ts и добавьте следующий код:

import { ApolloServer, gql } from 'apollo-server';

const typeDefs = gql`
  type Book {
    id: ID!
    title: String!
    author: String!
  }

  type Query {
    books: [Book]
    book(id: ID!): Book
  }
`;

Здесь мы определили тип Book с полями id, title и author. Query содержит два запроса: получение всех книг и одной книги по ID.

Моковые данные

Для тестирования добавим массив с книгами:

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

Шаг 3: Написание резолверов

Резолверы — это функции, которые возвращают данные для каждого поля схемы. Они связывают схему с реальными данными.

Реализация резолверов

Добавьте объект resolvers:

const resolvers = {
  Query: {
    books: () => books,
    book: (_: any, args: { id: string }) => {
      return books.find(book => book.id === args.id);
    },
  },
};

Первый аргумент _ — это родительский объект (в данном случае не используется). Второй аргумент args содержит параметры запроса, например, id.

Сборка сервера

Теперь создадим экземпляр сервера и запустим его:

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

server.listen().then(({ url }) => {
  console.log(`🚀 Сервер запущен на ${url}`);
});

Полный код файла src/index.ts:

import { ApolloServer, gql } from 'apollo-server';

const typeDefs = gql`
  type Book {
    id: ID!
    title: String!
    author: String!
  }

  type Query {
    books: [Book]
    book(id: ID!): Book
  }
`;

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

const resolvers = {
  Query: {
    books: () => books,
    book: (_: any, args: { id: string }) => {
      return books.find(book => book.id === args.id);
    },
  },
};

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

server.listen().then(({ url }) => {
  console.log(`🚀 Сервер запущен на ${url}`);
});

Шаг 4: Запуск и тестирование

Запуск сервера

В терминале выполните команду:

npx ts-node src/index.ts

Если все настроено правильно, вы увидите сообщение: 🚀 Сервер запущен на http://localhost:4000.

Выполнение запросов

Откройте браузер и перейдите по адресу http://localhost:4000. Вы попадете в Apollo Studio — встроенную IDE для тестирования GraphQL запросов.

Попробуйте выполнить следующие запросы:

Получить все книги:

query {
  books {
    id
    title
    author
  }
}

Получить одну книгу по ID:

query {
  book(id: "1") {
    title
    author
  }
}

Вы увидите JSON-ответ с запрошенными данными. Обратите внимание, что вы можете выбирать только нужные поля — это ключевая особенность GraphQL.

Заключение

Поздравляем! Вы создали свой первый GraphQL API на TypeScript. В этом туториале мы разобрали: