Alamofire — co to je, HTTP klient ve Swiftu a jak funguje

Co je Alamofire?

Alamofire je HTTP klient pro Swift, vytvořený společností Alamofire Software Foundation (původně Mattt Thompson v roce 2014). Knihovna abstrahuje nízkoúrovňové detaily URLSession a poskytuje čisté a výrazné API pro síťovou komunikaci.

Základní filozofií Alamofire je řetězová syntaxe, kde parametry požadavku (URL, metoda, hlavičky, parametry, kodér) jsou předávány prostřednictvím postupných volání. To činí kód čitelnějším a snižuje pravděpodobnost chyb spojených s nesprávnou konfigurací URLRequest. Deklarativní přístup umožňuje soustředit se na to, co je třeba udělat, nikoli na podrobnosti nastavení připojení. Vývojář popíše požadovaný výsledek a knihovna převezme nízkoúrovňovou práci se sítí.

Knihovna je aktivně udržována od roku 2014 a prošla sedmi hlavními verzemi. Alamofire 5, aktuální pro roky 2025–2026, zahrnuje podporu pro Combine, async/await, konvertory odpovědí, EventMonitor pro ladění a RequestInterceptor pro zachytávání požadavků. Každá hlavní verze přinesla významná vylepšení: Alamofire 4 přidalo podporu Codable, Alamofire 5 — Combine Publishers a vylepšený systém zachytávání požadavků.

Ekosystém Alamofire zahrnuje další knihovny: AlamofireImage pro načítání a ukládání obrázků do mezipaměti, AlamofireNetworkActivityIndicator pro indikátor sítě ve stavovém řádku iOS a AlamofireObjectMapper pro integraci s ObjectMapper. Tyto komponenty dělají z Alamofire kompletní síťový stack, nejen HTTP klienta.

Instalace a konfigurace

Alamofire se instaluje pomocí Swift Package Manager (doporučeno), CocoaPods nebo Carthage. V Xcode stačí otevřít menu File → Add Packages, vložit URL repozitáře a zadat verzi.

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

// Import v souboru
import Alamofire

Po instalaci je Alamofire globálně dostupný prostřednictvím jmenného prostoru AF (zkratka z Alamofire) bez další konfigurace. Většina projektů začíná nastavením Session s vlastní konfigurací — to umožňuje nastavit základní URL, standardní hlavičky, časové limity a obsluhu TLS certifikátů.

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

Vytvoření vlastní relace pomocí Session(configuration:) je nezbytné, když je vyžadována jedinečná konfigurace pro různé části aplikace — například samostatná relace pro načítání obrázků s agresivním ukládáním do mezipaměti a samostatná pro API požadavky s autentizací. Relace Alamofire přijímá nejen konfiguraci, ale také interceptor, serverTrustManager, cachedResponseHandler a redirectHandler, což umožňuje plnou kontrolu nad chováním sítě ve všech fázích požadavku.

Hlavní funkce

Alamofire poskytuje širokou škálu funkcí pokrývajících většinu scénářů síťové komunikace v iOS aplikacích. Podívejme se na ty klíčové.

HTTP požadavky

Základní syntaxe požadavku zahrnuje metodu, URL, parametry a kódování. Všechny standardní HTTP metody jsou podporovány prostřednictvím enum HTTPMethod: get, post, put, patch, delete. Parametry mohou být kódovány jako URL parametry (URLEncoding), JSON tělo (JSONEncoding) nebo multipart formát (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("Uživatel vytvořen: \(user)")
        case .failure(let error):
            print("Chyba: \(error)")
        }
    }

Metoda validate() automaticky kontroluje stavový kód (200–299) a typ obsahu, vrací chybu při nestandardní odpovědi, což eliminuje ruční kontrolu statusCode. responseDecodable používá protokol Decodable pro automatickou deserializaci JSON do Swift struktury — eliminuje ruční JSONSerialization a snižuje množství boilerplate kódu při práci s REST API.

Zpracování odpovědí

Alamofire podporuje několik typů obsluhy odpovědí: response (surová data), responseJSON (slovník/pole), responseString (text), responseData (Data) a responseDecodable (Decodable model). Konvertory odpovědí lze vytvářet vlastní — pro protobuf, grafické formáty nebo vlastní protokoly.

Nahrávání a stahování souborů

Pro nahrávání dat na server se používá upload, který podporuje Data, File a MultipartFormData. Stahování velkých souborů se provádí pomocí download s možností obnovení prostřednictvím resumeData po přerušení nebo výpadku spojení. Obě operace podporují sledování průběhu pomocí uploadProgress a downloadProgress s desetinnými hodnotami od 0 do 1 pro zobrazení v uživatelském rozhraní.

Multipart nahrávání s Alamofire je obzvláště pohodlné: metoda upload(multipartFormData:) přijímá closure, ve kterém se části formuláře přidávají pomocí append. Každá část může obsahovat data, soubor nebo proud, stejně jako vlastní název a mime typ. Alamofire automaticky vypočítá hranice multipart a nastaví správnou hlavičku Content-Type, což zbavuje vývojáře ručního sestavování těla požadavku. Pro velké soubory se doporučuje použít streamování (stream provider) namísto načítání celého souboru do paměti — zabraňuje to překročení limitu paměti na mobilních zařízeních s omezenými zdroji. Typický scénář — odeslání avataru uživatele spolu s daty profilu v jednom multipart požadavku, což snižuje počet HTTP volání a zjednodušuje zpracování na straně serveru.

Alamofire vs URLSession

Srovnání Alamofire a nativního URLSession pomáhá při architektonickém rozhodování. Alamofire nenahrazuje URLSession — je postaveno nad ním a používá stejné mechanismy konfigurace, ukládání do mezipaměti a úloh na pozadí. Všechny funkce URLSession jsou k dispozici prostřednictvím Alamofire, ale s pohodlnější deklarativní syntaxí.

Ve velkých projektech Alamofire snižuje množství kódu pro síťové požadavky o 30–50% a zjednodušuje zpracování chyb. V malých projektech nebo při přísných požadavcích na velikost binárního souboru je nativní URLSession preferovanější kvůli absenci externích závislostí.

Moderní Alamofire 5 se integruje s Combine prostřednictvím vlastnosti publishDecodable, která vrací Publisher, umožňující vytváření reaktivních řetězců požadavků se zpracováním chyb a transformací dat. Pro async/await jsou k dispozici metody s příponou value — například AF.request(url).serializingDecodable(User.self).value, což činí syntaxi mimořádně stručnou a připomíná práci s nativním URLSession. Při použití async/await odpadá potřeba closure a zpracování chyb se provádí prostřednictvím standardních do-catch bloků Swift, což zjednodušuje údržbu kódu a jeho čitelnost z dlouhodobého hlediska.

Příklady kódu

Podívejme se na složitější příklad — požadavek se zachytávačem, který automaticky přidává autorizační token a provádí opakovaný pokus při chybě 401. To je typický scénář pro aplikace s JWT autentizací.

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)
        }
    }
}

Zachytávač AuthInterceptor implementuje dva protokoly: adapt (přidává token ke každému požadavku) a retry (pokouší se obnovit token při chybě 401). Metoda retry kontroluje stavový kód odpovědi a pokud je přijat 401, žádá o nový token prostřednictvím TokenManager. Po úspěšném obnovení je požadavek automaticky opakován.

Použití zachytávače s relací:

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

Všechny požadavky prostřednictvím této relace automaticky procházejí přes AuthInterceptor — token je přidán do hlaviček a při 401 dojde k obnovení a opakování. To eliminuje duplikaci autentizačního kódu v každém požadavku a centralizuje logiku práce s tokeny.