Alamofire — що це, HTTP-клієнт на Swift і як працює

Що таке Alamofire?

Alamofire — це HTTP-клієнт для Swift, створений компанією Alamofire Software Foundation (спочатку Mattt Thompson у 2014 році). Бібліотека абстрагує низькорівневі деталі URLSession, надаючи чистий і виразний API для мережевої взаємодії.

Основна філософія Alamofire — ланцюжковий синтаксис, при якому параметри запиту (URL, метод, заголовки, параметри, кодувальник) передаються через послідовні виклики. Це робить код більш читабельним і зменшує ймовірність помилок, пов'язаних з неправильною конфігурацією URLRequest. Декларативний підхід дозволяє зосередитися на тому, що потрібно зробити, а не на деталях того, як налаштувати з'єднання. Розробник описує бажаний результат, а бібліотека бере на себе низькорівневу роботу з мережею.

Бібліотека активно підтримується з 2014 року і пройшла через сім мажорних версій. Alamofire 5, актуальна на 2025–2026 роки, включає підтримку Combine, async/await, конвертерів відповідей, EventMonitor для налагодження та RequestInterceptor для перехоплення запитів. Кожна мажорна версія приносила значні покращення: Alamofire 4 додала Codable-підтримку, Alamofire 5 — Combine Publishers і покращену систему перехоплення запитів.

Екосистема Alamofire включає додаткові бібліотеки: AlamofireImage для завантаження та кешування зображень, AlamofireNetworkActivityIndicator для індикатора мережі в статус-барі iOS та AlamofireObjectMapper для інтеграції з ObjectMapper. Ці компоненти роблять Alamofire повноцінним мережевим стеком, а не просто HTTP-клієнтом.

Встановлення та налаштування

Alamofire встановлюється через Swift Package Manager (рекомендовано), CocoaPods або Carthage. У Xcode достатньо відкрити меню File → Add Packages, вставити URL репозиторію та вказати версію.

// Swift Package Manager — додай у Package.swift
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git",
             from: "5.9.0")
]

// Імпорт у файлі
import Alamofire

Після встановлення Alamofire доступна глобально через простір імен AF(скорочення від Alamofire) без додаткового налаштування. Більшість проєктів починають з налаштування Session зі своєю конфігурацією — це дозволяє задати базовий URL, стандартні заголовки, тайм-аути та обробники сертифікатів TLS.

let configuration = URLSessionConfiguration.default
configuration.timeoutIntervalForRequest = 30
let session = Session(configuration: configuration)

Створення власної сесії через Session(configuration:) необхідне, коли потрібна унікальна конфігурація для різних частин додатка — наприклад, окрема сесія для завантаження зображень з агресивним кешуванням та окрема для API-запитів з автентифікацією. Сесія Alamofire приймає не тільки конфігурацію, але й interceptor, serverTrustManager, cachedResponseHandler та redirectHandler, що дозволяє повністю контролювати поведінку мережі на всіх етапах запиту.

Основні можливості

Alamofire надає широкий набір функцій, що покривають більшість сценаріїв мережевої взаємодії в iOS-додатках. Розглянемо ключові з них.

HTTP-запити

Базовий синтаксис запиту включає метод, URL, параметри та encoding. Всі стандартні HTTP-методи підтримуються через enum HTTPMethod: get, post, put, patch, delete. Параметри можуть бути закодовані як URL-параметри (URLEncoding), JSON-тіло (JSONEncoding) або мультипарт-форма (MultipartFormData).

AF.request("https://api.example.com/users", method: .post,
           parameters: ["name": "Alex", "role": "developer"])
    .validate()
    .responseDecodable(of: User.self) { response in
        switch response.result {
        case .success(let user):
            print("Створено користувачем: \(user)")
        case .failure(let error):
            print("Помилка: \(error)")
        }
    }

Метод validate() автоматично перевіряє статус-код (200–299) і тип контенту, повертаючи помилку при нестандартній відповіді, що позбавляє від ручної перевірки statusCode. responseDecodable використовує протокол Decodable для автоматичної десеріалізації JSON у Swift-структуру — це усуває ручний JSONSerialization і скорочує обсяг boilerplate-коду при роботі з REST API.

Обробка відповідей

Alamofire підтримує кілька типів обробників відповіді: response (сирі дані), responseJSON (словник/масив), responseString (текст), responseData (Data) та responseDecodable (Decodable-модель). Конвертери відповідей можна створювати кастомні — для protobuf, графічних форматів або власних протоколів.

Завантаження та вивантаження файлів

Для завантаження даних на сервер використовується upload, що підтримує Data, File та MultipartFormData. Скачування великих файлів виконується через download з можливістю відновлення через resumeData після обриву з'єднання. Обидві операції підтримують відстеження прогресу через uploadProgress та downloadProgress з дробовими значеннями від 0 до 1 для відображення в інтерфейсі користувача.

Multipart-завантаження з Alamofire особливо зручне: метод upload(multipartFormData:) приймає замикання, в якому додаються частини форми через append. Кожна частина може містити дані, файл або потік, а також власне ім'я та mime-тип. Alamofire автоматично розраховує межі multipart і встановлює правильний заголовок Content-Type, що позбавляє розробника від ручного формування тіла запиту. Для великих файлів рекомендується використовувати потокову передачу (stream provider) замість завантаження всього файлу в пам'ять — це запобігає перевищенню ліміту пам'яті на мобільних пристроях з обмеженими ресурсами. Типовий сценарій — відправка аватарки користувача разом з даними профілю в одному multipart-запиті, що скорочує кількість HTTP-викликів і спрощує обробку на сервері.

Alamofire vs URLSession

Порівняння Alamofire та нативного URLSession допомагає прийняти архітектурне рішення. Alamofire не замінює URLSession — він надбудовується поверх нього і використовує ті ж механізми конфігурації, кешування та фонових завдань. Всі можливості URLSession доступні через Alamofire, але з більш зручним декларативним синтаксисом.

У великих проєктах Alamofire скорочує кількість коду для мережевих запитів на 30–50% і спрощує обробку помилок. У невеликих проєктах або при жорстких вимогах до розміру бінарника нативний URLSession кращий через відсутність зовнішніх залежностей.

Сучасний Alamofire 5 інтегрується з Combine через властивість publishDecodable, яка повертає Publisher, дозволяючи будувати реактивні ланцюжки запитів з обробкою помилок і трансформацією даних. Для async/await доступні методи з суфіксом value — наприклад, AF.request(url).serializingDecodable(User.self).value, що робить синтаксис максимально лаконічним і нагадує роботу з нативним URLSession. При використанні async/await відпадає необхідність у замиканнях, а обробка помилок виконується через стандартні do-catch блоки Swift, що спрощує підтримку коду та його читабельність у довгостроковій перспективі.

Приклади коду

Розглянемо більш складний приклад — запит з перехоплювачем, який автоматично додає токен авторизації та виконує повторну спробу при 401 помилці. Це типовий сценарій для додатків з JWT-автентифікацією.

class AuthInterceptor: RequestInterceptor {
    func adapt(_ urlRequest: URLRequest,
               for session: Session,
               completion: @escaping (Result<URLRequest, Error>) -> Void) {
        var request = urlRequest
        request.setValue("Bearer \(TokenManager.shared.token)",
                         forHTTPHeaderField: "Authorization")
        completion(.success(request))
    }

    func retry(_ request: Request,
              for session: Session,
              dueTo error: Error,
              completion: @escaping (RetryResult) -> Void) {
        guard let response = request.response,
              response.statusCode == 401
        else { return completion(.doNotRetry) }
        TokenManager.shared.refreshToken { success in
            completion(success ? .retry : .doNotRetry)
        }
    }
}

Інтерсептор AuthInterceptor реалізує два протоколи: adapt (додає токен до кожного запиту) та retry (намагається оновити токен при 401 помилці). Метод retry перевіряє статус-код відповіді і, якщо отримано 401, запитує новий токен через TokenManager. Після успішного оновлення запит повторюється автоматично.

Використання інтерсептора з сесією:

let session = Session(interceptor: AuthInterceptor())
session.request("https://api.example.com/profile")
    .responseDecodable(of: Profile.self) { response in
        print(response.result)
    }

Всі запити через цю сесію автоматично проходять через AuthInterceptor — токен додається до заголовків, а при 401 виконується refresh і повтор. Це усуває дублювання коду автентифікації в кожному запиті та централізує логіку роботи з токенами.