Какие знаешь виды сущностей GraphQL схемы?

Виды сущностей GraphQL схемы

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

1. Типы объектов (Object Types)

Это основные строительные блоки GraphQL схемы. Они представляют объекты, которые можно запрашивать, и содержат поля конкретных типов.

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
  createdAt: DateTime!
}

Каждый тип объекта состоит из:

• Поля (fields) - свойства объекта
• Аргументы (arguments) - параметры, передаваемые в поля
• Типы возвращаемых значений - скалярные типы или другие объекты

2. Скалярные типы (Scalar Types)

Базовые примитивные типы, представляющие листовые значения в GraphQL запросах.

Встроенные скалярные типы:

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

Пользовательские скаляры можно определить в схеме:

scalar DateTime
scalar Email
scalar JSON

3. Типы перечислений (Enum Types)

Определяют фиксированный набор допустимых значений.

enum UserRole {
  ADMIN
  EDITOR
  VIEWER
  GUEST
}

enum SortOrder {
  ASC
  DESC
}

4. Интерфейсы (Interfaces)

Абстрактные типы, которые определяют набор полей, которые должны быть реализованы конкретными типами.

interface Node {
  id: ID!
}

interface SearchResult {
  title: String!
  relevance: Float!
}

type User implements Node & SearchResult {
  id: ID!
  title: String!
  relevance: Float!
  email: String!
}

5. Типы объединений (Union Types)

Представляют тип, который может быть одним из нескольких типов объектов.

union SearchResult = Book | Author | Review

type Book {
  title: String!
  author: String!
}

type Author {
  name: String!
  books: [Book!]!
}

6. Типы ввода (Input Types)

Специальные типы для передачи сложных данных в аргументах мутаций и запросов.

input UserInput {
  name: String!
  email: String!
  password: String!
  role: UserRole = VIEWER
}

input PaginationInput {
  limit: Int! = 10
  offset: Int! = 0
  sortBy: String = "createdAt"
}

7. Корневые типы (Root Types)

Определяют точки входа для GraphQL операций.

type Query {
  getUser(id: ID!): User
  getPosts(filter: PostFilter): [Post!]!
  search(query: String!): SearchResult
}

type Mutation {
  createUser(input: UserInput!): User!
  updateUser(id: ID!, input: UserInput!): User!
  deleteUser(id: ID!): Boolean!
}

type Subscription {
  userCreated: User!
  postUpdated(postId: ID!): Post!
}

8. Директивы (Directives)

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

Встроенные директивы:

• @deprecated - помечает поле как устаревшее
• @skip - пропускает поле при выполнении
• @include - включает поле только при выполнении условия

Пользовательские директивы:

directive @auth(role: UserRole!) on FIELD_DEFINITION
directive @rateLimit(max: Int, window: String) on FIELD_DEFINITION

type Query {
  adminData: String! @auth(role: ADMIN)
  sensitiveInfo: String! @rateLimit(max: 100, window: "1h")
}

9. Модификаторы типов

Специальные обозначения, изменяющие поведение типов:

• ! (NonNull) - указывает, что значение не может быть null
• [] (List) - обозначает массив значений
• Комбинации: [String!]! - ненулевой массив ненулевых строк

Практическое применение

В реальных проектах структура GraphQL схемы обычно организуется следующим образом:

# Основные типы
type Query {
  # Запросы данных
}

type Mutation {
  # Изменения данных
}

type Subscription {
  # Подписки на изменения
}

# Доменные объекты
type Product {
  id: ID!
  name: String!
  price: Float!
  category: Category!
}

# Входные данные
input ProductFilter {
  categoryId: ID
  minPrice: Float
  maxPrice: Float
  inStock: Boolean
}

# Перечисления
enum SortDirection {
  ASC
  DESC
}

Важность понимания сущностей

Каждая сущность GraphQL схемы играет важную роль:

1. Типы объектов обеспечивают структуру ответов
2. Скаляры и перечисления определяют элементарные значения
3. Интерфейсы и объединения обеспечивают полиморфизм
4. Типы ввода стандартизируют передачу данных
5. Директивы добавляют метапрограммирование

Грамотное использование всех видов сущностей позволяет создавать выразительные, типобезопасные и эффективные API, которые легко развивать и поддерживать. Современные инструменты GraphQL, такие как Apollo Server или GraphQL Yoga, предоставляют дополнительные возможности для расширения стандартных сущностей через плагины и middleware.