Для чего нужна GraphQL схема?

GraphQL схема - описание возможных запросов

GraphQL схема — это типизированное описание всех данных и операций, которые доступны в GraphQL API. Она определяет структуру данных, возможные запросы, мутации и подписки, которые может выполнять клиент.

Основная проблема, которую решает GraphQL

REST API - много запросов, излишние данные:

// REST: нужно делать несколько запросов
// 1. GET /api/users/123
const user = await fetch('/api/users/123').then(r => r.json());
// { id: 123, name: 'John', email: 'john@example.com', avatar: '...', ...много ненужного }

// 2. GET /api/users/123/posts
const posts = await fetch('/api/users/123/posts').then(r => r.json());
// { items: [ { id: 1, title: '...', content: '...' }, ... ] }

// 3. GET /api/posts/1/comments
const comments = await fetch('/api/posts/1/comments').then(r => r.json());
// { items: [ { id: 1, author: {...}, text: '...' }, ... ] }

GraphQL - один запрос, только нужные данные:

// GraphQL: один запрос
const query = `
  query GetUserWithPosts($id: ID!) {
    user(id: $id) {
      name
      email
      posts {
        title
        comments {
          text
          author { name }
        }
      }
    }
  }
`;

const data = await fetch('/graphql', {
  method: 'POST',
  body: JSON.stringify({ query, variables: { id: 123 } })
}).then(r => r.json());

// Получит РОВНО то, что запросил

Структура GraphQL схемы

Простой пример схемы:

type User {
  id: ID!
  name: String!
  email: String!
  age: Int
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
}

type Comment {
  id: ID!
  text: String!
  author: User!
}

type Query {
  user(id: ID!): User
  users(limit: Int = 10): [User!]!
  post(id: ID!): Post
}

type Mutation {
  createUser(name: String!, email: String!): User!
  deleteUser(id: ID!): Boolean!
}

Типизация в GraphQL:

• String - строка
• Int - целое число
• Float - число с плавающей точкой
• Boolean - да/нет
• ID - уникальный идентификатор
• [Type] - массив типа
• Type! - обязательное поле (не может быть null)

Основные преимущества GraphQL схемы

1. Строгая типизация:

# Схема определяет точные типы
type Query {
  getUserAge(id: ID!): Int!  # Всегда вернет целое число
}

# Ошибки видны до запроса!
# Клиент не может запросить несуществующее поле

2. Самодокументирующийся код:

type User {
  """
  Уникальный идентификатор пользователя
  """
  id: ID!
  
  """
  Полное имя пользователя (обязательно)
  """
  name: String!
}

3. Расширяемость:

# Добавить новое поле безопасно
type User {
  id: ID!
  name: String!
  createdAt: DateTime  # Новое поле, необязательное
}

# Старые клиенты продолжат работать!

Пример использования из фронтенда

1. Запрос данных:

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

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

function UserProfile({ userId }) {
  const { data, loading, error } = useQuery(GET_USER, {
    variables: { id: userId }
  });
  
  if (loading) return <p>Загрузка...</p>;
  if (error) return <p>Ошибка: {error.message}</p>;
  
  return (
    <div>
      <h1>{data.user.name}</h1>
      <p>{data.user.email}</p>
      <ul>
        {data.user.posts.map(post => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  );
}

2. Мутация (изменение данных):

const CREATE_POST = gql`
  mutation CreatePost($title: String!, $content: String!) {
    createPost(title: $title, content: $content) {
      id
      title
      createdAt
    }
  }
`;

function CreatePostForm() {
  const [createPost, { loading }] = useMutation(CREATE_POST);
  
  const handleSubmit = async (formData) => {
    try {
      const result = await createPost({
        variables: {
          title: formData.title,
          content: formData.content
        }
      });
      console.log('Пост создан:', result.data.createPost);
    } catch (error) {
      console.error('Ошибка:', error);
    }
  };
  
  return <form onSubmit={handleSubmit}>...</form>;
}

3. Подписка (реал-тайм обновления):

const ON_NEW_MESSAGE = gql`
  subscription OnNewMessage($roomId: ID!) {
    messageAdded(roomId: $roomId) {
      id
      text
      author { name }
      createdAt
    }
  }
`;

function ChatRoom({ roomId }) {
  const { data, loading } = useSubscription(ON_NEW_MESSAGE, {
    variables: { roomId }
  });
  
  return <div>{data?.messageAdded?.text}</div>;
}

Валидация и автоматическая генерация кода

GraphQL схема обеспечивает:

// 1. Валидация на стороне клиента
const query = `
  query {
    user(id: 123) {
      nonExistentField  // Ошибка! Поля нет в схеме
    }
  }
`;
// GraphQL выдаст ошибку перед отправкой

// 2. Генерация TypeScript типов
// Инструменты вроде graphql-codegen генерируют типы из схемы
import { GetUserQuery } from './generated';

const data: GetUserQuery = response;  // Типизировано!

GraphQL vs REST API

Практические примеры использования

1. Получить только нужные поля:

query {
  user(id: 1) {
    name        # Только имя
    email       # Только email
    # avatar, age и др. НЕ будут получены
  }
}

2. Вложенные запросы:

query {
  user(id: 1) {
    name
    posts {              # Вложенный запрос
      title
      comments {         # Еще более вложенный
        text
        author {
          name
        }
      }
    }
  }
}

3. Переиспользуемые фрагменты:

fragment UserInfo on User {
  id
  name
  email
  avatar
}

query {
  user(id: 1) {
    ...UserInfo    # Вставить фрагмент
  }
  
  allUsers(limit: 5) {
    ...UserInfo    # Переиспользовать
  }
}

Когда использовать GraphQL

Хорошие случаи:

1. Мобильные приложения (экономия трафика)
2. Приложения с разным количеством данных на разных экранах
3. Сложные связанные данные
4. Требуется реал-тайм
5. Кроссплатформенные приложения

Плохие случаи:

1. Простые CRUD операции (REST проще)
2. Файловые загрузки
3. Потоковая передача больших данных
4. Очень простые микросервисы

Лучшие практики

1. Используй nullable и required правильно (знай, когда ! нужен)
2. Группируй связанные поля в типы
3. Документируй типы и поля
4. Версионируй схему осторожно
5. Кэшируй запросы на клиенте
6. Используй persisted queries для производительности