Alamofire: nedir, HTTP istemci işlevleri ve geliştirmede kullanımı

Alamofire nedir?

Alamofire, Apple platformlarında HTTP istekleriyle çalışmak için tamamen Swift ile yazılmış bir kütüphanedir. Geliştirme 2014 yılında Objective-C kütüphanesi AFNetworking'e alternatif olarak başladı ve hızla iOS topluluğunda ağ iletişimi standardı haline geldi.

Kütüphane, sistem çerçevesi URLSession üzerine inşa edilmiştir ve düşük seviyeli API'sini kısa ve öz yöntem zincirlerine soyutlar. Alamofire, URLSession'ın tüm özelliklerini destekler: arka plan oturumları, istek yakalayıcıları, SSL sertifikaları ve birden çok yanıt serileştirme yöntemi.

Swift Package Index'e göre Alamofire, GitHub'da 45.000'den fazla yıldızla en popüler 10 Swift paketi arasındadır. Kütüphane iOS 10+, macOS 10.12+, tvOS 10+ ve watchOS 3+ ile uyumludur.

Doğrudan URLSession kullanımına kıyasla Alamofire'in ana avantajı, kalıplaşmış kodun azaltılmasıdır. Tek bir AF.request çağrısı, 15–20 satır manuel URLRequest yapılandırması, yanıt işleme ve veri kod çözmenin yerini alır. Aynı zamanda kütüphane, özel oturumlar ve uzantılar aracılığıyla özel senaryolar için tam esneklik sağlar.

Alamofire'in temel özellikleri

Alamofire, çoğu mobil geliştirme senaryosunu kapsayan geniş bir ağ işlevleri yelpazesi sunar. Modüler mimarisi sayesinde geliştiricilerin yalnızca gerekli bileşenleri eklemesi yeterlidir.

Tüm HTTP yöntemlerinin desteği

HTTP yöntemleri GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS ve TRACE, tek tip bir API aracılığıyla uygulanır. Her yöntem, istek parametrelerini ve başlıklarını kabul eder ve Result türü olarak bir yanıt döndürür. Geliştiricinin URLRequest'i manuel olarak yapılandırması gerekmez — kütüphane, sağlanan argümanlara göre otomatik olarak yapar.

Sunucu yanıtı doğrulama

Alamofire'da yanıt doğrulama, verileri uygulamaya aktarmadan önce durum kodlarını ve yanıt içeriğini kontrol etmeye olanak tanır. Kütüphane, kapanışlar aracılığıyla özel doğrulama koşullarını destekleyerek hata yönetimi üzerinde tam kontrol sağlar. Varsayılan olarak yalnızca 200–299 durum kodları kontrol edilir.

Otomatik parametre kodlama

Parametreler, seçilen türe göre otomatik olarak kodlanır: GET istekleri için URL kodlaması ve POST için JSON kodlaması. Alamofire ayrıca Property List kodlamasını ve ParameterEncoder protokolü aracılığıyla özel kodlayıcıları destekleyerek biçimin herhangi bir sunucuya uyarlanmasına olanak tanır.

Oturum yönetimi ve yakalayıcılar

Alamofire'da oturum, zaman aşımlarını, SSL sertifikalarını, varsayılan HTTP başlıklarını ve proxy'leri yapılandırmaya olanak tanır. EventMonitor yakalayıcıları, istek yaşam döngüsü olaylarını (oluşturma, gönderme, yanıt alma ve tamamlama) izlemeyi sağlar. Bu, üretimde günlükleme, analiz ve ağ sorunlarını hata ayıklama için kullanışlıdır.

Alamofire nasıl çalışır?

Alamofire, bir URLSession örneğini ve ağ yapılandırmasını kapsülleyen Session tabanlı bir mimari kullanır. Her istek, bir işleyici zincirinden geçer: bağdaştırıcılar, yeniden deneme politikaları, doğrulayıcılar ve serileştiriciler, esneklik ve genişletilebilirlik sağlar.

Session ve Request modeli

Session nesnesi, uygulamadaki tüm ağ isteklerini yönetir. Zaman aşımları, varsayılan başlıklar ve sertifikalar içeren bir yapılandırmayla oluşturulur. Her AF.request çağrısı, gönderilmeden önce değiştirilebilen bir DataRequest döndürür. Alamofire, oturuma zayıf referanslar aracılığıyla otomatik olarak tutma döngülerini işleyerek bellek sızıntılarını önler.

import Alamofire

let session = Session(configuration: config)
session.request("https://api.example.com/users")
    .validate()
    .responseDecodable(of: [User].self) { response in
        switch response.result {
        case .success(let users):
            print("Alınan \(users.count) kullanıcı")
        case .failure(let error):
            print("Hata: \(error.localizedDescription)")
        }
    }

Alamofire kurulumu ve yapılandırması

Alamofire kurulumu, Swift Package Manager, CocoaPods veya Carthage aracılığıyla yapılır. Yeni projeler için önerilen yöntem, Xcode'a entegre olan SPM'dir, çünkü ek araç gerektirmez ve entegrasyon birkaç tıklamayla gerçekleşir.

Swift Package Manager ile

Xcode'da paket ekleme, File → Add Packages menüsü aracılığıyla yapılır. Depo URL'si: https://github.com/Alamofire/Alamofire. Sürümün en son kararlı sürüme sabitlenmesi önerilir. Alamofire anlamsal sürümleme izler ve tüm önemli değişiklikler CHANGELOG'da belgelenir.

CocoaPods ile

CocoaPods, mevcut altyapıya sahip projeler için popüler bir seçenek olmaya devam etmektedir. Podfile'ınıza pod 'Alamofire' satırını ekleyin ve pod install komutunu çalıştırın. Alamofire'ın harici bağımlılığı yoktur, bu da entegrasyonu basitleştirir ve mevcut projelerde sürüm çakışmalarını ortadan kaldırır.

Alamofire kullanım örnekleri

Aşağıdaki örnekler, iOS uygulamalarında Alamofire'ın tipik kullanım senaryolarını göstermektedir: basit GET isteklerinden ilerleme takibi ile dosya yüklemeye kadar.

GET isteği ve JSON yanıtı

Parametrelerle ve yanıtın Codable modeline kod çözülmesiyle basit bir GET isteği, mobil uygulamalarda Alamofire'ın en yaygın kullanım senaryosudur. Parametreler otomatik olarak kodlanır ve yanıt JSONDecoder aracılığıyla çözülür. Kod kompakt ve okunabilirdir.

struct User: Codable {
    let id: Int
    let name: String
    let email: String
}

AF.request("https://jsonplaceholder.typicode.com/users",
               method: .get)
    .validate()
    .responseDecodable(of: [User].self) { response in
        switch response.result {
        case .success(let users):
            print("Kullanıcılar: \(users.count)")
        case .failure(let error):
            print("Hata: \(error)")
        }
    }

JSON gövdesiyle POST isteği

JSON gövdesiyle POST isteği, sunucuda kaynak oluşturmak için kullanılır. Alamofire, JSONParameterEncoder aracılığıyla iletilen nesneyi otomatik olarak kodlayarak geliştiriciyi manuel serileştirmeden kurtarır. Yanıt, aynı JSONDecoder kullanılarak bir veri modeline çözülür.

let newUser = User(id: 1,
                     name: "Ahmet Yılmaz",
                     email: "ivan@example.com")

AF.request("https://jsonplaceholder.typicode.com/users",
               method: .post,
               parameters: newUser,
               encoder: JSONParameterEncoder.default)
    .validate()
    .responseDecodable(of: User.self) { response in
        if let created = response.value {
            print("Kullanıcı oluşturuldu: \(created)")
        }
    }

Medya yükleme

Alamofire'daki upload yöntemi, dosya, veri ve çok parçalı form yüklemelerini destekler. Kütüphane otomatik olarak ilerlemeyi yönetir ve uploadProgress kapanışları aracılığıyla yükleme durumunu izlemeye olanak tanır; bu, bir ilerleme göstergesi görüntülemek için kullanışlıdır.

let imageData = UIImage(named: "photo")?.jpegData(compressionQuality: 0.8)

AF.upload(imageData,
           to: "https://api.example.com/upload")
    .uploadProgress { progress in
        print("İlerleme: \(progress.fractionCompleted * 100)%")
    }
    .responseDecodable(of: UploadResponse.self) { response in
        print("Yükleme tamamlandı")
    }

Alamofire'de hata yönetimi ve doğrulama

Alamofire'da hata yönetimi, yanıt doğrulama ve Result türlerinin bir kombinasyonuna dayanır. Hata modeli, tipik ağ arıza senaryolarının tümünü kapsayan AFError'ı içerir: zaman aşımları, bağlantı kaybı, sunucu hataları ve başarısız serileştirme. Her durum ayrı ayrı ele alınır.

Bir hatadan sonra yeniden denemeler için Alamofire, RequestRetrier mekanizmasını sağlar. Bu protokol, yeniden deneme politikasını tanımlar: deneme sayısı, aralarındaki gecikme ve yeniden denemenin gerçekleştirildiği koşul. Örneğin, 503 sunucu hatasında istek 2 saniye sonra yeniden denenebilirken, 401 hatasında yeni bir kimlik doğrulama belirteci istenebilir.

Numaralandırma ile AFError yaklaşımı, geliştiricinin hiçbir hata türünü kaçırmamasını sağlar — derleyici, işlemenin bütünlüğünü kontrol eder. Bu, kodu ham URLSession'da NSError aracılığıyla hata yönetimine kıyasla daha güvenilir ve öngörülebilir kılar.

Yeniden deneme politikaları ve tekrarlanan istekler

RequestRetrier protokolü, isteği, oturumu, hatayı ve tamamlama kapanışını alan bir yeniden deneme yöntemi tanımlar. Bu yöntemde geliştirici, isteğin yeniden denenip denenmeyeceğine ve hangi gecikmeden sonra deneneceğine karar verir. Alamofire, yaygın senaryolar için yerleşik bir RetryPolicy uygulaması sağlar, ancak üretim kodu için iş mantığına dayalı özel politikalar oluşturulması önerilir.

AFError, farklı hata kategorileri için iç içe durumları olan bir numaralandırmadır. Geliştirici her türü ayrı ayrı işleyebilir: zaman aşımları için — isteği yeniden dene, sunucu hataları için — kullanıcıya anlaşılır bir mesaj göster. Alamofire, RequestRetrier protokolü aracılığıyla özel yeniden deneme politikalarını destekler.

Yerleşik doğrulama, 200–299 aralığındaki durum kodlarını ve yanıt içerik türünü kontrol eder. Genişletilmiş doğrulama için, validate kapanışı aracılığıyla özel koşullar eklenebilir; bu, verileri UI katmanına aktarmadan önce iş mantığı doğrulamasına olanak tanır.