Архитектура и принципы работы GraphQL
Что происходит между клиентом, схемой и источниками данных


1. Главная идея архитектуры

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

Он не хранит данные сам по себе.
GraphQL — это не база данных, а универсальный интерфейс к любому источнику данных: SQL, NoSQL, микросервисы, REST, файлы, внешние API.
Его задача — связать клиентскую структуру запроса со структурой данных в бэкенде.

Схематично:
Клиент → GraphQL сервер → Источники данных (DB, REST, gRPC, API)


2. Schema — сердце GraphQL

Schema (схема) — это основной контракт между клиентом и сервером.

Она описывает:
какие данные доступны;
какие поля у этих данных есть;
какие операции можно выполнять.

Схема написана на SDL (Schema Definition Language), декларативном языке, напоминающем описание классов.

Пример:

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

type Post {
  id: ID!
  title: String!
  content: String
}

type Query {
  user(id: ID!): User
  allUsers: [User!]!
}

Ключевые понятия:
type — определяет структуру данных (аналог Java-класса или DTO).
! — обязательное поле (non-null).
[User!]! — список пользователей, где ни один элемент не равен null.
Query — специальный тип, описывающий операции чтения.

Схема — это не код, а декларация.
На её основе GraphQL сервер автоматически понимает, как валидировать запросы, какие поля допустимы и какие возвращать ошибки.


3. Query, Mutation, Subscription — три типа операций

GraphQL разделяет все действия на три категории.

1. Query — запрос данных (аналог GET в REST)
Используется для чтения.

Клиент описывает, какие сущности и поля нужны:

query {
  user(id: 42) {
    name
    posts {
      title
    }
  }
}

Сервер вернёт данные в том же формате:

{
  "data": {
    "user": {
      "name": "Den",
      "posts": [
        { "title": "gRPC и Java" },
        { "title": "GraphQL под капотом" }
      ]
    }
  }
}

2. Mutation — изменение данных (аналог POST/PUT/DELETE)
Mutation обозначает действия, которые модифицируют состояние системы.
Они могут создавать, обновлять или удалять записи.

mutation {
  createUser(input: { name: "Alex" }) {
    id
    name
  }
}

GraphQL возвращает результат — обновлённые данные или подтверждение операции.

3. Subscription — подписка на события (реактивный поток)
Subscription создаёт постоянное соединение между клиентом и сервером (обычно через WebSocket).
Когда на сервере происходят изменения, клиент получает уведомления в реальном времени.

subscription {
  userCreated {
    id
    name
  }
}

Если на сервере создан новый пользователь, событие userCreated автоматически отправляется всем подписанным клиентам.


4. Как работает запрос GraphQL: путь от клиента до данных

Чтобы понять механику, посмотрим на полный цикл обработки запроса.

Шаг 1. Клиент отправляет запрос

Клиент (например, браузер) отправляет HTTP POST на /graphql с JSON-телом:

{
  "query": "query { user(id: 42) { name posts { title } } }"
}

GraphQL-запрос — это декларативное описание структуры данных, не код и не SQL.

Шаг 2. Сервер парсит и валидирует запрос

GraphQL-сервер:
Парсит текст запроса.
Проверяет, что все поля и типы существуют в схеме.
Проверяет типы аргументов (id действительно ID!).
Отклоняет запрос, если нарушен контракт схемы.

Таким образом, сервер никогда не выполнит запрос, который не соответствует схеме.
Это гарантирует типобезопасность и предсказуемость работы.


#Java #middle #GraphQL

Шаг 3. Сервер вызывает резолверы

Резолвер (resolver) — это функция, которая знает, как получить данные для конкретного поля.

Например, в Java через библиотеку graphql-java:

GraphQLObjectType userType = newObject()
    .name("User")
    .field(field -> field
        .name("id")
        .type(Scalars.GraphQLID))
    .field(field -> field
        .name("name")
        .type(Scalars.GraphQLString))
    .field(field -> field
        .name("posts")
        .type(new GraphQLList(postType))
        .dataFetcher(env -> postService.getByUser(env.getSource())))
    .build();

Резолверы вызываются рекурсивно:
Сначала выполняется user(id: 42).
Затем для каждого пользователя — posts.
Затем для каждого поста — title.

GraphQL умеет оптимизировать выполнение: например, группировать одинаковые вызовы (DataLoader паттерн).

Шаг 4. Формирование ответа

После выполнения всех резолверов GraphQL собирает результат в структуру, повторяющую форму запроса, и отправляет JSON-ответ клиенту:

{
  "data": {
    "user": {
      "name": "Den",
      "posts": [{ "title": "gRPC и Java" }]
    }
  }
}

Если на каком-то шаге произошла ошибка, она не прерывает всё выполнение.

GraphQL вернёт частичные данные + список ошибок:

{
  "data": { "user": null },
  "errors": [{ "message": "User not found" }]
}

5. Почему GraphQL — не база данных

Эта путаница встречается часто.
GraphQL не хранит и не управляет данными.
Он не заменяет SQL или ORM.

GraphQL — это API-уровень, который:
принимает запросы,
интерпретирует их,
вызывает нужные источники данных,
собирает и возвращает результат в едином формате.

Под капотом это может быть:
JDBC-запросы в PostgreSQL,
вызовы REST API других микросервисов,
gRPC-вызовы,
кэш Redis,
файловая система или внешние API.

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


6. Интеграция GraphQL в бэкенд

GraphQL не заменяет ваш backend — он становится поверх него.

В Java это обычно выглядит так:
Spring Boot + graphql-spring-boot-starter — стандартный способ поднять GraphQL-сервер.
Схема (.graphqls) описывается декларативно.
Резолверы реализуются как обычные Spring-бины.

Пример:

@Component
public class UserResolver implements GraphQLQueryResolver {
    private final UserService userService;
    public UserResolver(UserService userService) { this.userService = userService; }

    public User user(Long id) {
        return userService.findById(id);
    }

    public List<User> allUsers() {
        return userService.findAll();
    }
}

GraphQL сам вызывает нужный метод в зависимости от запроса клиента.

Таким образом, GraphQL интегрируется поверх существующего слоя сервисов и репозиториев, не требуя переписывания бизнес-логики.

#Java #middle #GraphQL

Определение схемы в GraphQL (SDL)

SDL (Schema Definition Language) — это декларативный язык описания GraphQL-схем.
Он задаёт структуру данных и операций, доступных клиенту.
SDL не содержит логики — это контракт, который определяет «форму» API: какие типы есть, какие поля у них доступны, какие аргументы принимаются.

GraphQL-сервер использует SDL как единый источник правды для валидации запросов и построения выполнения.


1. Основные виды типов в SDL

GraphQL предоставляет несколько видов типов, каждый из которых отвечает за свою роль.

1. type — объектный тип (основа схемы)

Используется для описания сущностей:

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

Типы описывают структуру данных — аналог классов/DTO.

2. input — тип вводимых данных

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

input CreateUserInput {
  name: String!
  age: Int
}

3. enum — перечисления

Хороший способ ограничить варианты.

enum Role {
  ADMIN
  USER
  GUEST
}

4. interface — абстрактный тип

Позволяет описывать общий контракт нескольких типов.

interface Entity {
  id: ID!
}

type User implements Entity {
  id: ID!
  name: String!
}

type Post implements Entity {
  id: ID!
  title: String!
}

Клиент может запросить id для любого, кто реализует Entity.

5. union — объединение разных типов

Не имеет общих полей.
Используется, когда ответ может быть разным по структуре.

union SearchResult = User | Post | Comment

2. Как выглядит схема GraphQL

В GraphQL схема определяется набором корневых операций:
Query — чтение
Mutation — изменение
Subscription — события/стриминг

Пример минимальной структуры:

schema {
  query: Query
  mutation: Mutation
}

На практике «schema {}» часто опускают — сервер выводит её автоматически.


3. Полный пример схемы: пользователи, посты и комментарии

Ниже — типичная схема блог-платформы, написанная в чистом SDL.

Сущности
type User {
  id: ID!
  name: String!
  role: Role!
  posts: [Post!]!
}

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

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

Перечисления
enum Role {
  ADMIN
  USER
  GUEST
}

Входные данные
input CreatePostInput {
  title: String!
  content: String
}

Запросы
type Query {
  user(id: ID!): User
  users: [User!]!

  post(id: ID!): Post
  posts(limit: Int, authorId: ID): [Post!]!
}

Мутации
type Mutation {
  createPost(input: CreatePostInput!): Post!
  deletePost(id: ID!): Boolean!
}

Подписки
type Subscription {
  postCreated: Post!
}

#Java #middle #GraphQL

4. Как схема связана с кодом

SDL — декларация.
Сервер должен сопоставить поля типам данных и резолверам.

Java (graphql-java, Spring for GraphQL)

SDL:

type Query {
  user(id: ID!): User
}

Резолвер:

@Component
public class UserResolver implements GraphQLQueryResolver {
    private final UserService service;

    public UserResolver(UserService service) {
        this.service = service;
    }

    public User user(Long id) {
        return service.findById(id);
    }
}

GraphQL автоматически соединяет:
поле user → метод user класса UserResolver
аргумент id → параметр метода

На что важно смотреть в связке схема - код

SDL описывает только форму данных, не логику.
Все поля объектных типов должны иметь резолверы (кроме простых полей, которые GraphQL просто читает из объекта).
input использует DTO-классы.
enum маппится на Enum-класс.
union и interface требуют регистрации type resolver-а.


5. Эволюция схемы: изменение и поддержка версий

GraphQL спроектирован так, чтобы обеспечивать обратную совместимость.
Важный принцип: старые клиенты должны продолжать работать после обновлений.

1. Добавление полей — безопасная операция

Можно безболезненно добавлять:
новые поля в типы
новые аргументы с default value
новые типы
новые enum-значения (если клиенты готовы к неизвестным значениям)

Пример:

type User {
  id: ID!
  name: String!
  email: String # новое поле
}

2. Деприкация полей

Поле нельзя удалить сразу — сначала его помечают как @deprecated.

type User {
  id: ID!
  name: String!

  # старое поле
  username: String @deprecated(reason: "Use 'name' instead")
}

Клиентский код и инструменты разработчика (GraphiQL, GraphQL Codegen) предупредят о деприкации.

3. Удаление полей

Удалять поле можно только после:
уведомления клиентов,
завершения миграции SDK/фронта,
истечения grace-period'a.

4. Эволюция enum-ов

Добавлять значения — безопасно.
Удалять — нет.

5. Миграции input-типов

Если нужно изменить входные данные:

Старое:
input CreatePostInput {
  title: String!
}

Новое:
input CreatePostInput {
  title: String!
  content: String @deprecated(reason: "Use body instead")
  body: String
}

#Java #middle #GraphQL

Запросы и мутации в GraphQL

GraphQL опирается на две основные операции:
Query — безопасные операции чтения данных.
Mutation — операции изменения состояния (создание, обновление, удаление).

Обе операции используют один и тот же язык запросов, отличаются только семантикой:
Query не влияет на состояние системы, Mutation — влияет.


1. Как выглядит запрос (Query)

GraphQL-запрос — декларативное описание структуры данных, которую клиент хочет получить.

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

query {
  user(id: 42) {
    name
    avatar
  }
}

Здесь:
query — тип операции (можно опустить: GraphQL сам определит, что это запрос).
user(id: 42) — вызов поля корневого типа Query.
{ name, avatar } — конкретные поля, которые клиент хочет получить.

GraphQL не вернёт дополнительные поля и не допустит отсутствующих — запрос полностью определяет форму ответа.

Ответ будет ровно такой:

{
  "data": {
    "user": {
      "name": "Den",
      "avatar": "https://example.com/den.png"
    }
  }
}

Никаких “лишних” полей.

2. Как работает передача аргументов

Аргументы передаются в круглых скобках и могут быть любого типа, определённого в схеме:
скаляры, enum, input-объекты.

Пример схемы:

type Query {
  posts(limit: Int, authorId: ID): [Post!]!
}

Пример запроса:

query {
  posts(limit: 5, authorId: 42) {
    id
    title
  }
}

Ответ будет:

{
  "data": {
    "posts": [
      { "id": "101", "title": "GraphQL SDL" },
      { "id": "102", "title": "gRPC vs GraphQL" }
    ]
  }
}

2.1. Переменные запроса (не хардкодим аргументы)

GraphQL поддерживает variables, что особенно важно для фронтенда.

Запрос:

query GetUser($id: ID!) {
  user(id: $id) {
    name
    avatar
  }
}

Передаваемые переменные:

{
  "id": 42
}

Сервер объединяет запрос с переменными и выполняет его.

Преимущества переменных:
запрос можно кэшировать,
тело операции не меняется,
безопаснее, чем вставлять значения в строку.


3. Что делает Mutation

Mutation изменяет данные.

Пример схемы:

type Mutation {
  createPost(input: CreatePostInput!): Post!
}

Пример запроса:

mutation {
  createPost(input: { title: "GraphQL", content: "SDL explained" }) {
    id
    title
  }
}

Mutation возвращает объект результата, содержащий новое состояние или подтверждение.

Ответ:

{
  "data": {
    "createPost": {
      "id": "501",
      "title": "GraphQL"
    }
  }
}

Важный принцип:
Mutation считается одиночной транзакцией.
Даже если внутри происходит много действий, GraphQL гарантирует их упорядоченное выполнение.


4. Возврат данных в нужной форме

GraphQL всегда возвращает данные:
в структуре, которую запросил клиент
в иерархии, описанной в запросе
строго тех типов, которые указаны в схеме

Пример: вложенная выборка.

query {
  user(id: 1) {
    name
    posts(limit: 2) {
      title
      comments {
        text
      }
    }
  }
}

Ответ:

{
  "data": {
    "user": {
      "name": "Den",
      "posts": [
        {
          "title": "GraphQL Basics",
          "comments": [
            { "text": "Отличная статья" }
          ]
        },
        {
          "title": "SDL Tutorial",
          "comments": []
        }
      ]
    }
  }
}

Сервер не может изменить структуру ответа — она определяется клиентом.

#Java #middle #GraphQL #Query #Mutation

5. Ошибки и partial responses

GraphQL всегда возвращает JSON-объект с двумя ключами:

data

errors

Что важно:
GraphQL может вернуть часть данных, даже если произошла ошибка.

пример: запрос

query {
  user(id: 1) {
    name
    posts {
      title
      likes
    }
  }
}

допустим, поле posts упало из-за ошибки в БД.

Ответ:

{
  "data": {
    "user": {
      "name": "Den",
      "posts": null
    }
  },
  "errors": [
    {
      "message": "Database timeout",
      "path": ["user", "posts"]
    }
  ]
}

GraphQL:
не останавливает выполнение всего запроса,
возвращает то, что смог,
указывает путь к проблемному полю.
Это концепция partial response, которой нет ни в REST, ни в gRPC.


6. Как Mutation обрабатывает ошибки

Mutation также может вернуть частичный результат, но чаще ошибка означает, что произошло отклонение операции:

{
  "data": {
    "createPost": null
  },
  "errors": [
    {
      "message": "User not authorized",
      "path": ["createPost"]
    }
  ]
}

GraphQL намеренно не использует коды HTTP-статуса, кроме:
200 — запрос обработан
400 — синтаксическая ошибка запроса
500 — ошибка самого сервера GraphQL (не бизнес-ошибка)


#Java #middle #GraphQL #Query #Mutation

Фрагменты, директивы и переменные

GraphQL — декларативный язык, но его мощь раскрывается по-настоящему, когда вы начинаете использовать фрагменты, директивы и переменные.

Эти инструменты позволяют:
избегать дублирования запросов,
включать или исключать поля динамически,
передавать аргументы безопасно,
строить сложные запросы, сохраняя читаемость.


1. Фрагменты

Фрагмент (fragment) — это именованный блок запроса, который описывает набор полей.
Он позволяет вынести общую часть и использовать её в нескольких местах.

Главная цель: избежать повторов полей.

Пример без фрагментов:

query {
  user(id: 1) {
    id
    name
    avatar
  }
  post(id: 10) {
    author {
      id
      name
      avatar
    }
  }
}

Повторяются три поля id, name, avatar.

Версия с фрагментом

fragment UserBasic on User {
  id
  name
  avatar
}

query {
  user(id: 1) {
    ...UserBasic
  }
  post(id: 10) {
    author {
      ...UserBasic
    }
  }
}

Теперь изменения структуры (например, добавление role) делаются в одном месте — фрагменте.

Как работает фрагмент
fragment UserBasic on User — объявление фрагмента.
User — тип, которому фрагмент принадлежит.
...UserBasic — вставка фрагмента.
Фрагменты можно вкладывать друг в друга и использовать с union и interface.

Кейсы, где фрагменты обязательны
Одинаковая структура данных в нескольких частях UI
Профили пользователей, карточки, списки.

Сложные запросы с глубокой вложенностью
Общие части выносятся в фрагменты.

Работа с interface и union
Позволяют описывать поля для нескольких типов.

Крупные запросы с десятками полей
Легче читать, тестировать и поддерживать.


2. Директивы

Директивы — это аннотации, которые модифицируют выполнение запроса.
Они влияют на структуру данных, которые вернёт сервер.

GraphQL имеет встроенные директивы и позволяет создавать свои.

2.1 Директива @include

Поле будет включено только если условие истинно.

query GetUser($showAvatar: Boolean!) {
  user(id: 1) {
    name
    avatar @include(if: $showAvatar)
  }
}

Переменные:

{ "showAvatar": true }

Если showAvatar = false, поле avatar пропадёт из ответа целиком.

2.2 Директива @skip

Обратная логика:

avatar @skip(if: $binaryMode)

Если binaryMode = true, поле будет пропущено.

2.3 Директива @deprecated

Помечает поле устаревшим.

type User {
  username: String @deprecated(reason: "Use 'name' instead")
}

Эта директива влияет на документацию и IDE, но не на данные.

2.4 Кастомные директивы

Пример (схема):

directive @upper on FIELD_DEFINITION

Резолвер может модифицировать строку на лету (например, вернуть верхний регистр).
Это используется для логирования, авторизации, кеширования, маскирования данных.


3. Переменные в запросах

Переменные — это место, где GraphQL становится особенно полезным.
Они позволяют использовать один и тот же запрос с разными параметрами, не переписывая запрос.

3.1 Базовый пример

Запрос:

query GetPost($id: ID!) {
  post(id: $id) {
    title
    content
  }
}

Переменные:

{
  "id": 100
}

Сервер соединяет тело запроса и переменные и выполняет.

3.2 Переменные для input-объектов (в мутациях)

Мутация:

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    title
  }
}

Переменные:

{
  "input": {
    "title": "GraphQL",
    "content": "Powerful queries"
  }
}

Это безопаснее, чем писать input прямо в теле мутации.

3.3 Комбинирование переменных с директивами

query User(
  $id: ID!,
  $withPosts: Boolean!
) {
  user(id: $id) {
    name
    posts @include(if: $withPosts) {
      title
    }
  }
}

Комбинация:
один запрос,
два режима вывода данных,
ноль дублирования.


#Java #middle #GraphQL #Query

4. Реальные производственные кейсы

Кейc 1: мобильная и web-версия используют разные наборы полей

query User(
  $id: ID!,
  $isMobile: Boolean!
) {
  user(id: $id) {
    name
    avatar @skip(if: $isMobile)
    posts @include(if: $isMobile) {
      title
    }
  }
}

Мобильный клиент получает минимум данных.
Web — максимум.

Кейc 2: переиспользование структуры пользователя

fragment UserCard on User {
  id
  name
  avatar
}

query PageData {
  recommendedUsers { ...UserCard }
  recentVisitors { ...UserCard }
  followers { ...UserCard }
}

Все блоки страницы используют одну структуру.
CRM-интерфейсы любят такое.

Кейc 3: миграции схемы через директивы

Старая модель:

username @deprecated(reason: "Use 'login' instead")

Frontend получает предупреждение в IDE — никаких тайных поломок.

Кейc 4: сложные фильтры в одном запросе

query FilterPosts($filter: PostFilter!) {
  posts(filter: $filter) {
    id
    title
  }
}

Переменные:

{
  "filter": {
    "authorId": 1,
    "tags": ["graphql", "java"],
    "minLikes": 10
  }
}

#Java #middle #GraphQL #Query

Реализация GraphQL на сервере


1. Как сервер “понимает” запросы

GraphQL — это не просто формат данных. Это полноценный язык запросов, который сервер интерпретирует строжайшим образом.

На сервере присутствуют три ключевых компонента:
Схема (Schema) — декларативное описание типов, запросов, мутаций и подписок.
Исполнитель (Executor) — механизм, который умеет разбирать, валидировать и выполнять запросы.
Резолверы (resolvers) — функции, которые реально достают данные.

Процесс обработки запроса выглядит так:

Шаг 1. Парсинг
Запрос, полученный в виде строки, разбирается в AST (абстрактное синтаксическое дерево).
GraphQL понимает только корректный язык запросов, поэтому на этом этапе запрос может быть отклонён.

Шаг 2. Валидация
AST сравнивается со схемой.

Сервер проверяет:
существуют ли указанные поля;
правильно ли переданы аргументы;
корректны ли типы;
не запрошены ли деприкейтнутые или отсутствующие типы.
Если запрос не соответствует схеме, сервер вообще не перейдёт к резолверам.

Шаг 3. Выполнение
GraphQL выполняет запрос сверху вниз, проходя по полям и вызывая резолверы там, где они определены.

GraphQL никогда не “догадывается”, где лежат данные.
Он лишь исполняет дерево запроса, вызывая привязанные функции.


2. Роль резолверов (resolvers)

Резолвер — это функция, которая отвечает на вопрос:
“Как получить данные для этого конкретного поля?”

В GraphQL у каждого поля может быть свой резолвер, хотя обычно определяют резолверы для корневых типов: Query, Mutation, Subscription.

Резолвер принимает три основных аргумента:
parent — результат предыдущего резолвера (нужен для вложенных структур);
args — аргументы, которые указал клиент;
context — общий контекст запроса (авторизация, транзакция, соединения с БД).

Пример простого резолвера на Java (Spring Boot + graphql-java-tools):

@Component
public class UserQueryResolver implements GraphQLQueryResolver {

    private final UserService service;

    public UserQueryResolver(UserService service) {
        this.service = service;
    }

    public User userById(Long id) {
        return service.findById(id);
    }
}

Резолвер выполняет ровно одну задачу: достать данные.
GraphQL не хранит состояние, не кэширует данные, не соединяется с БД — всё это делает твой код через резолверы.


3. Маппинг схемы на реальные источники данных

GraphQL — это уровень между клиентом и данными.

Источники могут быть любыми:
реляционная БД (PostgreSQL);
документоориентированная БД (MongoDB);
REST API других микросервисов;
gRPC сервисы;
сообщения из Kafka;
кэш Redis.

GraphQL не диктует, где должны лежать данные. Он просто обеспечивает единый интерфейс запросов.

Пример маппинга:

type Query {
    user(id: ID!): User
}

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

Резолверы:

@Component
public class UserResolver implements GraphQLResolver<User> {

    private final PostService postService;

    public UserResolver(PostService postService) {
        this.postService = postService;
    }

    public List<Post> posts(User user) {
        return postService.findByUserId(user.getId());
    }
}

GraphQL вызывает posts() только если клиент запросит поле posts.
Если клиент запросит только user { id name }, резолвер posts не будет вызван вообще.

Отсюда следует ключевой принцип:
сервер выполняет только то, что клиент запросил — ни больше, ни меньше.


#Java #middle #GraphQL

4. Типичная архитектура GraphQL-сервера (Spring Boot)

Структура проекта в Java обычно такая:

/graphql
  /schema
    schema.graphqls

/resolvers
  QueryResolver.java
  MutationResolver.java
  UserResolver.java
  PostResolver.java

/services
  UserService.java
  PostService.java

/repositories
  UserRepository.java
  PostRepository.java

Описание этапов:

Схема
Файл .graphqls описывает типы и операции.

Резолверы
Связывают поля схемы с Java-методами.

Сервисы
Логика бизнес-операций.

Репозитории
SQL/NoSQL/REST/gRPC слой, через который сервер реально получает данные.

Context
Сюда кладут:
JWT токен
объект пользователя
транзакции
общие ресурсы


5. Пример полного цикла запроса

Клиент отправляет запрос:

query {
    user(id: 10) {
        id
        name
        posts {
            id
            title
        }
    }
}

Что делает сервер:
Парсит запрос → AST
Проверяет типы по схеме
Вызывает QueryResolver.user(id=10)
Получает объект User
Чтобы отдать поле posts, вызывает UserResolver.posts(user)
Формирует объект ответа, возвращает клиенту JSON

Клиент всегда получает именно ту форму данных, которую указал.
Сервер не отдаёт лишних полей.


6. Почему GraphQL — это слой поверх данных, а не база данных

GraphQL:
не знает SQL;
не оптимизирует запросы;
не управляет транзакциями;
не индексирует данные;
не проверяет связи между таблицами.

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

Он лишь обеспечивает:
строгую структуру данных (схему)
гибкие запросы от клиента
единый интерфейс ко множеству источников
оптимизацию на уровне поля (через резолверы)

Всё остальное — на стороне backend-логики.


#Java #middle #GraphQL

GraphQL vs REST vs gRPC

REST — ресурсно-ориентированный HTTP API, обычно JSON по HTTP/1.1. Прост, совместим с любым клиентом, хорош для публичных и простых API.
GraphQL — язык запросов + схема; клиент сам описывает форму данных. Один эндпоинт, строгая схема, гибкость запросов, удобен для фронтенда.
gRPC — RPC-фреймворк на основе HTTP/2 + Protocol Buffers; строгие контракты (.proto), бинарная сериализация, встроенный стриминг. Ориентирован на высокую производительность и внутренние сервисы.


Формат данных

REST → JSON (текстовый, человекочитаемый).
GraphQL → JSON-ответ, но запросы декларативны и строго типизированы схемой.
gRPC → Protocol Buffers (бинарный), компактно, фиксированные поля.
Вывод: protobuf обычно экономит трафик и парсится быстрее; JSON удобнее для дебага и совместимости.

Протокол транспорта

REST → HTTP/1.1 (обычно), можно HTTP/2, но без нативного стриминга.
GraphQL → обычно HTTP/1.1 POST/GET для Query/Mutation; Subscription — WebSocket или HTTP/2 SSE.
gRPC → HTTP/2 по умолчанию, мультиплексирование, потоковые фреймы, двунаправленность.
Вывод: для потоковых сценариев и мультиплексирования gRPC технически лучше.

Типы взаимодействия

REST → запрос/ответ (stateless).
GraphQL → query/mutation/subscription; один запрос может агрегировать много сущностей.
gRPC → unary, server streaming, client streaming, bidirectional streaming (всё на уровне протокола).
Вывод: если нужны сложные стримы и двунаправленные каналы — gRPC.

Типизация и контракт

REST → схема часто нестрогая (OpenAPI/Swagger добавляет контракт).
GraphQL → строгая схема (SDL).
gRPC → строгие контракты (.proto).
Вывод: GraphQL и gRPC обеспечивают статический контракт; REST требует дополнительных инструментов для той же дисциплины.

Производительность (в общих чертах)

gRPC обычно выигрывает по пропускной способности и латентности за счёт бинарной сериализации и HTTP/2.
GraphQL может быть эффективным по числу запросов (агрегация) и по уменьшению round-trip’ов, но JSON+резолверы добавляют накладные расходы.
REST проще и зачастую медленнее при больших объёмах и при множественных запросах с агрегацией.
Вывод: для внутренней коммуникации между сервисами с высокой нагрузкой — gRPC; для клиентского слоя — GraphQL/REST в зависимости от потребностей.

Эволюция API и версияция

REST → часто версионируют (/v1/) или добавляют параметры; ломкость при изменениях.
GraphQL → расширяемость без версий (добавление полей безопасно), депрекация поддерживается.
gRPC → совместимость через правила protobuf (резервирование, добавление новых полей безопасно при соблюдении правил).
Вывод: GraphQL и gRPC дают удобные инструменты для эволюции без жесткой версии.

Инструментальная поддержка и экосистема

REST → универсальная поддержка, простые средства тестирования.
GraphQL → богатая экосистема: GraphiQL, Apollo, Relay, Codegen. Отлично для фронтенда.
gRPC → генерация стубов под любые языки, хорошие SDK для серверов и клиентов; браузерная поддержка требует gRPC-Web.
Вывод: выбор зависит от клиентской среды: браузер напрямую лучше работает с REST/GraphQL; для gRPC нужен шлюз (gRPC-Web) или прокси.


#Java #middle #GraphQL

Практические сценарии

публичный HTTP API для сторонних клиентов (публичная документация)

Выбор: REST или GraphQL
Почему: совместимость, простота, отсутствие необходимости требованиям к бинарному протоколу.
REST, если API простое, CRUD-ориентированное, нужно кэширование по URL и широчайшая совместимость.
GraphQL, если клиенты (много разных) требуют разные наборы данных и важно уменьшить число запросов.

фронтенд (SPA, мобильные клиенты) с разнообразными представлениями

Выбор: GraphQL
Почему: клиент сам формирует shape ответов; экономия round-trips; отличная интеграция с Apollo/Relay; кодогенерация типов для TS/Swift/Kotlin.

внутренняя связь между микросервисами с высокой нагрузкой

Выбор: gRPC
Почему: низкая латентность, компактность, стриминг, строгие контракты, удобная кодогенерация для множества языков.

real-time (чат, телеметрия, видео/аудио)

Выбор: gRPC (bidirectional) или GraphQL Subscriptions (WebSocket)
Почему: gRPC даёт нативный поток; GraphQL Subscriptions удобны для фронтенда, но требуют инфраструктуры и могут быть сложнее в масштабировании.

интеграция с legacy REST-сервисами

Выбор: GraphQL в качестве BFF (Backend-for-Frontend) или REST-шлюз
Почему: GraphQL может агрегировать несколько REST-вызовов и отдать клиенту нужную структуру.


Почему часто комбинируют: GraphQL для клиентов, gRPC для микросервисов

Это распространённый и рациональный паттерн:
Внутренние сервисы общаются по gRPC (эффективно, типобезопасно, стриминг).
BFF / API Gateway (или отдельный GraphQL-сервер) агрегирует данные из gRPC/REST/БД и предоставляет фронту единый, гибкий интерфейс.
Фронтенд работает с GraphQL (или REST), не заботясь о том, как именно данные доставлены внутри инфраструктуры.

Преимущества паттерна:
Отделение оптимизации внутренней сетевой коммуникации (gRPC) от удобства клиентских API (GraphQL).
Централизация логики агрегации и адаптации под клиентов.
Возможность менять внутреннюю реализацию без ломки фронта.

Пример (псевдокод Java resolver, вызывающий gRPC-stub):

// GraphQL resolver
public class UserResolver {
    private final UserGrpc.UserBlockingStub userStub;

    public UserResolver(UserGrpc.UserBlockingStub userStub) {
        this.userStub = userStub;
    }

    public User getUser(String id) {
        UserRequest req = UserRequest.newBuilder().setId(id).build();
        UserResponse resp = userStub.getUser(req); // gRPC call to internal service
        return mapToGraphQLUser(resp);
    }
}

Детальный разбор преимуществ и ограничений

Удобство разработки
REST: быстро стартовать, понятная модель. Но при сложных клиентских потребностях растёт число эндпоинтов.
GraphQL: позволяет фронтенду быстро изменять данные без координации с бэком, но требует работы со схемой и авторизацией на уровне полей.
gRPC: требует .proto и генерации стабов, но даёт сильную типизацию и меньше рутинного кода при изменениях.

Кеширование
REST: простое кеширование по URL (HTTP caches, CDNs).
GraphQL: кеширование сложнее — операция может возвращать разные поля; решения: persisted queries, apollo cache, CDN на уровне persisted queries/operation id.
gRPC: кеширование на транспортном уровне сложнее; обычно кешируют ответы в сервисах.

Отладка и наблюдаемость
REST: легко отлаживать (curl, браузер).
GraphQL: дебаг через GraphiQL/Apollo Studio; трассировка полей сложнее (нужны field-level metrics).
gRPC: бинарные пакеты труднее смотреть вручную; нужно подходящие инструменты (grpcurl, tshark + protobuf descriptors).

Безопасность и авторизация

REST: стандартные механизмы (OAuth, JWT, TLS).
GraphQL: нужно управлять авторизацией на уровне полей (field-level), чтобы не раскрывать данные; также важны depth-limiting, query complexity limiting, persisted queries.
gRPC: поддерживает mTLS, аутентификацию/авторизацию через metadata; access control реализуется в сервисах.

Количество сетевых вызовов / latency
GraphQL часто уменьшает RTT за счёт агрегации (один запрос вместо множества).
gRPC уменьшает сетевые накладные расходы: меньше байт, лучше TCP connection reuse, HTTP/2 мультиплексирование.


#Java #middle #GraphQL

Практические шаблоны интеграции (patterns)

1) BFF (Backend-for-Frontend) — GraphQL на фронте + gRPC внутри

GraphQL агрегатор (BFF) вызывает gRPC сервисы, комбинирует ответы и отдаёт клиенту.
Позволяет хранить оптимизированные внутр. контракты и независимую клиентскую схему.

2) API Gateway с трансляцией

gRPC Gateway (прокси) экспонирует REST/JSON поверх gRPC-сервисов или наоборот.
Полезно для совместимости с внешними клиентами.

3) Dual API

Предоставлять одновременно REST (для публичного потребления) и GraphQL (для интерактивного фронта).
Поддерживать один источник данных и разные фасады.

4) Persisted Queries + CDN

Для GraphQL: генерировать хэш-запросов (operationId) и кэшировать на CDN; уменьшает payload и риск DoS.


Частые ошибки

Выбор gRPC для публичного браузерного API без gRPC-Web — приведёт к дополнительной сложности (нужен прокси).
GraphQL без контроля сложности — клиенты могут генерировать тяжёлые запросы (глубокая вложенность). Нужно ставить лимиты.
REST для сложной фронт-логики — приведёт к множеству эндпоинтов и оверхеду в клиенте.
Игнорирование кэширования в GraphQL — потеря преимуществ CDN/edge caching; нужен persisted queries или отдельные REST-эндпоинты для тяжелых ресурсов.


Чек-лист для принятия решения (практический)

Клиенты — браузеры? мобильные? сторонние интеграторы?
браузер/мобильный фронт → GraphQL выгоден;
сторонние сторонние потребители → REST предпочтителен (совместимость).

Нужен ли стриминг / двунаправленная связь?
да → gRPC;
нет → GraphQL/REST.

Высокая нагрузка внутри сети (RTT, пропускная способность)?
да → gRPC;

Требуется гибкость выбора полей клиентом и уменьшение запросов?
да → GraphQL;

Требуется простое кеширование через CDN/HTTP?
да → REST (или реализовать persisted queries для GraphQL).

Нужно строгая схема и codegen для многих языков?
gRPC или GraphQL (оба дают schema/codegen).


Рекомендованные архитектурные сочетания (рецепты)

Внутренние микросервисы (gRPC) + GraphQL BFF + браузерный фронт — оптимальный вариант для больших команд: скорость внутри, гибкость для фронтенда.
REST public API + GraphQL internal BFF for web clients — если нужно максимально простое публичное API, но гибкость для своих фронтенд-команд.
gRPC end-to-end — когда все клиенты контролируются и могут использовать gRPC (например, мобильный клиент с gRPC-Web или нативный клиент).


Пример архитектуры

Сценарий: крупное приложение с веб-клиентом и мобильными приложениями + множество микросервисов.
Внутренние микросервисы: общаются по gRPC (protobuf).
Aggregation Layer: GraphQL BFF. Он:
вызывает gRPC сервисы (stub-ы),
использует DataLoader / batching для борьбы с N+1,
кеширует часто запрашиваемые фрагменты,
реализует field-level авторизацию.
Фронтенд: запрашивает GraphQL; для критичных статических ресурсов (изображения) используется CDN.
Преимущество: фронтенд получает гибкий API, внутренние сервисы остаются быстрыми и типобезопасными.


#Java #middle #GraphQL

Advanced GraphQL: реактивность и Federation

GraphQL уже давно не ограничивается статическими запросами к одной базе.

Современные системы требуют:
реактивности: live updates, push-события на фронтенд;
масштабируемости: объединение схем из разных сервисов;
микросервисной интеграции: разные источники данных и форматы;
единый клиентский интерфейс: фронт видит единую схему, хотя данные приходят из нескольких микросервисов.

Эти задачи решаются через Subscriptions, Federation, Schema Stitching, GraphQL Gateway.


1. Subscriptions и live updates

1.1 Что такое Subscription

Subscription — это тип операции GraphQL, который подписывается на события и получает данные по мере их появления, в отличие от Query/Mutation, где данные запрашиваются один раз.

Используется для:
чатов и уведомлений;
реального мониторинга (метрики, логи);
обновления UI при изменении данных на сервере.

1.2 Механика на сервере

Клиент подписывается на событие через WebSocket или Server-Sent Events (SSE).
Сервер регистрирует подписку и хранит её в памяти или через pub/sub (Redis, Kafka).
При событии вызываются соответствующие резолверы Subscription, результат отправляется клиенту.

1.3 Пример на Spring Boot с graphql-java

Схема (schema.graphqls)

type Subscription {
  postAdded: Post!
}

Резолвер Subscription

@Component
public class PostSubscription implements GraphQLSubscriptionResolver {

    private final Publisher<Post> postPublisher;

    public PostSubscription(Publisher<Post> postPublisher) {
        this.postPublisher = postPublisher;
    }

    public Publisher<Post> postAdded() {
        return postPublisher;
    }
}

Публикация события (например, после мутации)

@Component
public class PostMutation implements GraphQLMutationResolver {

    private final Publisher<Post> postPublisher;
    private final PostService postService;

    public PostMutation(PostService postService, Publisher<Post> postPublisher) {
        this.postService = postService;
        this.postPublisher = postPublisher;
    }

    public Post createPost(CreatePostInput input) {
        Post newPost = postService.create(input);
        postPublisher.publish(newPost); // пушим в подписчиков
        return newPost;
    }
}

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

1.4 Реактивная интеграция с gRPC

Микросервис может уведомлять GraphQL через gRPC стриминг (Server Streaming).
GraphQL Gateway принимает события и пушит их клиентам через Subscription.
Реализуется через Publisher или Flux (Project Reactor) в Java.

Пример с Project Reactor:

public Publisher<Post> postAdded() {
    return Flux.from(postGrpcStub.subscribePosts());
}

#Java #middle #GraphQL

2. Federation / Schema stitching

2.1 Зачем нужна Federation

В микросервисной архитектуре каждая команда может иметь свой GraphQL-сервис.
Фронтенду нужен единый endpoint, а не десятки отдельных.

Schema stitching: объединяет схемы в один endpoint вручную.

Apollo Federation: более продвинутый стандарт, позволяющий каждому сервису быть федеративным узлом.

2.2 Принцип работы Federation

Subgraph Service — каждый сервис предоставляет свою часть схемы: User, Post, Comment.
Gateway / Apollo Gateway — объединяет схемы subgraph и решает, какой сервис вызывать для каждого запроса.
Reference resolver — позволяет связать типы из разных сервисов (например, User в Post).

Пример на Java (с Spring Boot + GraphQL Federation, библиотека graphql-java-federation):

Сервис Users

type User @key(fields: "id") {
  id: ID!
  name: String!
}

Сервис Posts

type Post {
  id: ID!
  title: String!
  author: User @provides(fields: "name")
}

Java resolver для Post.author

@Component
public class PostResolver implements GraphQLResolver<Post> {

    private final UserGrpc.UserBlockingStub userStub;

    public PostResolver(UserGrpc.UserBlockingStub userStub) {
        this.userStub = userStub;
    }

    public User author(Post post) {
        UserRequest req = UserRequest.newBuilder().setId(post.getAuthorId()).build();
        UserResponse resp = userStub.getUser(req);
        return mapToGraphQLUser(resp);
    }
}

Gateway собирает всю федеративную схему и возвращает фронтенду единый API.

3. GraphQL Gateway и объединение данных

3.1 Роль Gateway

Аггрегирует данные из нескольких микросервисов (REST, gRPC, базы, Kafka).
Решает проблемы N+1 через batching (DataLoader).
Управляет кешированием и throttling.
Поддерживает Subscriptions и Federation.

3.2 Пример архитектуры

[Frontend SPA / Mobile] --GraphQL--> [GraphQL Gateway] --gRPC--> [UserService]
                                                   |--> [PostService]
                                                   |--> [CommentService]
                                                   |--> [External REST API]

Особенности:
Gateway использует DataLoader для агрегации запросов, уменьшения количества вызовов к сервисам.
Subscriptions могут получать события из gRPC стримов или Kafka и пушить клиенту.


4. Примеры использования и кейсы

4.1 Live feed

Мобильное приложение подписывается на postAdded.
PostService пушит новые посты через gRPC или внутренний EventBus.
Gateway трансформирует данные в GraphQL Subscription → клиент получает обновления моментально.

4.2 Микросервисная интеграция

UserService и PostService разрабатываются разными командами.
Gateway объединяет их схемы через Federation.
Фронтенд видит единый API: user(id: 1) { name posts { title } }, не зная, что posts приходит из другого сервиса.

4.3 Agreggation + caching

Gateway кеширует данные User на 5 минут.
PostService вызывается только для новых постов.
DataLoader агрегирует все запросы к UserService за одну операцию.


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

Использовать Federation для масштабируемых командных проектов.
Subscription через WebSocket + Publisher/Flux для реактивных интерфейсов.
DataLoader для оптимизации N+1 вызовов в распределённых сервисах.
Разделять ответственность: микросервисы предоставляют свои типы и резолверы, Gateway агрегирует.
Event-driven подход для live updates: gRPC streaming, Kafka, Redis Pub/Sub.
Мониторинг: трассировка на уровне каждого subgraph, latency, throughput.
Эволюция схем: добавление новых полей без ломки клиентов, депрекация старых.


#Java #middle #GraphQL

Spring Cloud Gateway: Архитектурный страж микросервисов

В монолитной архитектуре приложение имеет одну точку входа — HTTP-порт, через который проходят все запросы. Клиент взаимодействует с единым целым. При переходе к микросервисам эта модель разрушается: вместо одного приложения появляются десятки или сотни независимых сервисов, каждый со своим API и сетевым адресом. Прямое обращение клиентов ко всем сервисам создаёт фундаментальные проблемы: клиент должен знать топологию сети, обеспечивать отказоустойчивость для каждого вызова, дублировать логику аутентификации и преобразования данных. Именно здесь возникает необходимость в паттерне API Gateway — единой интеллектуальной точке входа, которая инкапсулирует внутреннюю структуру системы и предоставляет клиентам унифицированный интерфейс. Spring Cloud Gateway (SCG) — это реализация этого паттерна в экосистеме Spring, построенная на реактивной парадигме для удовлетворения требований современных высоконагруженных распределённых систем.


Архитектурное позиционирование и место в экосистеме

Spring Cloud Gateway функционирует как шлюз прикладного уровня (Layer 7) в модели OSI.
Его позиция строго определена: между внешними клиентами (мобильные приложения, браузеры, сторонние системы) и внутренним кластером микросросервисов. Он не является заменой балансировщику нагрузки сетевого уровня (например, AWS NLB или hardware-балансировщику), но работает в тесной связке с ним. Типичная многоуровневая архитектура включает внешний балансировщик, который распределяет трафик между несколькими инстансами SCG для обеспечения отказоустойчивости и масштабируемости, а сам SCG уже занимается интеллектуальной маршрутизацией к конкретным сервисам.

В экосистеме Spring Cloud Gateway является эволюционным преемником Zuul 1.x. Zuul 1, построенный на блокирующем сервлетном API, имел архитектурные ограничения, связанные с выделением потока на каждый соединение, что создавало проблемы при большом количестве одновременных соединений, особенно с длительными запросами (например, Server-Sent Events, WebSockets). SCG был создан с нуля на реактивном стеке Spring WebFlux и проекте Reactor, что позволило реализовать полностью неблокирующую, асинхронную архитектуру, способную эффективно работать с тысячами одновременных соединений на скромных аппаратных ресурсах. Это стратегическое выравнивание с реактивной парадигмой, которую Spring продвигает для построения масштабируемых систем.


#Java #middle #Spring_Cloud_Gateway

Детальный разбор решаемых проблем

1. Интеллектуальная маршрутизация и абстракция сервисов
Базовая и критически важная функция — динамическая маршрутизация запроса к соответствующему backend-сервису на основе содержимого запроса. SCG анализирует HTTP-запросы (путь, заголовки, параметры) и, используя механизм предикатов, определяет, какой маршрут должен быть применён. Каждый маршрут связан с определённым URI назначения (например, lb://SERVICE-NAME при использовании Service Discovery через Spring Cloud LoadBalancer). Это позволяет полностью скрыть от клиента реальные сетевые адреса и даже имена хостов сервисов. Клиент обращается к api.company.com/orders, а шлюз решает, что этот запрос должен уйти в сервис order-service-v2, работающий в трёх экземплярах. Механизм балансировки нагрузки на стороне клиента (client-side load balancing) интегрирован непосредственно в процесс проксирования.

2. Централизованная безопасность и контроль доступа
Вместо того чтобы встраивать идентификацию и авторизацию в каждый микросервис, что приводит к дублированию кода и сложности управления политиками, SCG позволяет централизовать эту логику. Типичный сценарий: фильтр шлюза (Gateway Filter) перехватывает входящий запрос, извлекает JWT-токен из заголовка Authorization, валидирует его подпись и срок действия, декодирует claims (утверждения) и либо добавляет обогащённую информацию (например, роли пользователя) в заголовки для передачи в нижестоящий сервис, либо сразу отвергает запрос с кодом 401 или 403. Это реализует паттерн "валидация токена на периметре". Таким образом, внутренние сервисы могут доверять данным из заголовков (которые, впрочем, должны проверяться на целостность в средах с высокими требованиями безопасности), что избавляет их от необходимости иметь доступ к секретам для проверки подписи JWT.

3. Применение кросс-сервисных политик
Многие требования, такие как ограничение частоты запросов (rate limiting), применяются на уровне всего API или конкретного пользователя, а не отдельного сервиса. SCG может интегрироваться с системами вроде Redis для реализации алгоритмов ограничения (например, "token bucket" или "sliding window"). Фильтр шлюза считает количество запросов с определённого ключа (IP, user ID, API key) за временное окно и блокирует превысившие лимит запросы до того, как они создадут нагрузку на бизнес-сервисы. Аналогично реализуется политика Circuit Breaker (размыкатель цепи): SCG отслеживает ошибки или задержки при вызовах к конкретному сервису и при достижении порога временно "разрывает цепь", перенаправляя запросы на заранее определённый fallback-ответ (например, кэшированные данные или заглушку), не нагружая падающий сервис. Это повышает отказоустойчивость всей системы.

4. Наблюдаемость и анализ трафика (Observability)
Как критически важный узел, через который проходит весь трафик, SCG является идеальным местом для сбора телеметрии. Он может автоматически генерировать метрики (например, количество запросов в секунду, задержки, процент ошибок) для каждого маршрута и экспортировать их в системы мониторинга типа Prometheus через Micrometer. Кроме того, он присваивает и распространяет уникальные идентификаторы запросов (trace ID), которые позволяют агрегаторам трассировки, таким как Zipkin или Sleuth, восстановить полный путь запроса по всем микросервисам. Это обеспечивает сквозную видимость, без которой отладка распределённой системы крайне затруднена.

5. Трансформация запросов и ответов
SCG выполняет роль адаптера между внешним и внутренним API. Это может быть простая перезапись путей (rewrite path): клиент отправляет запрос на /api/v1/user, а шлюз перенаправляет его на внутренний сервис по пути /user. Более сложные сценарии включают модификацию заголовков (добавление, удаление), трансформацию тела запроса/ответа (например, из XML в JSON) с помощью встроенных или кастомных фильтров. Это позволяет внутренним сервисам эволюционировать независимо от клиентов, а шлюзу — обеспечивать обратную совместимость.


#Java #middle #Spring_Cloud_Gateway

Конкурентный ландшафт и выбор технологии

Рынок gateway-решений насыщен. SCG не единственный и не универсальный вариант.

Kong
Сильный, промышленный, плагинно-ориентированный API-gateway на базе NGINX и LuaJIT. Скорее всего превосходит SCG по пропускной способности на уровне низкоуровневой сети. Но менее гибок для JVM-экосистемы и глубокой интеграции с Spring.

NGINX
Высокопроизводительный L7-proxy, но без богатой программируемости. SCG выигрывает там, где нужны сложные фильтры и логика на Java/Kotlin.

Envoy
Современный proxy, облачная стандартизация, основа для Istio. Максимально производительный, нативный, ориентирован на service mesh. SCG выигрывает на уровне интеграции с приложением и кастомизируемости внутри JVM.

Traefik
Простой, легкий, динамический, ориентирован на Docker/Kubernetes. SCG более мощен при построении сложных политик, при наличии Spring-экосистемы.

Spring Cloud Gateway vs. Spring MVC (и Zuul 1)
Здесь различие фундаментально и лежит в плоскости архитектурной парадигмы.
Spring MVC и Zuul 1 построены на сервлетной модели, которая привязывает каждый HTTP-запрос к потоку (thread) на всё время его обработки. Потоки — дорогой ресурс, их количество в пуле ограничено (часто 200-500). Когда все потоки заняты ожиданием ответа от медленного backend-сервиса, шлюз перестаёт принимать новые запросы, даже если CPU простаивает. SCG, построенный на WebFlux и Reactor Netty, использует событийно-ориентированную, неблокирующую модель. Небольшое количество потоков (часто равное количеству ядер CPU) обрабатывает множество соединений. Когда запрос проксируется к backend-сервису, поток не блокируется в ожидании ответа, а освобождается для обработки других событий (новых запросов или пришедших ответов). Колбэк вызывается, когда ответ готов. Это позволяет одному экземпляру SCG эффективно обслуживать десятки тысяч одновременных long-lived соединений (например, для streaming API) с предскатуемым потреблением памяти. С точки зрения JVM, это означает отказ от пула потоков Tomcat/Jetty и работу на основе NIO-селекторов в Netty, где события диспетчеризуются ядром Reactor.


Архитектура: Reactor Netty и WebFlux

Работа Spring Cloud Gateway начинается с автоконфигурации Spring Boot. Ядром является ReactorNettyHttpPredicateHandlerMapping. Весь входящий трафик принимается сервером Netty, который работает на реактивном канале HttpServer.

Когда Netty принимает новый HTTP-запрос, он преобразует его в реактивный тип ServerHttpRequest и запускает цепочку обработки.

Основной цикл выглядит так:

Сопоставление маршрута (Route Predicate Handler Mapping): Для входящего ServerHttpRequest проверяются все определённые в контексте маршруты (Route). Каждый маршрут содержит коллекцию Predicate. Предикаты — это условия на основе запроса (например, Path=/api/**, Header=X-Request-Id, Method=GET). Проверка выполняется последовательно до первого совпадения. Этот процесс не блокирующий, все предикаты оцениваются в том же реактивном потоке.

Сборка цепочки фильтров (Filtering Web Handler): Найденный маршрут содержит упорядоченный список фильтров (GatewayFilter) и URI назначения. Формируется цепочка обработки DefaultGatewayFilterChain. Фильтры делятся на два типа: "pre-filters" (выполняются до вызова проксируемого сервиса) и "post-filters" (выполняются после получения ответа). Сам вызов проксируемого сервиса также реализован как специальный фильтр — NettyRoutingFilter.

Выполнение цепочки фильтров (Reactive Pipeline): Цепочка выполняется как реактивный пайплайн. Например, пре-фильтр аутентификации проверяет токен, используя реактивный ReactiveJwtDecoder, который не блокирует поток. Если вызов к сервису ключей необходим, он выполняется асинхронно. Затем фильтр преобразования путей модифицирует ServerHttpRequest. Ключевой фильтр LoadBalancerClientFilter взаимодействует с реактивным ReactorLoadBalancer для преобразования логического имени сервиса (из lb://SERVICE) в реальный физический адрес, выбранный с учётом балансировки.


#Java #middle #Spring_Cloud_Gateway

Проксирование запроса (NettyRoutingFilter): Это кульминация. Фильтр берет обогащённый ServerHttpRequest, конвертирует его в запрос Netty (HttpClientRequest) и отправляет через неблокирующий HTTP-клиент Netty (HttpClient) к целевому сервису. Клиент Netty использует ту же событийно-ориентированную модель. Запрос ставится в очередь на отправку, и текущий поток немедленно освобождается. Когда от backend-сервиса приходит ответ (HttpClientResponse), Netty генерирует событие, которое подхватывается реактивным пайплайном, преобразуя ответ в ServerHttpResponse.

Обработка ответа (Post-Filters): Запускается "post-filter" часть цепочки. Здесь могут работать фильтры добавления стандартных заголовков, логирования, преобразования тела ответа. Итоговый ServerHttpResponse записывается в исходный канал Netty к клиенту.

В памяти JVM это проявляется как доминирование объектов реактивных стримов (Mono, Flux), цепочек операторов и лямбда-выражений в heap. Стек вызовов глубокий, но асинхронный: в дампе потока вы не увидите блокирующего вызова HttpClient. Вместо этого увидите фреймы типа onNext, onComplete из реализации Reactor. Пул потоков Netty (обычно reactor-http-nio-) активен, но количество потоков мало. Основное потребление памяти связано с буферами Netty для HTTP-сообщений (которые используют пул ByteBuf для эффективного управления), и объектами, представляющими запросы/ответы.


Типичные сценарии реализации

Rate Limiting с использованием Redis: Фильтр, реализующий алгоритм "скользящего окна". Для каждого запроса вычисляется ключ (например, user:123:path:/api/orders). С помощью реактивного клиента Redis (ReactiveRedisTemplate) выполняются команды ZREMRANGEBYSCORE (удаление старых записей) и ZADD + ZCOUNT (добавление текущего запроса и подсчёт количества запросов в окне). Вся эта последовательность выполняется как атомарный Lua-скрипт на стороне Redis для обеспечения консистентности. Если лимит превышен, цепочка прерывается с возвратом 429 Too Many Requests.

Аутентификация и передача контекста: Кастомный GatewayFilter в порядке pre извлекает JWT из заголовка. Используя ReactiveJwtDecoder (который может кэшировать JWK для проверки подписи), токен декодируется. Из claims извлекается идентификатор пользователя и его роли, которые затем добавляются в заголовки запроса, например, X-User-Id и X-User-Roles. Важный нюанс: для предотвращения подмены заголовков внутренними сервисами, эти заголовки должны либо очищаться шлюзом от входящих значений, либо внутренние сервисы должны доверять только конкретным заголовкам, установленным шлюзом (что может быть обеспечено настройками сетевой безопасности).

API Composition (Агрегация): Хотя SCG не является специализированным агрегатором (как GraphQL BFF), он может выполнять простую агрегацию с помощью фильтра ModifyResponseBodyGatewayFilterFactory. Например, клиенту нужны данные пользователя вместе с его последним заказом. Шлюз может последовательно вызвать user-service и, используя данные из ответа, вызвать order-service, а затем объединить результаты в единый JSON. Эта операция выполняется неблокирующе с помощью операторов Reactor flatMap или zip. Однако для сложных агрегаций с множественными зависимостями предпочтительнее выделенный BFF-сервис.

Circuit Breaker с Resilience4J: SCG интегрируется с Resilience4J через конфигурацию. Для маршрута определяется конфигурация Circuit Breaker с параметрами порога ошибок, временем ожидания в полуоткрытом состоянии и т.д. Когда фильтр активирован, все вызовы через него оборачиваются в защитный контур. В случае открытия контура запросы не идут к падающему сервису, а перенаправляются на заданный fallbackUri, который может указывать на статический ответ или простой сервис-заглушку, возвращающий данные из кэша.


#Java #middle #Spring_Cloud_Gateway