Alamofire — co to jest, klient HTTP w Swift i jak działa

Czym jest Alamofire?

Alamofire — to klient HTTP dla Swift, stworzony przez Alamofire Software Foundation (pierwotnie Mattt Thompson w 2014 roku). Biblioteka abstrahuje niskopoziomowe szczegóły URLSession, zapewniając czyste i wyraziste API do komunikacji sieciowej.

Podstawowa filozofia Alamofire to składnia łańcuchowa, w której parametry żądania (URL, metoda, nagłówki, parametry, koder) są przekazywane przez kolejne wywołania. Sprawia to, że kod jest bardziej czytelny i zmniejsza prawdopodobieństwo błędów związanych z nieprawidłową konfiguracją URLRequest. Podejście deklaratywne pozwala skupić się na tym, co należy zrobić, a nie na szczegółach konfiguracji połączenia. Deweloper opisuje pożądany rezultat, a biblioteka przejmuje niskopoziomową pracę z siecią.

Biblioteka jest aktywnie rozwijana od 2014 roku i przeszła przez siedem głównych wersji. Alamofire 5, aktualna na lata 2025–2026, obejmuje wsparcie dla Combine, async/await, konwerterów odpowiedzi, EventMonitor do debugowania i RequestInterceptor do przechwytywania żądań. Każda główna wersja przynosiła znaczące ulepszenia: Alamofire 4 dodała obsługę Codable, Alamofire 5 — Combine Publishers i ulepszony system przechwytywania żądań.

Ekosystem Alamofire obejmuje dodatkowe biblioteki: AlamofireImage do ładowania i buforowania obrazów, AlamofireNetworkActivityIndicator do wskaźnika aktywności sieciowej na pasku stanu iOS oraz AlamofireObjectMapper do integracji z ObjectMapper. Te komponenty czynią Alamofire pełnym stosem sieciowym, a nie tylko klientem HTTP.

Instalacja i konfiguracja

Alamofire instaluje się przez Swift Package Manager (zalecane), CocoaPods lub Carthage. W Xcode wystarczy otworzyć menu File → Add Packages, wkleić URL repozytorium i określić wersję.

// Swift Package Manager — dodaj w Package.swift
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git",
             from: "5.9.0")
]

// Import w pliku
import Alamofire

Po instalacji Alamofire jest dostępne globalnie poprzez przestrzeń nazw AF (skrót od Alamofire) bez dodatkowej konfiguracji. Większość projektów zaczyna od konfiguracji Session z własną konfiguracją — pozwala to ustawić bazowy URL, standardowe nagłówki, limity czasu i obsługę certyfikatów TLS.

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

Tworzenie własnej sesji przez Session(configuration:) jest konieczne, gdy wymagana jest unikalna konfiguracja dla różnych części aplikacji — na przykład osobna sesja do ładowania obrazów z agresywnym buforowaniem i osobna dla żądań API z uwierzytelnianiem. Sesja Alamofire przyjmuje nie tylko konfigurację, ale także interceptor, serverTrustManager, cachedResponseHandler i redirectHandler, co pozwala w pełni kontrolować zachowanie sieci na wszystkich etapach żądania.

Główne funkcje

Alamofire zapewnia szeroki zestaw funkcji pokrywających większość scenariuszy komunikacji sieciowej w aplikacjach iOS. Przyjrzyjmy się kluczowym z nich.

Żądania HTTP

Podstawowa składnia żądania obejmuje metodę, URL, parametry i encoding. Wszystkie standardowe metody HTTP są obsługiwane przez enum HTTPMethod: get, post, put, patch, delete. Parametry mogą być zakodowane jako parametry URL (URLEncoding), ciało JSON (JSONEncoding) lub format multipart (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("Utworzono użytkownika: \(user)")
        case .failure(let error):
            print("Błąd: \(error)")
        }
    }

Metoda validate() automatycznie sprawdza kod statusu (200–299) i typ treści, zwracając błąd przy niestandardowej odpowiedzi, co eliminuje ręczne sprawdzanie statusCode. responseDecodable używa protokołu Decodable do automatycznej deserializacji JSON do struktury Swift — eliminuje to ręczne JSONSerialization i zmniejsza ilość kodu boilerplate podczas pracy z REST API.

Obsługa odpowiedzi

Alamofire obsługuje kilka typów handlerów odpowiedzi: response (surowe dane), responseJSON (słownik/tablica), responseString (tekst), responseData (Data) i responseDecodable (model Decodable). Konwertery odpowiedzi można tworzyć własne — dla protobuf, formatów graficznych lub własnych protokołów.

Przesyłanie i pobieranie plików

Do przesyłania danych na serwer używane jest upload, obsługujące Data, File i MultipartFormData. Pobieranie dużych plików odbywa się przez download z możliwością wznowienia przez resumeData po przerwaniu lub zerwaniu połączenia. Obie operacje obsługują śledzenie postępu przez uploadProgress i downloadProgress z wartościami ułamkowymi od 0 do 1 do wyświetlania w interfejsie użytkownika.

Multipart-przesyłanie z Alamofire jest szczególnie wygodne: metoda upload(multipartFormData:) przyjmuje domknięcie, w którym dodawane są części formularza przez append. Każda część może zawierać dane, plik lub strumień, a także własną nazwę i typ mime. Alamofire automatycznie oblicza granice multipart i ustawia prawidłowy nagłówek Content-Type, co eliminuje ręczne formowanie ciała żądania. Dla dużych plików zaleca się używanie transmisji strumieniowej (stream provider) zamiast ładowania całego pliku do pamięci — zapobiega to przekroczeniu limitu pamięci na urządzeniach mobilnych z ograniczonymi zasobami. Typowy scenariusz — wysyłanie awatara użytkownika wraz z danymi profilu w jednym żądaniu multipart, co zmniejsza liczbę wywołań HTTP i upraszcza przetwarzanie po stronie serwera.

Alamofire vs URLSession

Porównanie Alamofire i natywnego URLSession pomaga podjąć decyzję architektoniczną. Alamofire nie zastępuje URLSession — jest nadbudową na nim i wykorzystuje te same mechanizmy konfiguracji, buforowania i zadań w tle. Wszystkie funkcje URLSession są dostępne przez Alamofire, ale z wygodniejszą deklaratywną składnią.

W dużych projektach Alamofire zmniejsza ilość kodu dla żądań sieciowych o 30–50% i upraszcza obsługę błędów. W małych projektach lub przy ścisłych wymaganiach dotyczących rozmiaru binarnego natywny URLSession jest preferowany ze względu na brak zewnętrznych zależności.

Nowoczesny Alamofire 5 integruje się z Combine poprzez właściwość publishDecodable, która zwraca Publisher, umożliwiając budowanie reaktywnych łańcuchów żądań z obsługą błędów i transformacją danych. Dla async/await dostępne są metody z sufiksem value — na przykład AF.request(url).serializingDecodable(User.self).value, co czyni składnię maksymalnie zwięzłą i przypomina pracę z natywnym URLSession. Podczas używania async/await odpada potrzeba domknięć, a obsługa błędów odbywa się przez standardowe bloki do-catch Swift, co upraszcza utrzymanie kodu i jego czytelność w długoterminowej perspektywie.

Przykłady kodu

Rozważmy bardziej złożony przykład — żądanie z przechwytywaczem, który automatycznie dodaje token autoryzacji i wykonuje ponowną próbę przy błędzie 401. Jest to typowy scenariusz dla aplikacji z uwierzytelnianiem 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)
        }
    }
}

Interceptor AuthInterceptor implementuje dwa protokoły: adapt (dodaje token do każdego żądania) i retry (próbuje odświeżyć token przy błędzie 401). Metoda retry sprawdza kod statusu odpowiedzi i, jeśli otrzymano 401, żąda nowego tokena przez TokenManager. Po pomyślnym odświeżeniu żądanie jest powtarzane automatycznie.

Użycie interceptor-a z sesją:

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

Wszystkie żądania przez tę sesję automatycznie przechodzą przez AuthInterceptor — token jest dodawany do nagłówków, a przy 401 następuje odświeżenie i ponowienie. Eliminuje to powielanie kodu uwierzytelniania w każdym żądaniu i centralizuje logikę pracy z tokenami.