Alamofire — ce este, client HTTP în Swift și cum funcționează

Ce este Alamofire?

Alamofire este un client HTTP pentru Swift, creat de Alamofire Software Foundation (inițial Mattt Thompson în 2014). Biblioteca abstrage detaliile de nivel scăzut ale URLSession, oferind o API curată și expresivă pentru comunicarea în rețea.

Filosofia de bază a Alamofire este sintaxa în lanț, în care parametrii cererii (URL, metodă, antete, parametri, codificator) sunt transmiși prin apeluri succesive. Acest lucru face codul mai lizibil și reduce probabilitatea erorilor legate de configurarea incorectă a URLRequest. Abordarea declarativă permite concentrarea pe ceea ce trebuie făcut, nu pe detaliile configurării conexiunii. Dezvoltatorul descrie rezultatul dorit, iar biblioteca preia munca de nivel scăzut cu rețeaua.

Biblioteca este susținută activ din 2014 și a trecut prin șapte versiuni majore. Alamofire 5, actuală pentru 2025–2026, include suport pentru Combine, async/await, convertoare de răspuns, EventMonitor pentru depanare și RequestInterceptor pentru interceptarea cererilor. Fiecare versiune majoră a adus îmbunătățiri semnificative: Alamofire 4 a adăugat suport Codable, Alamofire 5 — Combine Publishers și un sistem îmbunătățit de interceptare a cererilor.

Ecosistemul Alamofire include biblioteci suplimentare: AlamofireImage pentru încărcarea și cache-uirea imaginilor, AlamofireNetworkActivityIndicator pentru indicatorul de rețea în bara de stare iOS și AlamofireObjectMapper pentru integrarea cu ObjectMapper. Aceste componente fac din Alamofire un stack de rețea complet, nu doar un client HTTP.

Instalare și configurare

Alamofire se instalează prin Swift Package Manager (recomandat), CocoaPods sau Carthage. În Xcode, deschideți meniul File → Add Packages, inserați URL-ul depozitului și specificați versiunea.

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

// Import în fișier
import Alamofire

După instalare, Alamofire este disponibil global prin spațiul de nume AF (prescurtare de la Alamofire) fără configurare suplimentară. Majoritatea proiectelor încep prin configurarea Session cu propria configurație — aceasta permite setarea URL-ului de bază, antetelor standard, timeout-urilor și gestionarilor de certificate TLS.

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

Crearea propriei sesiuni prin Session(configuration:) este necesară când se dorește o configurație unică pentru diferite părți ale aplicației — de exemplu, o sesiune separată pentru încărcarea imaginilor cu cache agresiv și alta pentru cererile API cu autentificare. Sesiunea Alamofire acceptă nu doar configurația, ci și interceptor, serverTrustManager, cachedResponseHandler și redirectHandler, permițând controlul complet al comportamentului rețelei în toate etapele cererii.

Funcționalități principale

Alamofire oferă un set larg de funcții care acoperă majoritatea scenariilor de comunicare în rețea în aplicațiile iOS. Să analizăm cele mai importante.

Cereri HTTP

Sintaxa de bază a unei cereri include metoda, URL-ul, parametrii și encoding-ul. Toate metodele HTTP standard sunt suportate prin enum-ul HTTPMethod: get, post, put, patch, delete. Parametrii pot fi codificați ca parametri URL (URLEncoding), corp JSON (JSONEncoding) sau 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("Utilizator creat: \(user)")
        case .failure(let error):
            print("Eroare: \(error)")
        }
    }

Metoda validate() verifică automat codul de stare (200–299) și tipul de conținut, returnând o eroare la un răspuns non-standard, eliminând necesitatea verificării manuale a statusCode. responseDecodable folosește protocolul Decodable pentru deserializarea automată a JSON-ului într-o structură Swift — elimină JSONSerializarea manuală și reduce volumul de cod boilerplate la lucrul cu REST API.

Procesarea răspunsurilor

Alamofire suportă mai multe tipuri de gestionare a răspunsurilor: response (date brute), responseJSON (dicționar/array), responseString (text), responseData (Data) și responseDecodable (model Decodable). Convertoarele de răspuns pot fi create personalizate — pentru protobuf, formate grafice sau protocoale proprii.

Încărcarea și descărcarea fișierelor

Pentru încărcarea datelor pe server se folosește upload, care suportă Data, File și MultipartFormData. Descărcarea fișierelor mari se face prin download cu posibilitatea reluării prin resumeData după întreruperea conexiunii. Ambele operațiuni suportă urmărirea progresului prin uploadProgress și downloadProgress cu valori fracționate de la 0 la 1 pentru afișarea în interfața utilizatorului.

Încărcarea multipart cu Alamofire este deosebit de convenabilă: metoda upload(multipartFormData:) primește un closure în care părțile formularului sunt adăugate prin append. Fiecare parte poate conține date, fișier sau flux, precum și propriul nume și tip mime. Alamofire calculează automat limitele multipart și setează antetul Content-Type corect, eliminând formarea manuală a corpului cererii. Pentru fișiere mari, se recomandă utilizarea transmisiei în flux (stream provider) în locul încărcării întregului fișier în memorie — aceasta previne depășirea limitei de memorie pe dispozitivele mobile cu resurse limitate. Un scenariu tipic — trimiterea avatarului utilizatorului împreună cu datele profilului într-o singură cerere multipart, ceea ce reduce numărul de apeluri HTTP și simplifică procesarea pe server.

Alamofire vs URLSession

Comparația dintre Alamofire și URLSession nativ ajută la luarea deciziilor arhitecturale. Alamofire nu înlocuiește URLSession — este construit deasupra lui și folosește aceleași mecanisme de configurare, cache și sarcini de fundal. Toate funcționalitățile URLSession sunt disponibile prin Alamofire, dar cu o sintaxă declarativă mai convenabilă.

În proiectele mari, Alamofire reduce cantitatea de cod pentru cererile de rețea cu 30–50% și simplifică gestionarea erorilor. În proiectele mici sau cu cerințe stricte privind dimensiunea binarului, URLSession nativ este preferat datorită absenței dependențelor externe.

Alamofire 5 modern se integrează cu Combine prin proprietatea publishDecodable, care returnează un Publisher, permițând construirea de lanțuri reactive de cereri cu gestionarea erorilor și transformarea datelor. Pentru async/await sunt disponibile metode cu sufixul value — de exemplu, AF.request(url).serializingDecodable(User.self).value, ceea ce face sintaxa extrem de concisă și amintește de lucrul cu URLSession nativ. La utilizarea async/await, nu mai sunt necesare closure-uri, iar gestionarea erorilor se face prin blocurile standard do-catch din Swift, simplificând întreținerea codului și lizibilitatea pe termen lung.

Exemple de cod

Să analizăm un exemplu mai complex — o cerere cu un interceptor care adaugă automat tokenul de autorizare și reîncearcă la eroarea 401. Acesta este un scenariu tipic pentru aplicațiile cu autentificare 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)
        }
    }
}

Interceptorul AuthInterceptor implementează două protocoale: adapt (adaugă tokenul la fiecare cerere) și retry (încearcă să reînnoiască tokenul la eroarea 401). Metoda retry verifică codul de stare al răspunsului și, dacă se primește 401, solicită un nou token prin TokenManager. După reînnoirea cu succes, cererea se repetă automat.

Utilizarea interceptorului cu sesiunea:

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

Toate cererile prin această sesiune trec automat prin AuthInterceptor — tokenul este adăugat la antete, iar la 401 se face reînnoire și reîncercare. Acest lucru elimină duplicarea codului de autentificare în fiecare cerere și centralizează logica de lucru cu tokenurile.