Розробка GraphQL API для мобільного додатку

Розробка GraphQL API для мобільного застосунку

GraphQL змінює модель взаємодії клієнта з сервером: замість фіксованих ендпоїнтів клієнт декларує, які саме поля йому потрібні, і отримує ровай їх. Для мобільного застосунку це особливо цінно — екран з картою товару запитує лише name, price, thumbnail, не тягучи description, reviews, inventory як при REST. На повільних з'єднаннях різниця помітна.

Коли GraphQL оправдан для мобільного

GraphQL додає складність: потрібна серверна реалізація (resolver'и, schema, DataLoader), клієнтська бібліотека та навчання команди. Оправдані сценарії:

• Різні клієнти (iOS, Android, Web) потребують обслуговування з одного API, їх вимоги до даних сильно розходяться
• Активно мінливий UI — можна додати поля у запит без змін сервера
• Вложені дані зі змінною глибиною (соціальний граф, каталог з категоріями)

Для CRUD з передбачуваною структурою даних REST простіше. GraphQL не чарівна куля.

Apollo Client на Android

Apollo Kotlin — де-факто стандарт. Генерує типобезопасні класи запитів з .graphql файлів під час збірки.

# app/src/main/graphql/GetProduct.graphql
query GetProduct($id: ID!) {
  product(id: $id) {
    id
    name
    price
    thumbnail {
      url
      width
      height
    }
  }
}

// автогенерований тип GetProductQuery.Data
val response = apolloClient.query(GetProductQuery(id = productId)).execute()
val product = response.data?.product

apolloClient налаштовується один раз з HttpEngine, заголовками авторизації та кешем:

val apolloClient = ApolloClient.Builder()
    .serverUrl("https://api.example.com/graphql")
    .addHttpHeader("Authorization", "Bearer $token")
    .normalizedCache(MemoryCacheFactory(maxSizeBytes = 10 * 1024 * 1024))
    .build()

normalizedCache — нормалізований кеш по полю id. Запит продукту з ленти та з детальної сторінки повертає один об'єкт в пам'яті — оновлення в одному місці автоматично відбивається везде.

Apollo Client на iOS

Apollo iOS генерує Swift-код аналогічно Kotlin.

let client = ApolloClient(
    networkTransport: RequestChainNetworkTransport(
        interceptorProvider: DefaultInterceptorProvider(store: store),
        endpointURL: URL(string: "https://api.example.com/graphql")!
    ),
    store: store
)

client.fetch(query: GetProductQuery(id: productId)) { result in
    switch result {
    case .success(let response):
        let product = response.data?.product
    case .failure(let error):
        print(error)
    }
}

Subscriptions для real-time

GraphQL subscriptions — WebSocket-канал для оновлень у реальному часі. Ідеально для чатів, live-оновлень ціни, статусів замовлень:

subscription OnOrderStatusChanged($orderId: ID!) {
  orderStatusChanged(orderId: $orderId) {
    status
    updatedAt
  }
}

Apollo Kotlin підтримує subscriptions через WebSocketNetworkTransport:

apolloClient.subscription(OnOrderStatusChangedSubscription(orderId = id))
    .toFlow()
    .collect { response ->
        val status = response.data?.orderStatusChanged?.status
    }

Оптимізація: Persisted Queries

Кожен GraphQL запит відправляє повний текст query у тілі запиту — накладні витрати. Automatic Persisted Queries (APQ): клієнт відправляє SHA256 хеш запиту, сервер повертає дані якщо знає цей хеш, інакше просить прислати повний текст. Apollo Client підтримує APQ з коробки.

N+1 та DataLoader на сервері

Класична проблема GraphQL resolver'ів: запит 100 продуктів триггерить 100 окремих SQL-запитів для завантаження категорії кожного. Рішення — DataLoader (batch + cache): всі запити категорій за одну ітерацію батчатися в один SELECT ... WHERE id IN (...).

Без DataLoader GraphQL схема, яка добре працює на 10 об'єктах, деградує на 1000 об'єктах. Це не клієнтська проблема, але її потрібно проектувати на етапі розробки API.

Обробка помилок

GraphQL повертає HTTP 200 навіть при помилках — помилки у тілі відповіді:

{
  "data": { "product": null },
  "errors": [{ "message": "Product not found", "extensions": { "code": "NOT_FOUND" } }]
}

Клієнт зобов'язаний перевіряти errors масив незалежно від HTTP статусу. Apollo Client надає список GraphQLError у response.errors.

Що входить у роботу

Проектуємо GraphQL схему під вимоги мобільного клієнта, реалізуємо resolver'и з DataLoader, налаштовуємо Apollo Client під платформи з кешем та subscriptions, інтегруємо аутентифікацію через HTTP заголовки та WebSocket connection params.

Строк: 2–4 тижні залежно від обсягу схеми та необхідності бекенду.