Alamofire — nedir, Swift'te HTTP istemcisi ve nasıl çalışır

Alamofire nedir?

Alamofire, Alamofire Software Foundation (başlangıçta 2014'te Mattt Thompson) tarafından oluşturulan Swift için bir HTTP istemcisidir. Kütüphane, düşük seviyeli URLSession ayrıntılarını soyutlayarak ağ iletişimi için temiz ve anlamlı bir API sağlar.

Alamofire'ın temel felsefesi, istek parametrelerinin (URL, yöntem, başlıklar, parametreler, kodlayıcı) sıralı çağrılar aracılığıyla iletildiği zincirleme sözdizimidir. Bu, kodu daha okunabilir hale getirir ve yanlış URLRequest yapılandırmasıyla ilgili hata olasılığını azaltır. Bildirimsel yaklaşım, bağlantı kurulumunun ayrıntıları yerine ne yapılması gerektiğine odaklanmayı sağlar. Geliştirici istenen sonucu tanımlar ve kütüphane düşük seviyeli ağ işini halleder.

Kütüphane 2014'ten beri aktif olarak bakımı yapılmakta ve yedi ana sürümden geçmiştir. 2025–2026 itibarıyla güncel olan Alamofire 5, Combine, async/await, yanıt dönüştürücüler, hata ayıklama için EventMonitor ve istekleri yakalamak için RequestInterceptor desteğini içerir. Her ana sürüm önemli iyileştirmeler getirmiştir: Alamofire 4, Codable desteği ekledi, Alamofire 5, Combine Publishers ve geliştirilmiş bir istek yakalama sistemi ekledi.

Alamofire ekosistemi ek kütüphaneler içerir: AlamofireImage görüntü yükleme ve önbellekleme için, AlamofireNetworkActivityIndicator iOS durum çubuğundaki ağ göstergesi için ve AlamofireObjectMapper ObjectMapper ile entegrasyon için. Bu bileşenler, Alamofire'ı sadece bir HTTP istemcisi değil, tam teşekküllü bir ağ yığını haline getirir.

Kurulum ve yapılandırma

Alamofire, Swift Package Manager (önerilen), CocoaPods veya Carthage aracılığıyla kurulur. Xcode'da, File → Add Packages menüsünü açmanız, depo URL'sini yapıştırmanız ve sürümü belirtmeniz yeterlidir.

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

// Dosyaya aktar
import Alamofire

Kurulumdan sonra Alamofire, ek yapılandırma gerektirmeden AF ad alanı (Alamofire'ın kısaltması) aracılığıyla genel olarak kullanılabilir. Çoğu proje, kendi yapılandırmalarıyla bir Session ayarlayarak başlar — bu, temel URL, varsayılan başlıklar, zaman aşımları ve TLS sertifika işleyicileri ayarlamaya olanak tanır.

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

Session(configuration:) aracılığıyla özel bir oturum oluşturmak, uygulamanın farklı bölümleri için benzersiz bir yapılandırma gerektiğinde gereklidir — örneğin, agresif önbellekleme ile görüntü indirmeleri için ayrı bir oturum ve kimlik doğrulama ile API istekleri için başka bir oturum. Alamofire Session yalnızca yapılandırmayı değil, aynı zamanda bir interceptor, serverTrustManager, cachedResponseHandler ve redirectHandler'ı da kabul ederek isteğin tüm aşamalarında ağ davranışı üzerinde tam kontrol sağlar.

Temel özellikler

Alamofire, iOS uygulamalarındaki çoğu ağ etkileşimi senaryosunu kapsayan geniş bir işlev yelpazesi sunar. Temel özelliklere bakalım.

HTTP İstekleri

Temel istek sözdizimi, yöntem, URL, parametreler ve kodlamayı içerir. HTTPMethod enum'u aracılığıyla tüm standart HTTP yöntemleri desteklenir: get, post, put, patch, delete. Parametreler, URL parametreleri (URLEncoding), JSON gövdesi (JSONEncoding) veya çok parçalı form verileri (MultipartFormData) olarak kodlanabilir.

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("Kullanıcı tarafından oluşturuldu: \(user)")
        case .failure(let error):
            print("Hata: \(error)")
        }
    }

validate() yöntemi, durum kodunu (200–299) ve içerik türünü otomatik olarak kontrol eder, beklenmeyen yanıtlarda hata döndürerek manuel statusCode kontrolünü ortadan kaldırır. responseDecodable, JSON'u Swift yapılarına otomatik olarak dönüştürmek için Decodable protokolünü kullanır — bu, manuel JSONSerialization'ı ortadan kaldırır ve REST API'leri ile çalışırken kalıp kodu azaltır.

Yanıt İşleme

Alamofire, çeşitli yanıt işleyici türlerini destekler: response (ham veri), responseJSON (sözlük/dizi), responseString (metin), responseData (Data) ve responseDecodable (Decodable model). Yanıt dönüştürücüler özelleştirilebilir — protobuf, grafik formatları veya özel protokoller için.

Dosya Yükleme ve İndirme

Sunucuya veri yüklemek için upload kullanılır ve Data, File ile MultipartFormData'yı destekler. Büyük dosyaların indirilmesi, bağlantı kesintisinden sonra resumeData aracılığıyla devam ettirme özelliği ile download üzerinden yapılır. Her iki işlem de kullanıcı arayüzünde görüntülemek için 0'dan 1'e kesirli değerlerle uploadProgress ve downloadProgress aracılığıyla ilerleme takibini destekler.

Alamofire ile çok parçalı yükleme özellikle kullanışlıdır: upload(multipartFormData:) yöntemi, append aracılığıyla form parçalarının eklendiği bir closure alır. Her parça, veri, dosya veya akışın yanı sıra kendi adı ve mime türünü içerebilir. Alamofire, çok parçalı sınırları otomatik olarak hesaplar ve doğru Content-Type başlığını ayarlayarak geliştiricinin istek gövdesini manuel olarak oluşturmasını engeller. Büyük dosyalar için, dosyanın tamamını belleğe yüklemek yerine akış sağlayıcıları kullanılması önerilir — bu, kaynakları sınırlı mobil cihazlarda bellek sınırının aşılmasını önler. Tipik bir senaryo, tek bir çok parçalı istekte profil verileriyle birlikte kullanıcı avatarı göndermektir; bu, HTTP çağrılarının sayısını azaltır ve sunucu tarafı işlemeyi basitleştirir.

Alamofire vs URLSession

Alamofire'ı yerel URLSession ile karşılaştırmak, mimari kararlar almaya yardımcı olur. Alamofire, URLSession'ın yerini almaz — onun üzerine inşa edilir ve aynı yapılandırma, önbellekleme ve arka plan görev mekanizmalarını kullanır. URLSession'ın tüm özelliklerine Alamofire aracılığıyla erişilebilir, ancak daha kullanışlı bir bildirimsel sözdizimi ile.

Büyük projelerde, Alamofire ağ isteği kodunu %30–50 oranında azaltır ve hata yönetimini basitleştirir. Küçük projelerde veya ikili dosya boyutunun katı bir kısıtlama olduğu durumlarda, harici bağımlılıkların olmaması nedeniyle yerel URLSession tercih edilir.

Modern Alamofire 5, bir Publisher döndüren publishDecodable özelliği aracılığıyla Combine ile entegre olur ve hata yönetimi ve veri dönüşümü ile reaktif istek zincirleri oluşturmayı sağlar. async/await için, value sonekine sahip yöntemler mevcuttur — örneğin, AF.request(url).serializingDecodable(User.self).value, sözdizimini son derece özlü hale getirir ve yerel URLSession ile çalışmayı anımsatır. async/await kullanıldığında, closure'lara artık gerek kalmaz ve hata yönetimi standart Swift do-catch blokları aracılığıyla yapılır, uzun vadede kod bakımını ve okunabilirliği basitleştirir.

Kod örnekleri

Daha karmaşık bir örneğe bakalım — otomatik olarak bir yetkilendirme tokenı ekleyen ve 401 hatasında yeniden deneme yapan bir yakalayıcı ile istek. Bu, JWT kimlik doğrulaması kullanan uygulamalar için tipik bir senaryodur.

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 iki protokol uygular: adapt (her isteğe token ekler) ve retry (401 hatasında token'ı yenilemeyi dener). retry yöntemi, yanıt durum kodunu kontrol eder ve 401 alınırsa TokenManager aracılığıyla yeni bir token ister. Başarılı yenilemeden sonra istek otomatik olarak yeniden dener.

Bir oturumla yakalayıcı kullanma:

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

Bu oturum aracılığıyla yapılan tüm istekler otomatik olarak AuthInterceptor'dan geçer — başlıklara token eklenir ve 401'de yenileme ve yeniden deneme yapılır. Bu, her istekte kimlik doğrulama kodu tekrarını ortadan kaldırır ve token yönetimi mantığını merkezileştirir.