GraphQL API с Swift: пошаговый туториал для начинающих

Онлайн-тренажер Python для начинающих

Изучайте Python легко и без перегрузки теорией. Решайте практические задачи с автоматической проверкой, получайте подсказки на русском языке и пишите код прямо в браузере — без необходимости что-либо устанавливать.

Начать курс

Введение в GraphQL и Swift

GraphQL — это современный язык запросов для API, разработанный Facebook. В отличие от REST, где вы получаете фиксированную структуру данных, GraphQL позволяет клиенту (вашему приложению на Swift) запрашивать только те поля, которые действительно нужны. Это особенно актуально для мобильных разработчиков, работающих с iOS и macOS: меньше данных — меньше трафика, быстрее загрузка, лучше UX.

В этом туториале мы разберём, как подключить GraphQL API к вашему Swift-проекту, выполнить базовые запросы и мутации. Мы будем использовать официальный клиент Apollo iOS — наиболее популярную и поддерживаемую библиотеку для работы с GraphQL в экосистеме Apple.

К концу статьи вы сможете:

Настроить Apollo iOS в Xcode-проекте
Написать и выполнить GraphQL-запрос (Query)
Отправить мутацию (Mutation) для изменения данных
Обработать ответы и ошибки

1. Настройка проекта и установка Apollo iOS

1.1. Создание нового проекта

Откройте Xcode и создайте новый проект (iOS App или macOS App). Выберите язык Swift и интерфейс SwiftUI или UIKit — не принципиально, так как работа с сетью не зависит от UI-фреймворка.

1.2. Установка через Swift Package Manager

Apollo iOS легко подключается через SPM. Перейдите в File → Add Packages... и вставьте URL:

https://github.com/apollographql/apollo-ios.git

Выберите последнюю стабильную версию (на момент написания — 1.15.0) и добавьте пакет в ваш таргет.

Также установите Apollo Code Generation CLI — инструмент для генерации Swift-типов из схемы GraphQL. Проще всего установить его через Homebrew:

brew install apollo-ios-cli

Если Homebrew не установлен, можно использовать npm:

npm install -g apollo-ios-cli

1.3. Инициализация конфигурации

В терминале, из корня вашего проекта, выполните:

apollo-ios-cli init --module-name YourAppName --schema-namespace GraphQL

Эта команда создаст файл apollo-codegen-config.json и папку GraphQL, где будут храниться ваши .graphql-файлы.

Теперь добавьте в проект схему сервера. Если сервер предоставляет schema.json или schema.graphqls, скопируйте его в папку GraphQL. Если нет — можно использовать встроенную команду для загрузки:

apollo-ios-cli fetch-schema --endpoint=https://your-graphql-endpoint.com/graphql

2. Пишем первый GraphQL-запрос (Query)

2.1. Создаём .graphql-файл

В папке GraphQL создайте файл Queries.graphql и напишите простой запрос. Предположим, у нас есть API для получения списка пользователей:

query GetUsers {
  users {
    id
    name
    email
  }
}

2.2. Генерация Swift-кода

Запустите генерацию кода из терминала:

apollo-ios-cli generate

После успешной генерации в папке Sources/API (или в указанной вами) появится файл API.swift с типами GetUsersQuery, GetUsersQuery.Data и т.д.

2.3. Выполнение запроса из Swift

Теперь создадим экземпляр клиента Apollo и выполним запрос. В вашем ContentView.swift (или любом другом файле) напишите:

import Apollo
import SwiftUI

class NetworkManager {
    static let shared = NetworkManager()
    private(set) lazy var apollo = ApolloClient(url: URL(string: "https://your-graphql-endpoint.com/graphql")!)
}

struct ContentView: View {
    @State private var users: [GetUsersQuery.Data.User] = []
    
    var body: some View {
        List(users, id: \.id) { user in
            VStack(alignment: .leading) {
                Text(user.name)
                    .font(.headline)
                Text(user.email)
                    .font(.subheadline)
            }
        }
        .onAppear {
            fetchUsers()
        }
    }
    
    func fetchUsers() {
        NetworkManager.shared.apollo.fetch(query: GetUsersQuery()) { result in
            switch result {
            case .success(let graphQLResult):
                if let usersData = graphQLResult.data?.users {
                    self.users = usersData
                }
                if let errors = graphQLResult.errors {
                    print("GraphQL ошибки: \(errors)")
                }
            case .failure(let error):
                print("Сетевая ошибка: \(error.localizedDescription)")
            }
        }
    }
}

Важно: Замените URL на реальный эндпоинт вашего GraphQL-сервера. В примере используется безопасный синтаксис с опциональными полями — это стандартная практика для Apollo.

3. Мутации: изменение данных на сервере

3.1. Описание мутации

Добавим в тот же файл Queries.graphql мутацию для создания нового пользователя:

mutation CreateUser($name: String!, $email: String!) {
  createUser(name: $name, email: $email) {
    id
    name
    email
  }
}

Обратите внимание на синтаксис: мы передаём переменные ($name, $email) и просим вернуть созданного пользователя с полями id, name, email.

3.2. Генерация и выполнение мутации

Снова запустите apollo-ios-cli generate — появится тип CreateUserMutation. Теперь напишем функцию для отправки мутации:

func createUser(name: String, email: String) {
    let mutation = CreateUserMutation(name: name, email: email)
    
    NetworkManager.shared.apollo.perform(mutation: mutation) { result in
        switch result {
        case .success(let graphQLResult):
            if let createdUser = graphQLResult.data?.createUser {
                print("Создан пользователь: \(createdUser.name)")
                // Обновляем UI или массив users
            }
            if let errors = graphQLResult.errors {
                print("Ошибки мутации: \(errors)")
            }
        case .failure(let error):
            print("Ошибка сети: \(error)")
        }
    }
}