GraphQL в TypeScript: Библиотеки для типобезопасных API

GraphQL в TypeScript: Полный обзор библиотек и инструментов

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

Почему TypeScript для GraphQL?

GraphQL запросы и ответы имеют строгую структуру, а TypeScript позволяет проверять эту структуру на этапе компиляции. Это устраняет целый класс ошибок, связанных с неверными типами данных. Основные преимущества:

• Типобезопасность — автоматическая генерация типов из GraphQL схемы
• Автодополнение — IDE подсказывает поля и типы запросов
• Рефакторинг — изменение схемы автоматически обновляет все клиентские запросы
• Минимизация ошибок — ошибки типов обнаруживаются до выполнения кода

Основные библиотеки для серверной части

1. TypeGraphQL

TypeGraphQL — самая популярная библиотека для создания GraphQL API на TypeScript. Она использует декораторы для определения схемы и резолверов.

Установка:

npm install type-graphql graphql reflect-metadata

Пример объявления типа и резолвера:

import { ObjectType, Field, Int, Resolver, Query, Arg } from "type-graphql";

@ObjectType()
class User {
  @Field(() => Int)
  id: number;

  @Field()
  name: string;

  @Field({ nullable: true })
  email?: string;
}

@Resolver(User)
class UserResolver {
  @Query(() => User, { nullable: true })
  async user(@Arg("id", () => Int) id: number): Promise<User | null> {
    // Логика получения пользователя из БД
    return { id, name: "John", email: "john@example.com" };
  }
}

Сборка схемы:

import { buildSchema } from "type-graphql";

const schema = await buildSchema({
  resolvers: [UserResolver],
  emitSchemaFile: true,
});

2. GraphQL Yoga

GraphQL Yoga — универсальный сервер GraphQL, который отлично работает с TypeScript. Основан на Express, но поддерживает любые платформы.

Установка:

npm install graphql-yoga graphql

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

import { createYoga, createSchema } from "graphql-yoga";
import { createServer } from "node:http";

const schema = createSchema({
  typeDefs: `
    type Query {
      hello: String
      user(id: Int!): User
    }
    type User {
      id: Int!
      name: String
    }
  `,
  resolvers: {
    Query: {
      hello: () => "Hello, GraphQL!",
      user: (_, { id }) => ({ id, name: "Alice" }),
    },
  },
});

const yoga = createYoga({ schema });
const server = createServer(yoga);
server.listen(4000, () => console.log("Server running on http://localhost:4000/graphql"));

Библиотеки для клиентской части

3. Apollo Client (с поддержкой TypeScript)

Apollo Client — мощный клиент для работы с GraphQL. С TypeScript он даёт полную типизацию запросов.

Установка:

npm install @apollo/client graphql

Пример типизированного запроса:

import { gql, useQuery } from "@apollo/client";

const GET_USER = gql`
  query GetUser($id: Int!) {
    user(id: $id) {
      id
      name
      email
    }
  }
`;

interface UserData {
  user: {
    id: number;
    name: string;
    email?: string;
  };
}

function UserProfile({ userId }: { userId: number }) {
  const { loading, data } = useQuery<UserData>(GET_USER, {
    variables: { id: userId },
  });

  if (loading) return <p>Loading...</p>;
  return <p>{data?.user.name}</p>;
}

4. URQL

URQL — лёгкая и гибкая альтернатива Apollo. Отлично типизируется.

Установка:

npm install urql graphql

Пример с TypeScript:

import { createClient, gql, useQuery } from "urql";

const client = createClient({
  url: "http://localhost:4000/graphql",
});

const USERS_QUERY = gql`
  query Users {
    users {
      id
      name
    }
  }
`;

interface UsersData {
  users: Array<{ id: number; name: string }>;
}

function UsersList() {
  const [result] = useQuery<Users