rzaripov.kz

Как выполнить запрос к API в Swift с помощью URLSession

Я Равиль Зарипов, программный разработчик из Алматы. В портфолио представлена моя работа с приложениями для Android, iOS, Windows, macOS и Linux. Для мобильных и десктопных решений я использую Delphi, FireMonkey, Kotlin и Swift, а также PHP и базы данных. Такой опыт помогает рассматривать сетевой слой не как изолированный пример, а как часть надёжного приложения.

URLSession — стандартный сетевой клиент в Swift, входящий в Foundation и Cocoa. Он поддерживает HTTP и HTTPS, передачу данных, кэширование, хранение куки и фоновые загрузки. API одинаково работает на iPhone, iPad и Mac, поэтому разработчику не приходится вручную управлять сокетами и сетевыми потоками.

Типичный вызов состоит из трёх этапов: формирования URL, настройки URLRequest и выполнения задачи URLSession. Ответ проверяют по HTTP-коду, затем декодируют в типизированную модель. Ошибки сети, сервера и формата данных обрабатывают отдельно. Такой порядок сохраняет код понятным и упрощает тестирование клиента.

Подготовка URL и структуры запроса

Сначала определяют адрес endpoint, HTTP-метод и параметры запроса. Базовый URL удобно хранить в настройках приложения, а путь к ресурсу добавлять через appendingPathComponent. Этот метод корректно обрабатывает пробелы и специальные символы, сохраняя структуру адреса.

Для 查询-параметров используют URLComponents. Значения передаются отдельными элементами URLQueryItem, поэтому кодирование и объединение параметров выполняются автоматически.

func makeRequest() -> URLRequest? {
    var components = URLComponents()
    components.scheme = "https"
    components.host = "api.example.com"
    components.path = "/users"
    components.queryItems = [
        URLQueryItem(name: "page", value: "2"),
        URLQueryItem(name: "limit", value: "20")
    ]

    guard let url = components.url else { return nil }

    var request = URLRequest(url: url)
    request.httpMethod = "GET"
    request.timeoutInterval = 15

    return request
}

Метод задают свойством httpMethod: обычно это GET, POST, PUT, PATCH или DELETE. Запросы GET и HEAD обычно не содержат тела, а POST, PUT и PATCH могут передавать JSON. Значение timeoutInterval ограничивает ожидание ответа и помогает избежать зависшего интерфейса при проблемах с сетью.

Передача JSON-тела и заголовков

Тело запроса формируют из структуры, соответствующей типу Encodable. JSONEncoder преобразует её в данные, которые можно записать в httpBody. Ручное объединение словарей в строку здесь не требуется.

struct NewUser: Encodable {
    let name: String
    let email: String
}

func makeRequest(endpoint: URL) throws -> URLRequest {
    let payload = NewUser(
        name: "Айдана",
        email: "a@example.com"
    )
    let encoder = JSONEncoder()
    encoder.keyEncodingStrategy = .convertToSnakeCase

    var request = URLRequest(url: endpoint.appendingPathComponent("users"))
    request.httpMethod = "POST"
    request.httpBody = try encoder.encode(payload)
    request.setValue(
        "application/json",
        forHTTPHeaderField: "Content-Type"
    )

    return request
}

Заголовок Content-Type сообщает серверу формат тела, а Accept задаёт желаемый тип ответа. Если сервер ожидает даты в определённом формате, настраивают dateEncodingStrategy. Ошибку кодирования лучше пробрасывать вызывающему коду, чтобы он мог показать понятное уведомление или записать диагностику.

Асинхронный вызов и декодирование ответа

Метод data(for:) выполняет запрос с помощью Swift Concurrency. Он возвращает данные и объект ответа, а функцию можно объявить как async throws. Такой подход избавляет от цепочки вложенных замыканий и позволяет использовать привычные конструкции try, catch и await.

struct User: Decodable {
    let id: Int
    let name: String
    let email: String
}

func loadUser(id: Int, endpoint: URL) async throws -> User {
    let url = endpoint
        .appendingPathComponent("users")
        .appendingPathComponent(String(id))
    var request = URLRequest(url: url)
    request.httpMethod = "GET"

    let (data, response) = try await URLSession.shared.data(for: request)

    guard let httpResponse = response as? HTTPURLResponse else {
        throw URLError(.badServerResponse)
    }
    guard (200...299).contains(httpResponse.statusCode) else {
        throw URLError(.badServerResponse)
    }

    return try JSONDecoder().decode(User.self, from: data)
}

Перед декодированием проверяют, что ответ принадлежит HTTPURLResponse, а код состояния находится в диапазоне от 200 до 299. JSONDecoder сопоставляет поля JSON со свойствами структуры. Если сервер использует другие имена полей, помогает convertFromSnakeCase, а для сложных дат настраивают отдельную стратегию декодирования.

Обработка ошибок, тайм-аутов и отмены

Сетевые ошибки возникают до получения HTTP-ответа: нет соединения, DNS-адрес не найден, истекло время ожидания или пользователь отменил задачу. Их перехватывают как URLError и анализируют поле code. Ошибки HTTP-статуса и несоответствие JSON-схемы относятся к другим категориям.

do {
    let (_, response) = try await URLSession.shared.data(for: request)
    print(response)
} catch let error as URLError {
    switch error.code {
    case .timedOut:
        print("Превышено время ожидания")
    case .notConnectedToInternet:
        print("Нет подключения к сети")
    case .cancelled:
        print("Запрос отменён")
    default:
        print("Сетевая ошибка: \(error.localizedDescription)")
    }
}

Код 401 или 403 обычно указывает на проблему авторизации, 404 — на отсутствие ресурса, 409 — на конфликт состояния. Ответ 429 и некоторые ошибки сервера иногда допускают повторную попытку с задержкой. Повторять такие запросы стоит только для идемпотентных операций и с учётом заголовка Retry-After. Отмена через Task.cancel() освобождает связанные ресурсы и предотвращает обновление экрана после ухода пользователя со страницы.

Авторизация и безопасное хранение токенов

Для защищённых ресурсов используют протокол OAuth 2.0. Короткоживущий токен доступа передают в заголовке Authorization, а не в параметрах URL: так секрет не попадёт в журналы сервера и историю браузера.

request.setValue(
    "Bearer \(accessToken)",
    forHTTPHeaderField: "Authorization"
)
request.setValue(
    "application/json",
    forHTTPHeaderField: "Accept"
)

Токены сохраняют в Keychain с достаточной степенью защиты. Обычное хранилище настроек не подходит для refresh token, а вывод токенов в консоль следует исключить из production-кода. Соединения выполняют по HTTPS без отключения проверки сертификатов. Дополнительные сценарии использования сетевого слоя представлены в материалах по сетевым запросам.

Когда срок действия токена заканчивается, приложение запрашивает новый access token и повторяет исходную операцию. Чтобы несколько параллельных запросов не запустили одновременное обновление, используют actor или иной механизм координации. Повтор выполняют только после успешного обновления и не чаще одного раза для конкретного запроса.

Сравнение способов выполнения запроса

Общая сессия подходит для простых обращений без индивидуальных настроек. Собственную URLSession создают, когда требуется задать кэш, куки, тайм-ауты, разрешение использовать мобильную сеть или включить фоновую передачу. Конфигурацию сессии желательно определить заранее и использовать повторно.

Асинхронный метод удобен в коде с async и await, а замыкание dataTask сохраняет совместимость с существующей архитектурой. JSONDecoder подходит для предсказуемых ответов, тогда как ручной разбор нужен при смешанных форматах или нестандартных полях. Выбор зависит от модели приложения, требований к отмене задач и способа обработки ошибок.

Способ Когда подходит Что учитывать
Общая сессия URLSession Простые запросы без отдельных настроек Минимальный объём кода, общие параметры сессии
URLSession с собственной конфигурацией Кэш, куки, фоновые загрузки и сетевые ограничения Требуется управлять жизненным циклом сессии
data(for:) с async и await Swift Concurrency и последовательный поток кода Удобная обработка ошибок и отмена через Task
dataTask с замыканием Существующий код на основе обратных вызовов Результат обрабатывается в очереди сессии
JSONDecoder Ответ с известной JSON-схемой Требуется тип Decodable и точные имена полей
Ручной разбор данных Нестандартный или смешанный формат Больше кода и собственный контроль ошибок